{"slug": "how-to-run-multiple-codex-agents-in-parallel", "title": "How to Run Multiple Codex Agents in Parallel", "summary": "OpenAI Codex users can run multiple agents in parallel using git worktrees, terminal multiplexers, or the official Codex desktop app to avoid branch collisions and speed up workflows. The approach allows developers to run separate sessions for refactoring, bug fixes, testing, and scaffolding simultaneously rather than waiting for one agent to finish. Each method has tradeoffs in visibility, cleanup requirements, and approval management.", "body_md": "# 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\nA single Codex agent is fast, but most developers using Codex seriously end up wanting more than one running at the same time. One session refactoring auth, one fixing a bug, one writing tests, one scaffolding a new component. The hard part is keeping them from stepping on each other’s branches, terminals, and approvals.\n\nThis guide covers the four practical ways to run multiple [OpenAI Codex](/codex-gui/) agents in parallel today, with the actual commands, tradeoffs, and the workflows that hold up past a few sessions.\n\n## Why parallel Codex agents matter\n\nThe model is rarely your bottleneck once you have the workflow tuned. Your bottleneck is usually that one Codex session can only execute one stream of work at a time, while you almost always have more than one stream of work to do. Running agents in parallel turns “wait for the agent to finish” into “wait for me to finish reviewing.”\n\nThree patterns where parallel sessions pay off immediately:\n\n**Fan-out scaffolding.** Spin up three sessions to write tests for three different modules.**Long task plus quick wins.** Start a long refactor in one session, fire off small bug fixes in others while it runs.**Branch isolation.** Run sessions on separate branches so one agent’s edits never collide with another’s.\n\nThe mechanics differ depending on which harness you use.\n\n## Option 1. Git worktrees plus multiple terminals\n\nThe lowest-tech way and the one every other approach builds on. Git worktrees let you check out the same repo into multiple sibling directories, each on its own branch. Each Codex session gets its own working tree, so file edits never collide.\n\n```\n# From your main repo\ngit worktree add ../myapp-feature-auth feature/auth\ngit worktree add ../myapp-bugfix-login bugfix/login\ngit worktree add ../myapp-scaffold-tests scaffold/tests\n\n# Open three terminal windows\ncd ../myapp-feature-auth && codex\ncd ../myapp-bugfix-login && codex\ncd ../myapp-scaffold-tests && codex\n```\n\nTradeoffs:\n\n**Good:** zero new tools. Works with vanilla Codex CLI today.**Bad:** no shared status view. To check on session 3 you have to switch to that terminal. Approval prompts can pile up unseen in a window you are not looking at.**Bad:** you are responsible for cleanup.`git worktree remove`\n\nand merging branches are manual.\n\nThis is the right starting point if you want to understand parallelism in Codex before adding any new tooling.\n\n## Option 2. Terminal multiplexer (tmux, Zellij, Warp)\n\nSame worktree pattern, but with a multiplexer keeping all sessions visible in one terminal window.\n\n```\n# Inside tmux\ntmux new-session -d -s codex\ntmux split-window -h\ntmux split-window -v\ntmux select-pane -t 0 && tmux send 'cd ../myapp-feature-auth && codex' Enter\ntmux select-pane -t 1 && tmux send 'cd ../myapp-bugfix-login && codex' Enter\ntmux select-pane -t 2 && tmux send 'cd ../myapp-scaffold-tests && codex' Enter\n```\n\nTradeoffs:\n\n**Good:** you can see all panes at once and switch with a keyboard shortcut.**Good:** tmux survives a closed terminal, so sessions keep running if your shell crashes.**Bad:** still terminal-only. Diff review is still raw text.**Bad:** approval prompts still per-pane.\n\nTools like Claude Squad take this pattern further by automating the worktree-plus-multiplexer setup. If you live in the terminal, that is a real improvement over hand-rolled tmux.\n\n## Option 3. The official Codex desktop app\n\nOpenAI’s Codex desktop app supports running multiple Codex agents in parallel out of the box, with built-in worktree support and a project-and-thread organization. On macOS and Windows, this is the cleanest first-party option.\n\nWhat you get:\n\n- Native parallel sessions inside one app\n- Built-in worktree per thread\n- Diff review and comment threads on changes\n- Shared history with the CLI\n\nWhat you do not get:\n\n- Linux support\n- Anything other than Codex (no Claude Code, Gemini, etc.)\n- Visual editors for markdown, mockups, or diagrams\n- A planning surface that the agent can read from and write back to\n\nFor Codex-only, single-platform teams, this is often the right answer. It is good software and it is officially supported.\n\n## Option 4. A multi-engine visual workspace\n\nThe fourth option is a workspace built around parallel agents from the start. Tools in this category run real Codex (and usually other engines) under the hood, but add a kanban view, per-session diff review, and structured planning around it.\n\nUsing [Nimbalyst as a Codex workspace](/codex-gui/) as the example:\n\n- Open the project folder once.\n- Click “New session,” pick Codex as the engine, and optionally toggle “git worktree” to isolate this session in a sibling checkout. Repeat for as many sessions as you need.\n- The kanban shows all sessions across phases (planning, in-progress, needs review, done) with the current file each agent is touching.\n- When a session completes, its diffs land in the visual diff viewer. Approve or reject inline, file by file.\n- Plans live as markdown documents in the same workspace. Codex reads from them and writes status back. The diff review covers the plan updates too.\n- An iOS companion lets you check status, accept diffs, and answer agent prompts when you are away from the laptop.\n\nTradeoffs:\n\n**Good:** all sessions visible at once, no terminal switching.**Good:** mixed engines. Run a Codex session and a Claude Code session in the same project, on the same kanban.**Good:** diff review is visual, not raw text. Markdown changes are shown in the rendered document, mockups as visual diffs, code as inline file diffs.**Good:** Linux support, where the official Codex app does not run.**Trade-off:** another app to install. If you are happy with the official Codex app on macOS and never want to leave it, you do not need this.\n\n## Choosing between the four\n\n| Use case | Best option |\n|---|---|\n| One-off, just want to try parallel | Worktrees + terminals |\n| Heavy terminal user, want one window | tmux or Claude Squad |\n| Codex only, on macOS or Windows, single-engine work | Official Codex desktop app |\n| Codex + Claude Code, parallel sessions, visual review | Visual workspace (Nimbalyst) |\n| Linux developer who wants Codex in a desktop app | Visual workspace (Nimbalyst) |\n| Want to plan and execute in the same place | Visual workspace (Nimbalyst) |\n\n## Tips that apply to every approach\n\nA few patterns hold across all four options.\n\n### Always use worktrees, not branches in one checkout\n\nIf two Codex sessions edit files in the same checkout, you will lose work. Worktrees give each agent its own physical directory, so concurrent file edits cannot collide. Every option above either supports worktrees natively or works trivially on top of them.\n\n### Write a strong AGENTS.md\n\nThe single biggest quality jump for parallel sessions comes from a thorough `AGENTS.md`\n\nat the repo root. Each new session reads it on startup. The better it is, the less drift across sessions. Include:\n\n- Project conventions (style, file layout, frameworks)\n- Out-of-scope files and folders\n- Commands the agent should and should not run\n- Test and build commands\n\n### Cap the number of concurrent sessions\n\nSix is a soft ceiling for most developers. Past that, you spend more time reviewing than producing. Watch your “needs review” queue. If it is growing faster than you can drain it, run fewer sessions in parallel.\n\n### Set sandbox and approval policies\n\nParallel sessions multiply the chances that some agent runs a command you would not approve. Configure Codex’s approval policy per project so destructive operations require explicit review even when you are not looking. The visual workspaces surface approval prompts in one place; the terminal options spread them across windows.\n\n### Review diffs visually if you can\n\nReading parallel terminal output for four agents at once does not scale. Even if you stay on the CLI for execution, find a way to view diffs in a real diff viewer (a workspace, an IDE, or `git difftool`\n\non each branch). Reviewing in raw terminal text is where bugs sneak in.\n\n## Where to go next\n\n## Related posts\n\n-\n### 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\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### Best Tools for Parallel AI Coding Agents (2026)\n\nCompare the best tools for running multiple Claude Code and Codex sessions in parallel — ccmanager, dmux, Superset, agentree, and Nimbalyst.", "url": "https://wpnews.pro/news/how-to-run-multiple-codex-agents-in-parallel", "canonical_source": "https://nimbalyst.com/blog/how-to-run-multiple-codex-agents-in-parallel/", "published_at": "2026-05-14 00:00:00+00:00", "updated_at": "2026-05-26 14:16:02.943345+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-products", "ai-infrastructure", "large-language-models"], "entities": ["OpenAI Codex"], "alternates": {"html": "https://wpnews.pro/news/how-to-run-multiple-codex-agents-in-parallel", "markdown": "https://wpnews.pro/news/how-to-run-multiple-codex-agents-in-parallel.md", "text": "https://wpnews.pro/news/how-to-run-multiple-codex-agents-in-parallel.txt", "jsonld": "https://wpnews.pro/news/how-to-run-multiple-codex-agents-in-parallel.jsonld"}}