Orchestrating Claude Code and Codex Together: A Power User Guide

A new power-user guide explains how to run Anthropic's Claude Code and OpenAI's Codex side by side using existing subscriptions, with sign-in via browser flows instead of API keys, shared project instructions via AGENTS.md and CLAUDE.md, and per-agent permission settings. The guide recommends a cross-review handoff pattern where one agent writes and the other reviews, and warns that an ANTHROPIC_API_KEY in the environment can accidentally bill API usage instead of a subscription.

Orchestrating Claude Code and Codex Together: A Power User Guide Run Claude Code and Codex side by side on the plans you already pay for: signing in without API keys, one set of project instructions both agents read, permission settings per agent, and the handoff patterns that make two agents better than one. The most common request we see from people setting up a coding-agent workflow is for one place to run the agents they already pay for, rather than for a new model or a new feature. In their words: the Codex desktop app and the Claude Code desktop app, merged together, on their actual memberships rather than a metered API key. The two agents do work well together, and the setup is not complicated once you know which pieces need to be duplicated and which can be shared. This guide covers signing both in on subscription access, giving them one set of project instructions, setting their permissions deliberately, and the handoff patterns that make running both worth the extra setup. Quick answer Sign in, do not paste keys. claude opens a browser sign-in against your Anthropic account. codex login does the same for your ChatGPT account. Watch for a stray API key. An ANTHROPIC API KEY sitting in your environment changes which account gets billed. Claude Code asks before using it; read the prompt. Share one instructions file. Codex reads AGENTS.md . Claude Code reads CLAUDE.md . Point one at the other with a single @AGENTS.md line instead of maintaining both. Set permissions per agent, in a file. Codex uses approval policy and sandbox mode in ~/.codex/config.toml . Claude Code uses permission modes and settings.json . The best two-agent pattern is cross-review. One agent writes, the other reviews the diff with no memory of having written it. Route by your own results. Model versions move faster than any comparison you read, including this one. Step 1: sign both agents in on the plans you already have Claude Code Install, then run it in a project and follow the browser prompts: curl -fsSL https://claude.ai/install.sh | bash macOS, Linux, WSL claude --version claude Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access. One thing to check before you sign in. If ANTHROPIC API KEY is set in your environment, Claude Code prompts you once to approve that key rather than opening the browser flow. If you meant to use your subscription, decline, and make sure the variable is not exported by your shell profile or a .env file the terminal sourced. This is the most common way people end up billing agent work to an API account they forgot they had configured. Confirm your setup with: claude doctor Codex has the same diagnostic as codex doctor , which checks installation, config, auth, and runtime health without starting a session. Run both once after setup and you will catch a broken install before an agent does. Codex Install, then sign in: curl -fsSL https://chatgpt.com/codex/install.sh | sh codex login opens the browser flow for your ChatGPT account codex login status shows the active authentication method Codex caches credentials at ~/.codex/auth.json or in your operating system’s credential store. If it is the file, treat it like a password: it holds access tokens, so keep it out of commits, tickets, and screen shares. codex logout clears it. If you deliberately want API-key billing for a particular machine, Codex makes that an explicit act rather than something it picks up from your environment: printenv OPENAI API KEY | codex login --with-api-key . Anything short of running that command leaves you on the account you signed in with. OpenAI determines which ChatGPT plans include Codex usage and what the allowances are, and those change. Check OpenAI’s own page on using Codex with your ChatGPT plan https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan rather than trusting a number in any article, including this one. Step 2: give both agents the same project instructions This is where two-agent setups quietly go wrong. You write a careful instructions file, one agent follows it, and the other does not, and it takes a week to notice that only half your sessions know the test command. Codex reads AGENTS.md . Generate a starting one from inside a session with /init . Claude Code reads CLAUDE.md , and it does not read AGENTS.md . Rather than maintaining two files that drift apart, make AGENTS.md the source and import it: @AGENTS.md Claude Code Use plan mode for changes under src/billing/ . The import loads at session start, and anything you write below it is appended, which is where Claude-specific instructions belong. A symlink works too when you have nothing agent-specific to add: ln -s AGENTS.md CLAUDE.md On Windows, use the @AGENTS.md import rather than the symlink, since symlink creation needs Administrator privileges or Developer Mode. What belongs in the shared file: build and test commands, the directory layout, conventions that differ from the language’s defaults, and the mistakes you have already had to correct twice. What does not: anything the agent can read off the codebase in ten seconds. Both agents pay context for every line, and adherence drops as the file grows. Step 3: set each agent’s permissions deliberately Two agents with different defaults produce work you trust unevenly, usually without realising why. Codex takes an approval policy and a sandbox mode, in ~/.codex/config.toml for your defaults and .codex/config.toml inside a repository for project-specific overrides: model = "gpt-5.6" approval policy = "on-request" sandbox mode = "workspace-write" approval policy accepts "untrusted" , "on-request" , and "never" . sandbox mode accepts "read-only" , "workspace-write" , and "danger-full-access" . The same values are available as flags for a single run, which is how you make one session stricter than your default without editing config: codex --sandbox read-only --ask-for-approval untrusted Named profiles are separate files layered on top of the base user config. codex --profile <name loads $CODEX HOME/<name .config.toml , and CODEX HOME defaults to ~/.codex . Set up a read-only reviewing profile on day one, because a reviewing agent has no reason to be able to write: ~/.codex/review.config.toml sandbox mode = "read-only" approval policy = "never" Start it with codex --profile review . The base ~/.codex/config.toml keeps your normal working defaults, and the profile only carries the values that differ. Check what is actually in effect inside a session with /status , and change it mid-session with /permissions . Claude Code uses permission modes and a settings.json at user, project, or local scope. The mode a session starts in, and the allow and deny rules that apply, are worth setting once per project rather than answering the same prompt fifty times. For anything that must hold regardless of what the agent decides, use a hook rather than an instruction, because instructions are context and hooks are enforcement. Step 4: route work between them The temptation is a fixed rule: this agent for refactors, that one for tests. Fixed rules go stale, because both vendors ship model updates faster than anyone republishes their comparison. What holds up is a routing habit rather than a routing table. Run the same task on both, once, in your own codebase. Two worktrees, same prompt, compare the diffs. One afternoon of this tells you more about your stack than any benchmark, and the answer will be specific to your language, your test suite, and how good your instructions file is. Re-check after a model release. A routing rule set six months ago is describing models that no longer exist. Split by failure mode, not by task type. If one agent tends to over-edit in your codebase and the other tends to stop short, that difference is stable and useful even as capability moves. Give the over-editor tightly scoped tasks and the cautious one the ambiguous ones. For a current side-by-side, see Claude Code vs Codex CLI: when to use which https://nimbalyst.com/blog/claude-code-vs-codex-cli-when-to-use-which/ and the fuller Codex vs Claude Code head-to-head https://nimbalyst.com/blog/codex-vs-claude-code-workflow-harness/ . Step 5: the handoff patterns worth learning Cross-agent review The highest-value pattern, and the reason to run two agents rather than two sessions of one. An agent reviewing its own work is checking against the same assumptions that produced the work. An agent that has never seen the conversation reviews the code as code. Implement in one worktree with Claude Code. Then run Codex’s reviewer against the same worktree. It is a top-level command, so there is no session to steer and nothing to prompt: codex --cd ../myapp-auth review --base main --uncommitted reviews staged, unstaged, and untracked changes instead, and --commit <sha reviews a single commit. Add a custom instruction as a positional argument when you want the reviewer pointed at something specific, such as codex review --base main "focus on the error handling and the deleted tests" . Going the other direction, implement with Codex and ask Claude Code to review the branch in a session started with read-only permissions. Swap the roles on the next task so you are not systematically trusting one agent’s blind spots. The reviews are worth reading even when they are wrong. A confident objection to code that is actually correct usually means the code is unclear, which is a finding of its own. Plan with one, implement with the other Have the first agent produce a written plan, in a file, as its whole output. Read it and correct it yourself. Then start the second agent fresh with the plan as its brief. The value comes from the plan becoming an artifact you reviewed before any code existed, which is the cheapest possible moment to catch a wrong approach, rather than from one model planning better than the other. It also means the implementing session starts with a tight brief rather than the full history of how the plan was arrived at. Race them on a genuinely uncertain task Two worktrees, same task, one agent each, and you keep the better result. Expensive in usage and cheap in coordination, so save it for work where you genuinely do not know what the right approach is. See how to run coding agents in parallel with git worktrees https://nimbalyst.com/blog/git-worktrees-for-ai-coding-agents-complete-guide/ for the isolation setup. Fall over when you hit a limit Both providers meter usage, and hitting a window mid-task is routine. Two agents means the second is a genuine fallback rather than a wait. Keep both signed in, keep the shared instructions file accurate, and switching costs you a prompt rather than an afternoon. Neither tool bypasses the other’s limits, and no workspace on top of them can either. Step 6: keep both in one place The setup above works entirely in a terminal. What it does not solve is the part that gets expensive at three or four concurrent sessions: knowing which agent is doing what, and reviewing two agents’ output in two different interfaces. Nimbalyst https://nimbalyst.com is the visual workspace for this. You pick Claude Code or Codex when you start a session, and both run in the same project, on a kanban board, each with its own transcript, its own files-changed sidebar, an optional git worktree on its own branch, and file-by-file red/green diff review before anything is committed. Anthropic and OpenAI still supply the agents, authenticate your account, and enforce their own limits. Nimbalyst supplies the workspace around them, and does not resell or meter provider tokens. It is free for individuals and MIT licensed for individual-use features. The details of which access methods work with which agent, including API keys and local models through LM Studio, are on the Claude Code and Codex subscriptions page https://nimbalyst.com/claude-code-codex-subscriptions/ . Common mistakes Maintaining two instructions files. They drift within a fortnight, and the drift is invisible until an agent does something the other would not have. Letting a stray environment variable pick your billing. Covered above, and worth checking again if you have ever pasted a key into a .env for an unrelated project. Assuming a routing rule is permanent. Write down when you last tested it. If the answer is more than a few months ago, you are routing on nostalgia. Giving the reviewing agent write access. A reviewer that can edit will fix things instead of telling you about them, and you lose the review. Running both without worktrees. Two agents in one working directory is the same collision whether they come from the same vendor or not. Related reading Related pages Related posts - Best Conductor Alternatives 2026: Windows, Linux, and Open Source Conductor is macOS only. The best Conductor alternatives in 2026 compared on platform support, agent coverage, licensing, and worktree isolation. - Best AI Agent Orchestration Platforms 2026: Coding vs Workflow AI agent orchestration means two different products. Compare control planes for your own coding agents Nimbalyst, Orca, Emdash, Superset, Conductor, Warp against workflow frameworks like LangGraph and CrewAI. - What Is an Agentic Development Environment ADE ? An agentic development environment is the workspace you use to direct several coding agents at once. Definition, origins, how an ADE differs from an IDE and a CLI agent, and criteria for evaluating one.