# How to run Claude Code, Codex and Gemini CLI together on one project

Install and log in to each CLI, then give each agent its own terminal and, when they edit code at once, its own git worktree. That handles the files; hand-offs between agents stay manual. MAO runs all three as terminal nodes on one canvas, each on its own login, with wires for hand-offs and a role per agent.

To run Claude Code, Codex and Gemini CLI on one project, install and sign in to each CLI, start each in its own terminal, and give every agent that edits code its own git worktree so their changes stay apart. Plain terminals and worktrees leave you to pass plans and reviews between the agents. MAO runs all three as terminal nodes on one canvas, each on its own login, with wires that let them send each other tasks and a role for each.

## Why mix Claude Code, Codex and Gemini CLI?

Each CLI is a different company's agent for its own models, so mixing them lets you give each part of the work to a different model. A common split is one agent to plan, one to build and one to review.

- **Claude Code** is Anthropic's agent and signs in with a Claude subscription or a Claude Console account.
- **Codex** is OpenAI's agent and signs in with a ChatGPT plan or an OpenAI API key.
- **Gemini CLI** is Google's agent and signs in with a Google account, a Gemini API key or Vertex AI.

A reviewer that did not write the code reads it fresh, and one from another provider is a further step removed from the author. Which model suits which job depends on your project, so try a split on a small task before you rely on it.

## What does each CLI need before you start?

Each one installs separately and asks you to sign in the first time you run it in a project directory.

|  | Claude Code | Codex | Gemini CLI |
| --- | --- | --- | --- |
| Install | Native installer, Homebrew or WinGet | Install script, npm or Homebrew | npm, Homebrew or MacPorts; needs Node.js 20 or later |
| Start | `claude` | `codex` | `gemini` |
| Sign in | Claude Pro, Max, Team or Enterprise, Claude Console, or a cloud provider | **Sign in with ChatGPT** (Plus, Pro, Business, Edu, Enterprise) or an API key | Sign in with Google, a Gemini API key, or Vertex AI |
| Project instructions | `CLAUDE.md`, or `AGENTS.md` | `AGENTS.md` | `GEMINI.md` |

With Homebrew:

```
brew install --cask claude-code
brew install --cask codex
brew install gemini-cli
```

On Windows:

```
winget install Anthropic.ClaudeCode
npm install -g @openai/codex
npm install -g @google/gemini-cli
```

Claude Code and Codex also have their own install scripts for each system, listed in their docs. Claude Code's native install updates itself in the background; a Homebrew or WinGet install does not, so upgrade it yourself with `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode`.

Then sign in to each one from your project directory:

1. Run `claude --version` to check the install, then `claude` and follow the browser login. Type `/login` inside a session to switch accounts later.
2. Run `codex` and choose **Sign in with ChatGPT**, or sign in with an API key by running `codex login --with-api-key` with the key on its standard input. `codex login status` shows which method is active.
3. Run `gemini` and choose a sign-in method. For a Gemini API key, set it first with `export GEMINI_API_KEY="YOUR_API_KEY"`. With a Code Assist licence from your organization, set `GOOGLE_CLOUD_PROJECT` to your Google Cloud project before you sign in with Google.

Check which Google accounts Gemini CLI serves before you set it up. Its README says it is meant for Gemini Code Assist Standard and Enterprise licences and Code Assist for GitHub on Google Cloud, plus paid API and Vertex AI keys. Free individual access and Google AI Pro and Ultra moved to Antigravity CLI on June 18, 2026.

## How do the three agents share project instructions?

Keep one `AGENTS.md` and point the other two at it. Each agent reads its own instruction file by default, so without this you maintain three copies of the same rules.

- **Codex** reads `AGENTS.md`, walking from the project root down to the current directory.
- **Claude Code** reads `AGENTS.md` when there is no `CLAUDE.md`. If you keep a `CLAUDE.md`, add a line `@AGENTS.md` to it to import the shared file.
- **Gemini CLI** reads `GEMINI.md`. List other names in the `context.fileName` setting of its `settings.json`:

```
{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}
```

## Can you just open three terminals?

Yes, and it needs nothing new: open three terminal windows or tabs in the repository and run `claude`, `codex` and `gemini`, one in each. Each CLI keeps its own login, so the three never share credentials.

It works while the agents read code or touch clearly separate files. They all edit the same working tree, though, so one agent's half-finished change is what the next one sees, and you are the only link between them: you copy the plan out of one window and paste it into the next.

## Does tmux make it easier?

