{"slug": "how-to-use-openai-codex-with-a-visual-workspace", "title": "How to Use OpenAI Codex with a Visual Workspace", "summary": "OpenAI Codex can be used with a visual workspace like Nimbalyst to move beyond terminal-based sessions, enabling users to review diffs, plan features in markdown, and run multiple sessions in parallel. The process involves installing the Codex CLI, setting up a visual workspace, and writing a detailed AGENTS.md file to guide the AI. This approach improves efficiency for developers managing complex, multi-step coding tasks.", "body_md": "# How to Use OpenAI Codex with a Visual Workspace\n\nStep-by-step guide to using OpenAI Codex with a visual workspace: install the CLI, set AGENTS.md, run sessions in Nimbalyst, review diffs, and plan in markdown.\n\nOpenAI’s Codex CLI is fast and powerful out of the box, but the terminal is a thin surface for real work. Once you are reviewing more than a handful of diffs a day, planning multi-step features, or running more than one Codex session at a time, you start to want a visual workspace around the agent.\n\nThis guide walks through how to use OpenAI Codex with a visual workspace from setup to a full review-and-ship loop. The walkthrough uses [Nimbalyst](/codex-gui/), an open-source workspace that runs Codex as a first-class engine, but most of the patterns translate to any Codex GUI.\n\n## What you will be able to do at the end\n\n- Run Codex sessions inside a visual editor instead of a terminal\n- Edit\n`AGENTS.md`\n\nin WYSIWYG markdown with inline AI diffs - Review every Codex change file by file, accept or reject inline\n- Run several Codex sessions in parallel, each on its own branch\n- Plan features in markdown documents the agent reads from\n- Monitor sessions from your phone while you are away from the laptop\n\n## Step 1. Install the Codex CLI\n\nThe visual workspace runs the actual Codex CLI under the hood, so install it first.\n\n```\nnpm install -g @openai/codex\ncodex --version\n```\n\nAuthenticate with your OpenAI API key or sign in with your ChatGPT plan.\n\n```\ncodex login\n```\n\nVerify Codex works in a small repo before adding the visual layer:\n\n```\ncd ~/some-test-repo\ncodex\n```\n\nIf you get a working session, the engine is fine. Now you can wrap it.\n\n## Step 2. Install the visual workspace\n\nDownload Nimbalyst for macOS, Windows, or Linux from [the download page](/download/), or build from source on GitHub. The desktop app is MIT licensed and free for individual use.\n\nAfter installing, open Nimbalyst and add your project folder. The workspace detects your `AGENTS.md`\n\n, your `.git`\n\ndirectory, and any existing Codex configuration automatically.\n\n## Step 3. Write a real AGENTS.md\n\nThe biggest single quality jump for Codex sessions comes from a well-written `AGENTS.md`\n\n. This is the file Codex reads at the start of every session. Treat it like onboarding documentation for a new engineer.\n\nIn the workspace, open `AGENTS.md`\n\nin the WYSIWYG markdown editor. Write something like:\n\n```\n# AGENTS.md\n\n## Project context\nThis is a TypeScript Astro site deployed to Cloudflare Pages.\nContent lives in src/content/, components in src/components/.\n\n## Conventions\n- Tailwind utility classes only, no inline style attributes\n- All copy lives in src/data/*.yaml, not in component files\n- Run `npm run build` before declaring a task done\n\n## Commands\n- `npm run dev` for local preview (do not run, the user does that)\n- `npm run build` for production build with Pagefind indexing\n\n## Out of scope\n- Do not modify .env or wrangler.toml\n- Do not add client-side JS frameworks\n```\n\nIn a visual editor you can ask Codex itself to draft or refine `AGENTS.md`\n\n. Every change is shown as an inline red and green diff before it lands, so you keep editorial control without leaving the document.\n\n## Step 4. Start a Codex session in the workspace\n\nIn Nimbalyst, open a new session and pick Codex as the engine. Type a prompt the way you would in the terminal:\n\n```\nAdd a `Last updated` line under each blog post title using the post's\n`updated` frontmatter field if present, falling back to `date`.\n```\n\nThe session opens with a chat panel on one side and your file tree on the other. As Codex works, files it touches appear in a per-session “files edited” sidebar. No more searching `git status`\n\nto figure out what changed.\n\n## Step 5. Review every diff visually\n\nThis is the part that makes the visual workspace pay for itself.\n\nWhen Codex finishes (or pauses to ask a question), open the diff viewer. Every file Codex touched appears as a red-and-green inline diff. You can:\n\n- Accept a file’s changes whole\n- Reject changes you do not like\n- Edit a change inline and re-run the agent against the corrected file\n\nFor markdown changes, the diff is shown in the rendered document, not the raw markdown. For mockups or diagrams, the diff is visual: you see the actual UI or graph change, not JSON. For data models, you see schema changes drawn out, not raw Prisma.\n\nThis is the workflow Codex’s terminal output does not give you. It is the difference between “trust and merge” and “review and ship.”\n\n## Step 6. Run a second Codex session in parallel\n\nOpen a new session. Pick Codex again. Optionally enable “git worktree” to run this session on its own checkout in a sibling directory, isolated from the first.\n\nNow you have two Codex agents running in the same project, each on its own branch, each visible on the kanban board with status, current file, and last action. Repeat for as many sessions as you want.\n\nA common pattern:\n\n- Session A: large refactor on a feature branch\n- Session B: small bug fix on a hotfix branch\n- Session C: scaffolding a new component on its own branch\n- Session D: writing tests for the merged refactor\n\nThe kanban shows you which sessions need input, which finished, and which crashed.\n\n## Step 7. Plan features in markdown the agent reads from\n\nFor anything bigger than a one-shot prompt, write a plan document. In the workspace, create `plans/feature-name.md`\n\nand structure it:\n\n```\n# Feature: User profile page\n\n## Goal\nAdd a profile page at /u/[username] showing the user's avatar, bio, and last 10 sessions.\n\n## Constraints\n- Must use existing auth middleware\n- Must work with our existing Prisma schema, no migrations\n- Must pass type check and tests before merge\n\n## Tasks\n- [ ] Add the route\n- [ ] Add the data loader\n- [ ] Add the component\n- [ ] Add the test\n```\n\nThen start a Codex session and tell it to “execute the plan in `plans/user-profile.md`\n\n, marking each task as you finish it.” Codex updates the plan in place as it works, and the diff viewer shows the checkbox flips and any new sub-tasks the agent added.\n\n## Step 8. Monitor from your phone\n\nIf your workspace ships a mobile companion (Nimbalyst has an iOS app), pair it with your desktop. From your phone you can:\n\n- See which Codex sessions are running, paused, or done\n- Review diffs and accept or reject changes\n- Answer Codex prompts when an agent needs input\n- Start new sessions\n\nThe point is not “code from the toilet.” The point is that an agent that finishes while you are in a meeting does not have to sit idle until you are back at your laptop.\n\n## Common questions\n\n**Do I still need the Codex CLI installed?** Yes. The visual workspace runs the real CLI under the hood. Your existing CLI auth, AGENTS.md, and approval policies all still apply.\n\n**Does this work with the official Codex desktop app?** They are different tools. The official app is a clean Codex-only chat GUI. Nimbalyst is a multi-engine visual workspace that adds editors, diff review, planning, and Linux support. You can use both if you want.\n\n**What about Claude Code?** The same workspace runs Claude Code. Pick whichever engine fits the task: Codex for fast scaffolding, Claude Code for deep refactors. See [Claude Code vs Codex CLI: when to use which](/blog/claude-code-vs-codex-cli-when-to-use-which/).\n\n**Is it free?** The Nimbalyst desktop app is free for individual use and open source under MIT. You bring your own OpenAI API key for Codex.\n\n## Where to go next\n\n## Related posts\n\n-\n### How to Run Multiple Codex Agents in Parallel\n\nRun multiple Codex agents in parallel with git worktrees, the official Codex app, terminal multiplexers, or a kanban workspace. Commands and tradeoffs.\n\n-\n### Best Codex GUI 2026: 4 Codex Desktop Apps Compared\n\nThe best Codex GUI in 2026. OpenAI Codex App, CodexMonitor, CloudCLI, and Nimbalyst compared on parallel sessions, worktrees, and platforms.\n\n-\n### Codex CLI Tips and Workflows to Get You Started\n\nPractical tips, workflows, and configuration for OpenAI Codex CLI: AGENTS.md setup, approval policies, cloud sandboxes, and GitHub integration.", "url": "https://wpnews.pro/news/how-to-use-openai-codex-with-a-visual-workspace", "canonical_source": "https://nimbalyst.com/blog/how-to-use-openai-codex-with-visual-workspace/", "published_at": "2026-05-12 00:00:00+00:00", "updated_at": "2026-05-26 14:16:09.717402+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "ai-products", "ai-infrastructure", "large-language-models"], "entities": ["OpenAI", "Codex CLI", "Nimbalyst", "Codex GUI", "AGENTS.md"], "alternates": {"html": "https://wpnews.pro/news/how-to-use-openai-codex-with-a-visual-workspace", "markdown": "https://wpnews.pro/news/how-to-use-openai-codex-with-a-visual-workspace.md", "text": "https://wpnews.pro/news/how-to-use-openai-codex-with-a-visual-workspace.txt", "jsonld": "https://wpnews.pro/news/how-to-use-openai-codex-with-a-visual-workspace.jsonld"}}