1---
2title: Use Claude Agent, Gemini CLI, and Codex in Zed
3description: Run Claude Agent, Gemini CLI, Codex, and other AI coding agents directly in Zed via the Agent Client Protocol (ACP).
4---
5
6# External Agents
7
8Zed supports many external agents, including CLI-based ones, through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
9
10Zed 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.
11
12> 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.
13> 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.
14
15## Gemini CLI {#gemini-cli}
16
17Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md).
18Under the hood we run Gemini CLI in the background, and talk to it over ACP.
19
20### Getting Started
21
22First open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Gemini CLI thread.
23
24If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the `zed: open keymap file` command to include:
25
26```json [keymap]
27[
28 {
29 "bindings": {
30 "cmd-alt-g": [
31 "agent::NewExternalAgentThread",
32 { "agent": { "custom": { "name": "gemini" } } }
33 ]
34 }
35 }
36]
37```
38
39#### Installation
40
41The first time you create a Gemini CLI thread, Zed will install [@google/gemini-cli](https://github.com/google-gemini/gemini-cli).
42This installation is only available to Zed and is kept up to date as you use the agent.
43
44#### Authentication
45
46After you have Gemini CLI running, you'll be prompted to authenticate.
47
48Click 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.
49Zed does not see your OAuth or access tokens in this case.
50
51If 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.
52
53For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).
54
55### Usage
56
57Gemini 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.
58
59> Some agent panel features are not yet available with Gemini CLI: editing past messages, resuming threads from history, and checkpointing.
60
61## Claude Agent
62
63Similar 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).
64Under 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).
65
66### Getting Started
67
68Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Claude Agent thread.
69
70If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the `zed: open keymap file` command to include:
71
72```json [keymap]
73[
74 {
75 "bindings": {
76 "cmd-alt-c": [
77 "agent::NewExternalAgentThread",
78 { "agent": { "custom": { "name": "claude-acp" } } }
79 ]
80 }
81 }
82]
83```
84
85### Authentication
86
87As of version `0.202.7`, authentication to Zed's Claude Agent installation is decoupled entirely from Zed's agent.
88That 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.
89
90To ensure you're using your billing method of choice, [open a new Claude Agent thread](./agent-panel.md#new-thread).
91Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription.
92
93#### Installation
94
95The first time you create a Claude Agent thread, Zed will install [@zed-industries/claude-agent-acp](https://github.com/zed-industries/claude-agent-acp).
96This installation is only available to Zed and is kept up to date as you use the agent.
97
98Zed 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.
99
100If 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.
101
102```json
103{
104 "agent_servers": {
105 "claude-acp": {
106 "type": "registry",
107 "env": {
108 "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable"
109 }
110 }
111 }
112}
113```
114
115### Usage
116
117Claude Agent supports the same workflows as Zed's first-party agent. Add context by @-mentioning files, recent threads, diagnostics, or symbols.
118
119In 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.
120However, the SDK doesn't yet expose everything needed to fully support all of them:
121
122- 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.
123- [Subagents](https://code.claude.com/docs/en/sub-agents) are supported.
124- [Agent teams](https://code.claude.com/docs/en/agent-teams) are currently _not_ supported.
125- [Hooks](https://code.claude.com/docs/en/hooks-guide) are currently _not_ supported.
126
127> Some [agent panel](./agent-panel.md) features are not yet available with Claude Agent: editing past messages, resuming threads from history, and checkpointing.
128
129#### CLAUDE.md
130
131Claude Agent in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory.
132
133If you don't have a `CLAUDE.md` file, you can ask Claude Agent to create one for you through the `init` slash command.
134
135## Codex CLI
136
137You can also run [Codex CLI](https://github.com/openai/codex) directly via Zed's [agent panel](./agent-panel.md).
138Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/codex-acp).
139
140### Getting Started
141
142As of version `0.208`, you should be able to use Codex directly from Zed.
143Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Codex thread.
144
145If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the `zed: open keymap file` command to include:
146
147```json
148[
149 {
150 "bindings": {
151 "cmd-alt-c": [
152 "agent::NewExternalAgentThread",
153 { "agent": { "custom": { "name": "codex-acp" } } }
154 ]
155 }
156 }
157]
158```
159
160### Authentication
161
162Authentication to Zed's Codex installation is decoupled entirely from Zed's agent.
163That 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.
164
165To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread).
166The first time you will be prompted to authenticate with one of three methods:
167
1681. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_
1692. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`.
1703. `OPENAI_API_KEY` - uses an API key you have set in your environment under the variable `OPENAI_API_KEY`.
171
172If you are already logged in and want to change your authentication method, type `/logout` in the thread and authenticate again.
173
174If 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.
175
176#### Installation
177
178The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp).
179This installation is only available to Zed and is kept up to date as you use the agent.
180
181Zed will always use this managed version of Codex even if you have it installed globally.
182
183### Usage
184
185Codex supports the same workflows as Zed's first-party agent. Add context by @-mentioning files or symbols.
186
187> Some agent panel features are not yet available with Codex: editing past messages, resuming threads from history, and checkpointing.
188
189## Add More Agents {#add-more-agents}
190
191### Via Agent Server Extensions
192
193<div class="warning">
194
195Starting from `v0.221.x`, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
196Learn more about it in [the release blog post](https://zed.dev/blog/acp-registry).
197At some point in the near future, Agent Server extensions will be deprecated.
198
199</div>
200
201Add more external agents to Zed by installing [Agent Server extensions](../extensions/agent-servers.md).
202
203See what agents are available by filtering for "Agent Servers" in the extensions page, which you can access via the command palette with `zed: extensions`, or the [Zed website](https://zed.dev/extensions?filter=agent-servers).
204
205### Via The ACP Registry
206
207#### Overview
208
209As mentioned above, the Agent Server extensions will be deprecated in the near future to give room to the ACP Registry.
210
211[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.
212
213At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods).
214
215#### Using it in Zed
216
217Use the `zed: acp registry` command to quickly go to the ACP Registry page.
218There's also a button ("Add Agent") that takes you there in the agent panel's configuration view.
219
220From there, you can click to install your preferred agent and it will become available right away in the `+` icon button in the agent panel.
221
222> If you installed the same agent through both the extension and the registry, the registry version takes precedence.
223
224### Custom Agents
225
226You 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:
227
228```json [settings]
229{
230 "agent_servers": {
231 "My Custom Agent": {
232 "type": "custom",
233 "command": "node",
234 "args": ["~/projects/agent/index.js", "--acp"],
235 "env": {}
236 }
237 }
238}
239```
240
241This can be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it.
242
243It'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.
244
245## Debugging Agents
246
247When using external agents in Zed, you can access the debug view via with `dev: open acp logs` from the Command Palette.
248This lets you see the messages being sent and received between Zed and the agent.
249
250
251
252It's helpful to attach data from this view if you're opening issues about problems with external agents like Claude Agent, Codex, OpenCode, etc.
253
254## MCP Servers
255
256Note that for external agents, access to MCP servers [installed from Zed](./mcp.md) may vary depending on the ACP implementation.
257For example, Claude Agent and Codex both support it, but Gemini CLI does not yet.