tmux puts the three agents in panes of one window, so you can watch them side by side and leave them running in a session you come back to. It changes how you see the agents, not how they share files.

1. Start a named session with `tmux new -s agents`.
2. Press `C-b %` to split the pane side by side, and `C-b "` to split it top and bottom.
3. Run `claude`, `codex` and `gemini`, one per pane.
4. Detach with `C-b d`, and return with `tmux attach -t agents`.

The panes still share one checkout, and you still relay work between them by hand.

## How do git worktrees keep the agents apart?

Give each agent that edits code its own worktree. A worktree is a second working directory for the same repository with its own branch checked out, so each agent edits its own files and commits to its own branch.

```
git worktree add -b agent/codex ../myapp-codex
git worktree add -b agent/gemini ../myapp-gemini

claude                            # plans and reads in the main checkout
cd ../myapp-codex && codex        # edits on agent/codex
cd ../myapp-gemini && gemini      # edits on agent/gemini
```

`git worktree list` shows every worktree and its branch. Git refuses to check out a branch that another worktree already has, which keeps two agents off the same branch. When a branch is merged, remove its worktree with `git worktree remove ../myapp-codex`.

Worktrees fix the files but not the hand-offs. The agents still cannot ask each other anything, and you still track which terminal is waiting for you.

## How does MAO run all three together?

MAO puts each agent on a canvas as a terminal node that runs the agent's own CLI on its own login. You draw wires between the agents so they can send each other tasks, give each one a role, and put the agents that edit code on layers, which are git worktrees.

1. **Install and sign in** to each CLI on the machine where its terminal will run. MAO runs the agent's own CLI and tells you when one is not installed. On Windows it finds agents installed with `npm install -g`, Gemini CLI among them, on your PATH.
2. **Open your repository** as a workspace in MAO.
3. **Place the agents.** Choose **New terminal or agent**, or press `Ctrl+T` (`Cmd+T` on macOS), then pick Claude Code and place its node. Repeat for Codex and Gemini CLI, which has its own tile in the agent sheet.
4. **Choose a login per node.** Each node uses the CLI's own login unless you pick a saved account from its **Account** menu. **Add account…** saves a **Directory**, **API key** or **Endpoint** account, depending on what the provider supports.
5. **Give each a role.** **Builder** and **Reviewer** are built in, for example Builder on Codex and Reviewer on Gemini CLI. Write a planning role for Claude Code in its instructions sheet and choose **Save as role**.
6. **Draw the wires.** Select the Claude Code node, choose **Connect** and pick Codex, then connect Codex to Gemini CLI. A wire grants access only to the node at its other end. Wire a specification note to all three to share the plan.
7. **Give the builder a layer** so its edits land on its own branch. You review the diff on the canvas and land the layer into Ground when it is ready.
8. **Ask once.** Mark Claude Code as the **Orchestrator** in its setup sheet and tell it what you want built.

From its own terminal, the planner hands work to its peers with the `mao` command:

```
mao peers
mao ask builder "Implement the plan in the spec note"
mao ask reviewer "Review the builder's changes for bugs and missing tests"
```

`mao ask` sends a task and waits for the result. `mao send` returns a task id at once and `mao wait <task-id>` collects the result later. An Orchestrator can also add an agent with `mao recruit <name> --preset <preset> --role <role>` and wire it with `mao connect <from> <to>`.

MAO adds a role's instructions to prompts it sends over ACP. An agent that runs only as a terminal does not receive them automatically, so put the same rules in the project's instruction file too.

## Which option should you use?

Start with the simplest one that covers your problem: terminals for a quick look, worktrees as soon as two agents edit code, and a canvas when you are tired of relaying work between them.

| Option | See all three at once | Avoids file collisions | Agents hand off work | Login per agent | Setup |
| --- | --- | --- | --- | --- | --- |
| Separate terminals | No, one window each | No | No, you copy and paste | Each CLI's own | None |
| tmux panes | Yes, panes in one window | No | No, you copy and paste | Each CLI's own | Install tmux |
| Git worktrees | Depends on your terminals | Yes, one branch each | No | Each CLI's own | One `git worktree add` per agent |
| MAO | Yes, nodes on a canvas | Yes, with layers | Yes, wires and `mao ask` | The CLI's own or a saved account per node | Place nodes, draw wires |

## Frequently asked questions

### Can Claude Code, Codex and Gemini CLI work on the same repository at the same time?

Yes. Each is a separate CLI with its own login, so all three can run in one repository at once. Give every agent that edits code its own git worktree, or its own layer in MAO, so their changes do not collide.

