Orchestrating Claude Code and Codex Together: A Power User Guide

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 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 and the fuller Codex vs Claude Code head-to-head.

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 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 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.

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

• Claude Code vs Codex CLI: when to use which
• Codex vs Claude Code: a head-to-head
• How to manage and review multiple agent sessions
• How to run coding agents in parallel with git worktrees
• Best multi-agent desktop apps for Claude Code and Codex