How to run Claude Code and OpenAI Codex together as one team

01Why run Claude Code and Codex together?

Most developers start with one AI coding agent and one terminal. That works until the task gets big enough that you are waiting: while the agent writes the backend, the frontend waits; while it runs tests, you wait. Adding a second agent is the obvious fix, and pairing two different products has advantages beyond raw parallelism.

• Different strengths for different jobs. Many teams use Claude Code for planning, architecture discussion, test design and code review, and Codex for focused, fast implementation of well-defined tasks. You assign each model the work it is best at instead of forcing one model to do everything.
• A real second opinion. A model reviewing its own output tends to approve its own blind spots. When Claude Code reviews code that Codex wrote (or the other way round), the reviewer does not share the author's assumptions, so it flags more real problems.
• More capacity from subscriptions you already pay for. If you have both an Anthropic and an OpenAI plan, running them side by side lets both quotas work for you at once instead of one sitting idle.
• True parallelism. Independent tasks such as an API endpoint, a UI screen and a test suite can progress at the same time.

02What goes wrong when you do it by hand

You can open two terminals, run claude in one and codex in the other, and coordinate them yourself. Most people who try this hit the same walls within a day:

• You become the message bus. Every plan, API schema, error log and review comment has to be copied from one window into the other.
• Context disappears. Close the laptop, lose the SSH connection or reboot, and both sessions are gone. The next morning you explain the project again.
• Nobody owns the whole. Each agent sees only its slice. Integration, ordering (“do not start the tests until the API exists”) and final review all fall back on you.

What you want is a lead agent you talk to, teammates that receive tasks and message each other directly, and something that keeps all of them alive. That is the job Team Agent does.

03What you need

• macOS (Apple Silicon or Intel) or Linux x64. Windows works through WSL.
• Node.js 18 or later, used only for the one-time installer.
• tmux. You do not need to know tmux; Team Agent drives it for you.
• Claude Code and the OpenAI Codex CLI, installed and signed in. Check that claude and codex both start normally in your terminal.

04Step-by-step setup

Step 1: Install Team Agent

npx @team-agent/installer@latest install
team-agent --version

The installer places a single native team-agent binary for your platform. There is no service to enable and nothing keeps running after the command finishes.

Step 2: Start Claude Code as the leader

Open a terminal in your project root and run:

team-agent claude

This is ordinary Claude Code: same interface, same models, same tools. The difference is that this conversation is now the leader of a team and can start and coordinate teammates. Prefer to lead with Codex? Run team-agent codex instead.

Step 3: Ask for a team in plain language

Tell the leader what you want. For example:

This is too much for one agent. Build a team:
- backend: Codex, implements the /v1/invoices endpoint
- reviewer: Claude, reviews every change for bugs and missing tests
Show me the plan first.

The leader proposes the roles. Before starting anyone, it confirms two choices with you for each teammate: which CLI it uses and whether it may skip permission prompts. Team Agent never picks these silently. Once you confirm, it writes the team files and starts each teammate in its own tmux pane.

Step 4 (optional): Define the team yourself

If you prefer configuration you can commit and review, write the files directly. A team is a folder with a TEAM.md and one Markdown file per role; the file name becomes the teammate's name.

.team/current/
  TEAM.md
  agents/
    backend.md
    reviewer.md

TEAM.md describes the goal:

---
name: billing-api
objective: Ship the /v1/invoices endpoint with tests and a reviewed change set
---
The leader plans and integrates. backend implements.
reviewer reviews every change before it is merged.

agents/backend.md runs on Codex:

---
provider: codex
dangerously_skip_permissions: false
---
You implement backend features in this repository.
Keep changes small, run the test suite before reporting,
and list the files you changed in every report.

agents/reviewer.md runs on Claude Code:

---
provider: claude
dangerously_skip_permissions: false
---
Review each change for correctness, security and missing tests.
Reply with concrete findings ordered by severity.
Do not edit product code yourself.

Then start the team from the leader's terminal:

team-agent start --from .team/current

