---
title: Use Claude Agent, Gemini CLI, and Codex in Zed
description: Run Claude Agent, Gemini CLI, Codex, and other AI coding agents directly in Zed via the Agent Client Protocol (ACP).
---

# External Agents

Zed supports many external agents, including CLI-based ones, through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).

Zed supports [Gemini CLI](https://github.com/google-gemini/gemini-cli) (the reference ACP implementation), [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview), [Codex](https://developers.openai.com/codex), [GitHub Copilot](https://github.com/github/copilot-language-server-release), and [additional agents](#add-more-agents) you can configure.

For Zed's built-in agent and the full list of tools it can use natively, see [Agent Tools](./tools.md).

> Note that Zed's interaction with external agents is strictly UI-based; the billing, legal, and terms arrangement is directly between you and the agent provider.
> Zed does not charge for use of external agents, and our [zero-data retention agreements/privacy guarantees](./ai-improvement.md) are **_only_** applicable for Zed's hosted models.

## Gemini CLI {#gemini-cli}

Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md).
Under the hood we run Gemini CLI in the background, and talk to it over ACP.

### Getting Started

First open the agent panel with {#kb agent::ToggleFocus}, and then start a new Gemini CLI thread using the agent selector button on the left (in the empty state) or the `+` button in the top right.

If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include:

```json [keymap]
[
  {
    "bindings": {
      "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }]
    }
  }
]
```

#### Installation

The first time you create a Gemini CLI thread, Zed will install [@google/gemini-cli](https://github.com/google-gemini/gemini-cli).
This installation is only available to Zed and is kept up to date as you use the agent.

#### Authentication

After you have Gemini CLI running, you'll be prompted to authenticate.

Click the "Login" button to open the Gemini CLI interactively, where you can log in with your Google account or [Vertex AI](https://cloud.google.com/vertex-ai) credentials.
Zed does not see your OAuth or access tokens in this case.

If the `GEMINI_API_KEY` environment variable (or `GOOGLE_AI_API_KEY`) is already set, or you have configured a Google AI API key in Zed's [language model provider settings](./llm-providers.md#google-ai), it will be passed to Gemini CLI automatically.

For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).

### Usage

Gemini CLI supports the same workflows as Zed's first-party agent: code generation, refactoring, debugging, and Q&A. Add context by @-mentioning files, recent threads, or symbols.

> Some agent panel features are not yet available with Gemini CLI: editing past messages, resuming threads from history, and checkpointing.

## Claude Agent

Similar to Gemini CLI, you can also run [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview) directly via Zed's [agent panel](./agent-panel.md).
Under the hood, Zed runs the Claude Agent SDK, which runs Claude Code under the hood, and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/claude-agent-acp).

### Getting Started

Open the agent panel with {#kb agent::ToggleFocus}, and then start a new Claude Agent thread using the agent selector button on the left (in the empty state) or the `+` button in the top right.

If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include:

```json [keymap]
[
  {
    "bindings": {
      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude-acp" }]
    }
  }
]
```

### Authentication

As of version `0.202.7`, authentication to Zed's Claude Agent installation is decoupled entirely from Zed's agent.
That is to say, an Anthropic API key added via the [Zed Agent's settings](./llm-providers.md#anthropic) will _not_ be utilized by Claude Agent for authentication and billing.

To ensure you're using your billing method of choice, [open a new Claude Agent thread](./agent-panel.md#new-thread).
Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription.

#### Installation

The first time you create a Claude Agent thread, Zed will install [@zed-industries/claude-agent-acp](https://github.com/zed-industries/claude-agent-acp).
This installation is only available to Zed and is kept up to date as you use the agent.

Zed will always use this managed version of the Claude Agent adapter, which includes a vendored version of the Claude Code CLI, even if you have it installed globally.

If you want to override the executable used by the adapter, you can set the `CLAUDE_CODE_EXECUTABLE` environment variable in your settings to the path of your preferred executable.

```json
{
  "agent_servers": {
    "claude-acp": {
      "type": "registry",
      "env": {
        "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable"
      }
    }
  }
}
```

### Usage

Claude Agent supports the same workflows as Zed's first-party agent. Add context by @-mentioning files, recent threads, diagnostics, or symbols.

In complement to talking to it [over ACP](https://agentclientprotocol.com), Zed relies on the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) to support some of its specific features.
However, the SDK doesn't yet expose everything needed to fully support all of them:

- Slash Commands: [Custom slash commands](https://code.claude.com/docs/en/slash-commands#custom-slash-commands) are fully supported, and have been merged into skills. A subset of [built-in commands](https://code.claude.com/docs/en/slash-commands#built-in-slash-commands) are supported.
- [Subagents](https://code.claude.com/docs/en/sub-agents) are supported.
- [Agent teams](https://code.claude.com/docs/en/agent-teams) are currently _not_ supported.
- [Hooks](https://code.claude.com/docs/en/hooks-guide) are currently _not_ supported.

> Some [agent panel](./agent-panel.md) features are not yet available with Claude Agent: editing past messages, resuming threads from history, and checkpointing.

#### CLAUDE.md

Claude Agent in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory.

If you don't have a `CLAUDE.md` file, you can ask Claude Agent to create one for you through the `init` slash command.

## Codex CLI

You can also run [Codex CLI](https://github.com/openai/codex) directly via Zed's [agent panel](./agent-panel.md).
Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/codex-acp).

### Getting Started

As of version `0.208`, you should be able to use Codex directly from Zed.
Open the agent panel with {#kb agent::ToggleFocus}, and then start a new Codex thread using the agent selector button on the left (in the empty state) or the `+` button in the top right.

If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include:

```json
[
  {
    "bindings": {
      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "codex-acp" }]
    }
  }
]
```

### Authentication

Authentication to Zed's Codex installation is decoupled entirely from Zed's agent.
That is to say, an OpenAI API key added via the [Zed Agent's settings](./llm-providers.md#openai) will _not_ be utilized by Codex for authentication and billing.

To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread).
The first time you will be prompted to authenticate with one of three methods:

1. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_
2. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`.
3. `OPENAI_API_KEY` - uses an API key you have set in your environment under the variable `OPENAI_API_KEY`.

If you are already logged in and want to change your authentication method, type `/logout` in the thread and authenticate again.

If you want to use a third-party provider with Codex, you can configure that with your [Codex config.toml](https://github.com/openai/codex/blob/main/docs/config.md#model-selection) or pass extra [args/env variables](https://github.com/openai/codex/blob/main/docs/config.md#model-selection) to your Codex agent servers settings.

#### Installation

The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp).
This installation is only available to Zed and is kept up to date as you use the agent.

Zed will always use this managed version of Codex even if you have it installed globally.

### Usage

Codex supports the same workflows as Zed's first-party agent. Add context by @-mentioning files or symbols.

> Some agent panel features are not yet available with Codex: editing past messages, resuming threads from history, and checkpointing.

## Add More Agents {#add-more-agents}

### Via The ACP Registry

[The ACP Registry](https://github.com/agentclientprotocol/registry) lets developers distribute ACP-compatible agents to any client that implements the protocol. Agents installed from the registry update automatically.

At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods).

#### Using it in Zed

Use the {#action zed::AcpRegistry} command to quickly go to the ACP Registry page.
There's also a button ("Add Agent") that takes you there in the agent panel's configuration view.

From there, you can click to install your preferred agent and it will become available right away in the `+` icon button in the agent panel.

> If you installed the same agent through both the extension and the registry, the registry version takes precedence.

### Custom Agents

You can also add agents through your settings file ([how to edit](../configuring-zed.md#settings-files)) by specifying certain fields under `agent_servers`, like so:

```json [settings]
{
  "agent_servers": {
    "My Custom Agent": {
      "type": "custom",
      "command": "node",
      "args": ["~/projects/agent/index.js", "--acp"],
      "env": {}
    }
  }
}
```

This can be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it.

It's also possible to customize environment variables for registry-installed agents like Claude Agent, Codex, and Gemini CLI by using their registry names (`claude-acp`, `codex-acp`, `gemini`) with `"type": "registry"` in your settings.

## Importing Threads {#importing-threads}

Zed can import existing threads from your external agent so they show up in your [Thread History](./agent-panel.md#multiple-threads) alongside the rest of your threads. This is useful when you've been working with Claude Agent, Codex, or another agent elsewhere and want to continue those conversations in Zed.

### Starting an Import

Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar} and open Thread History by clicking the clock icon at the bottom of the sidebar (or run {#action agents_sidebar::ToggleThreadHistory} from the Command Palette). Then click the **Import Threads** button (the download icon) in the Thread History toolbar.

This opens the **Import External Agent Threads** dialog, which lists every external agent you have configured. Choose the agents you want to import from, then click **Import Threads**. Zed connects to each selected agent, retrieves its sessions over [ACP](https://agentclientprotocol.com), and adds any that aren't already in your history. When the import finishes, a notification reports how many threads were added.

### What to Expect

- **The agent must be configured in Zed.** Only agents you've already set up (see the sections above and [Add More Agents](#add-more-agents)) appear in the dialog.
- **Imported threads are archived.** They're added to Thread History as archived entries; open one to restore it and continue where you left off. See [Managing Multiple Threads](./agent-panel.md#multiple-threads).
- **Only threads tied to a project folder are imported.** Sessions that an agent reports without an associated working directory are skipped.
- **Re-importing is safe.** Threads you've already imported are skipped, so you can run the import again later to pick up new sessions without creating duplicates.
- **Local and remote projects are supported.** Threads are gathered from the agents available in your current local and [remote](../remote-development.md) projects.

## Debugging Agents

When using external agents in Zed, you can access the debug view via with {#action dev::OpenAcpLogs} from the Command Palette.
This lets you see the messages being sent and received between Zed and the agent.

![The debug view for ACP logs.](https://zed.dev/img/acp/acp-logs.webp)

It's helpful to attach data from this view if you're opening issues about problems with external agents like Claude Agent, Codex, OpenCode, etc.

## Configuration Boundaries {#configuration-boundaries}

External agents run as separate processes that communicate with Zed via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). This creates important boundaries between Zed's configuration and the agent's native configuration.

### What Zed Forwards to External Agents

When you start an external agent thread, Zed sends:

| Setting               | How to Configure                                                      |
| --------------------- | --------------------------------------------------------------------- |
| Model selection       | `agent_servers.<agent>.default_model` in settings                     |
| Mode selection        | `agent_servers.<agent>.default_mode` in settings                      |
| Environment variables | `agent_servers.<agent>.env` in settings                               |
| MCP servers           | `context_servers` in settings (see [limitations](#mcp-server-access)) |
| Working directory     | Automatically set to project root                                     |

**Not forwarded:**

- [Profiles](./agent-panel.md#profiles) — profiles only apply to Zed's first-party agent
- [Tool permissions](./tool-permissions.md) settings — external agents request permissions at runtime via UI prompts
- Rules files — Zed's [rules system](./rules.md) only applies to Zed's first-party agent (external agents read their own rules files directly)

### What External Agents Read Directly {#native-config}

External agents run as CLI tools with full filesystem access. They read their own configuration files directly — Zed doesn't forward or block these.

#### Claude Agent

Claude Agent runs Claude Code under the hood, which reads its standard configuration:

| Config                              | Read by Claude Agent?                                             |
| ----------------------------------- | ----------------------------------------------------------------- |
| `~/.claude/` directory              | Yes — Claude Code reads its own settings and memory               |
| CLAUDE.md files                     | Yes — Claude Code reads these directly from the project           |
| Skills                              | Yes — exposed via the Claude Agent SDK                            |
| MCP servers from Claude Code config | Yes — but Zed also forwards its own MCP servers via ACP           |
| Hooks                               | No — [not supported](https://code.claude.com/docs/en/hooks-guide) |
| Authentication                      | Separate — you must authenticate via `/login` in Zed              |

> **Why separate authentication?** Zed isolates Claude Agent authentication to give you control over which account and billing method you use.

#### Codex

Codex runs the Codex CLI under the hood, which reads its standard configuration:

| Config                        | Read by Codex?                                  |
| ----------------------------- | ----------------------------------------------- |
| `~/.codex/config.toml`        | Yes — Codex CLI reads its own config            |
| MCP servers from Codex config | Yes — but Zed also forwards its own MCP servers |
| `CODEX_API_KEY` env var       | Yes — inherited from your shell environment     |
| `OPENAI_API_KEY` env var      | Yes — inherited from your shell environment     |
| ChatGPT OAuth login           | Separate — you must re-authenticate in Zed      |

You can also pass environment variables through Zed settings:

```json [settings]
{
  "agent_servers": {
    "codex-acp": {
      "type": "registry",
      "env": {
        "CODEX_API_KEY": "your-key",
        "CUSTOM_PROVIDER_URL": "https://..."
      }
    }
  }
}
```

### MCP Server Access {#mcp-server-access}

MCP servers configured in Zed's `context_servers` are forwarded to Claude Agent and Codex via the ACP protocol.

- **Local stdio-based MCP servers:** Work reliably
- **Remote MCP servers with OAuth:** May have issues ([#54410](https://github.com/zed-industries/zed/issues/54410))

External agents can access MCP servers from two sources: Zed's `context_servers` (forwarded via ACP) and their own native configuration files (`~/.claude/`, `~/.codex/config.toml`).

For more on configuring MCP servers, see [Model Context Protocol](./mcp.md).

### Troubleshooting {#troubleshooting}

**"I enabled MCP tools in Zed but the agent can't see them"**

1. Verify the MCP server is enabled in `context_servers` settings
2. For remote MCP servers with OAuth, this is a [known issue](https://github.com/zed-industries/zed/issues/54410) — try local stdio-based servers instead
3. Open {#action dev::OpenAcpLogs} from the Command Palette to debug

**"My existing Claude Code / Codex setup isn't working in Zed"**

External agents read their own config files, but authentication is handled separately:

1. Re-authenticate via `/login` (Claude Agent) or the authentication prompt (Codex)
2. Your existing MCP servers and settings from `~/.claude/` or `~/.codex/config.toml` should work
3. You can also configure additional settings via `agent_servers.<agent>.env` in Zed

**"Profiles don't affect my external agent"**

Correct — [profiles](./agent-panel.md#profiles) only apply to Zed's first-party agent. External agents have their own tool sets and don't use Zed's profile system.