### Do I need API keys to run all three?

No. Claude Code signs in with a Claude subscription and Codex with a ChatGPT plan, and Gemini CLI signs in with a Google account for organizations with a Code Assist licence. In MAO each agent runs on its own login, and MAO does not route your prompts through its own servers.

### Which version of Gemini CLI does MAO need?

Gemini CLI 0.41 or later. With an older version, MAO says which version it found, where, and how to update it.

### Can Gemini CLI read my AGENTS.md?

Yes, once you list it. Gemini CLI reads `GEMINI.md` by default; add `AGENTS.md` to the `context.fileName` setting and it reads that file too, the same one Codex and Claude Code read.

### I have a free or Google AI Pro account. Can I still use Gemini CLI?

According to Gemini CLI's README, free individual access and Google AI Pro and Ultra moved to Antigravity CLI on June 18, 2026. MAO also runs Antigravity as an agent, beside Claude Code and Codex.

## Sources

- [Claude Code quickstart](https://code.claude.com/docs/en/quickstart): the native, Homebrew and WinGet installs and how each updates, `claude --version`, the first-run login, account types and `/login`.
- [How Claude remembers your project](https://code.claude.com/docs/en/memory): `CLAUDE.md`, reading `AGENTS.md`, and `@` imports.
- [Codex CLI](https://developers.openai.com/codex/cli): the standalone installer and running `codex` in a project directory.
- [Codex authentication](https://developers.openai.com/codex/auth): **Sign in with ChatGPT**, `codex login --with-api-key` and `codex login status`.
- [Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md): where Codex looks for `AGENTS.md`.
- [Codex README](https://github.com/openai/codex): the install scripts, the npm and Homebrew installs, and the ChatGPT plans that include Codex.
- [Gemini CLI README](https://github.com/google-gemini/gemini-cli): which accounts Gemini CLI serves, the move to Antigravity CLI, install commands and sign-in options.
- [Gemini CLI installation](https://www.geminicli.com/docs/get-started/installation): Node.js 20 or later and supported systems.
- [Gemini CLI authentication](https://www.geminicli.com/docs/get-started/authentication): Google sign-in, `GEMINI_API_KEY`, Vertex AI and `GOOGLE_CLOUD_PROJECT`.
- [Gemini CLI context files](https://www.geminicli.com/docs/cli/gemini-md): `GEMINI.md` and the `context.fileName` setting.
- [tmux Getting Started](https://github.com/tmux/tmux/wiki/Getting-Started): named sessions, splitting panes, detaching and attaching.
- [git-worktree](https://git-scm.com/docs/git-worktree): `git worktree add -b`, `list`, `remove`, and the one-worktree-per-branch check.
- [Supported coding agents](https://trymao.dev/claude-code-codex-grok): Gemini CLI as a built-in agent, the 0.41 requirement, Antigravity, and agents that must be installed.
- [Configure agent launch presets](https://trymao.dev/docs/agent-presets-accounts-roles/agent-presets): **New terminal or agent**, presets, and changing a node's model, account and role.
- [Add and choose provider accounts](https://trymao.dev/docs/agent-presets-accounts-roles/agent-accounts): **Directory**, **API key** and **Endpoint** accounts per node.
- [Save and assign agent roles](https://trymao.dev/docs/agent-presets-accounts-roles/agent-roles): **Builder**, **Reviewer**, **Save as role** and role delivery over ACP.
- [Connect agents, notes, and portals](https://trymao.dev/docs/connections-orchestration-mao-cli/node-connections): wires and what they grant.
- [Send a task and collect its result](https://trymao.dev/docs/connections-orchestration-mao-cli/task-delivery): `mao ask`, `mao send` and `mao wait`.
- [Manage agents as an Orchestrator](https://trymao.dev/docs/connections-orchestration-mao-cli/orchestrator-actions): `mao recruit` and `mao connect`.
- [Create a worktree layer](https://trymao.dev/docs/layers-git-worktrees/create-layer) and [Land a layer into Ground](https://trymao.dev/docs/layers-git-worktrees/land-layer): layers as git worktrees.
- [MAO 0.10.0](https://trymao.dev/changelog/0.10.0) and [MAO 0.11.8](https://trymao.dev/changelog/0.11.8): Gemini CLI as a built-in agent, the version message, and npm-installed agents on Windows.
- [Multi-agent orchestration for coding agents](https://trymao.dev/multi-agent-orchestration): MAO does not route prompts through its own servers.

Checked on 2026-10-28.

Source: https://trymao.dev/run-claude-code-codex-gemini-together