You can also set model and effort in a role's front matter. Use team-agent models --provider codex to list the exact model names your installed CLI supports.

Step 5: Send work and read results

Usually you just keep talking to the leader, and it sends tasks for you. You can also drive the team from any terminal:

team-agent send backend "Add pagination to GET /v1/invoices and cover it with tests"
team-agent status
team-agent inbox leader -n 3

status shows every teammate's provider, activity and health. inbox shows the latest replies. A sent message is not a finished task: teammates report back when they are done, and the leader summarizes.

Step 6: Stop for the day, resume tomorrow

team-agent stop        # end of day: stops the team, keeps saved sessions
team-agent start       # next morning: same teammates, same context

Because each agent runs inside tmux, closing your terminal or losing an SSH connection does not stop the team. After a reboot, team-agent start brings it back and resumes each agent's saved conversation where the CLI supports it.

05Recommended role splits

There is no single right answer, but these combinations work well as starting points:

Team shape	Leader	Teammates	Good for
Builder + reviewer	Claude Code	Codex (backend), Claude (reviewer)	Everyday feature work with a quality gate
Parallel feature team	Claude Code	Codex (backend), Codex (frontend), Claude or Pi (tests)	Full-stack features split by layer
Codex-led	Codex	Codex (implementers), Claude (architect, reviewer)	Codex users who want a design and review partner
Build, test, fix loop	Claude Code	Codex (developer), Claude (tester)	Bug fixing where a tester keeps reporting until it passes

Teammates are not limited to coding. People also run multi-reviewer paper critiques, brainstorming panels and research teams with the same setup.

06Tips for a productive Claude + Codex team

1. One leader per feature. Give each feature direction a single leader conversation. It decides how to split the work and integrates the results, so you stay in the product-owner seat.
2. Make review a rule, not a favor. Put “every change goes through reviewer” in TEAM.md. The leader enforces it.
3. Let teammates talk directly. The frontend can ask the backend for the API shape without going through you. That is where most of the time savings come from.
4. Keep tasks small and testable. “Add pagination with tests” beats “improve the API”. Tests give both agents an objective referee.
5. Choose permissions deliberately. Skipping permission prompts makes unattended work smoother but gives the agent broader authority. Turning them off is not a sandbox either; it keeps each CLI's native confirmation behavior.
6. You do not have to watch the panes. They are there if you want to look or step in. Reports come back to the leader's conversation.

07Troubleshooting

When something looks wrong, run the built-in health check first:

team-agent doctor --workspace .

When everything is healthy it prints a single line. When something is broken it prints a short report that stops at the first failing step and suggests one command to fix it. Common cases:

• A teammate is not replying. Check team-agent status. If its CLI exited, team-agent start backend restarts that one teammate without touching the others.
• A teammate got confused after a long session. Reset just that agent with a fresh context while the rest of the team keeps working (see team-agent agent --help).
• The CLI is not signed in. Team Agent never logs in for you. Start claude or codex on its own once, sign in, then start the team again.

08FAQ

Can Claude Code and OpenAI Codex work on the same project at the same time?

Yes. Run each CLI in its own terminal session and give each one a separate role, such as implementer and reviewer. A coordinator like Team Agent starts both in tmux, routes tasks and messages between them, and collects their results so they do not overwrite each other's work or depend on you to copy context.

Do I need API keys to run Claude Code and Codex together?

No. Team Agent runs the official Claude Code and Codex CLIs signed in with your existing accounts or subscriptions. API keys are only needed if you choose to attach an API-based profile.

Which should be the leader, Claude Code or Codex?

Either works. A common setup is Claude Code as the leader because it plans, explains trade-offs and reviews well, with Codex teammates doing focused implementation. You can also lead with Codex and use Claude Code as the reviewer.

How do I keep the team running overnight or after a reboot?

Each agent runs inside tmux, so closing the terminal does not stop it. Use team-agent stop to end the day and team-agent start to bring the same team back; saved conversations are resumed where the agent CLI supports it.