1# External Agents
2
3Zed supports many external agents, including CLI-based ones, through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
4
5Currently, [Gemini CLI](https://github.com/google-gemini/gemini-cli) serves as the reference implementation.
6[Claude Code](https://www.anthropic.com/claude-code) and [Codex](https://developers.openai.com/codex) are also included by default, and you can [add more custom ACP-compatible agents](#add-more-agents) as well.
7
8> 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.
9> 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.
10
11## Gemini CLI {#gemini-cli}
12
13Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md).
14
15Under the hood we run Gemini CLI in the background, and talk to it over ACP.
16This means that you're running the real Gemini CLI, with all of the advantages of that, but you can see and interact with files in your editor.
17
18### Getting Started
19
20As of [Zed Stable v0.201.5](https://zed.dev/releases/stable/0.201.5) you should be able to use Gemini CLI directly from Zed. First open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Gemini CLI thread.
21
22If 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` command to include:
23
24```json [keymap]
25[
26 {
27 "bindings": {
28 "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }]
29 }
30 }
31]
32```
33
34#### Installation
35
36The 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.
37
38By default, Zed will use this managed version of Gemini CLI even if you have it installed globally. However, you can configure it to use a version in your `PATH` by adding this to your settings:
39
40```json [settings]
41{
42 "agent_servers": {
43 "gemini": {
44 "ignore_system_version": false
45 }
46 }
47}
48```
49
50#### Authentication
51
52After you have Gemini CLI running, you'll be prompted to choose your authentication method.
53
54Most users should click the "Log in with Google".
55This will cause a browser window to pop-up and auth directly with Gemini CLI. Zed does not see your OAuth or access tokens in this case.
56
57You can also use the "Gemini API Key". If you select this, and have the `GEMINI_API_KEY` set, then we will use that.
58Otherwise Zed will prompt you for an API key which will be stored securely in your keychain, and used to start Gemini CLI from within Zed.
59
60The "Vertex AI" option is for those who are using [Vertex AI](https://cloud.google.com/vertex-ai), and have already configured their environment correctly.
61
62For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).
63
64### Usage
65
66Similar to Zed's first-party agent, you can use Gemini CLI to do anything that you need.
67And to give it context, you can @-mention files, recent threads, symbols, or fetch the web.
68
69> Note that some first-party agent features don't yet work with Gemini CLI: editing past messages, resuming threads from history, and checkpointing.
70> We hope to add these features in the near future.
71
72## Claude Code
73
74Similar to Gemini CLI, you can also run [Claude Code](https://www.anthropic.com/claude-code) directly via Zed's [agent panel](./agent-panel.md).
75Under the hood, Zed runs Claude Code and communicate to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/claude-code-acp).
76
77### Getting Started
78
79Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Claude Code thread.
80
81If 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` command to include:
82
83```json [keymap]
84[
85 {
86 "bindings": {
87 "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude_code" }]
88 }
89 }
90]
91```
92
93### Authentication
94
95As of version `0.202.7` (stable) and `0.203.2` (preview), authentication to Zed's Claude Code installation is decoupled entirely from Zed's agent.
96That is to say, an Anthropic API key added via the [Zed Agent's settings](./llm-providers.md#anthropic) will _not_ be utilized by Claude Code for authentication and billing.
97
98To ensure you're using your billing method of choice, [open a new Claude Code thread](./agent-panel.md#new-thread).
99Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription.
100
101#### Installation
102
103The first time you create a Claude Code thread, Zed will install [@zed-industries/claude-code-acp](https://github.com/zed-industries/claude-code-acp).
104This installation is only available to Zed and is kept up to date as you use the agent.
105
106Zed will always use this managed version of the Claude Code adapter, which includes a vendored version of the Claude Code CLI, even if you have it installed globally.
107
108If 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.
109
110```json
111{
112 "agent_servers": {
113 "claude": {
114 "env": {
115 "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable"
116 }
117 }
118 }
119}
120```
121
122### Usage
123
124Similar to Zed's first-party agent, you can use Claude Code to do anything that you need.
125And to give it context, you can @-mention files, recent threads, symbols, or fetch the web.
126
127In complement to talking to it [over ACP](https://agentclientprotocol.com), Zed relies on the [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview) to support some of its specific features.
128However, the SDK doesn't yet expose everything needed to fully support all of them:
129
130- Slash Commands: A subset of [built-in commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands#built-in-slash-commands) are supported, while [custom slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands#custom-slash-commands) are fully supported.
131- [Subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) are supported.
132- [Hooks](https://docs.anthropic.com/en/docs/claude-code/hooks-guide) are currently _not_ supported.
133
134> Also note that some [first-party agent](./agent-panel.md) features don't yet work with Claude Code: editing past messages, resuming threads from history, and checkpointing.
135> We hope to add these features in the near future.
136
137#### CLAUDE.md
138
139Claude Code in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory.
140
141If you don't have a `CLAUDE.md` file, you can ask Claude Code to create one for you through the `init` slash command.
142
143## Codex CLI
144
145You can also run [Codex CLI](https://github.com/openai/codex) directly via Zed's [agent panel](./agent-panel.md).
146Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/codex-acp).
147
148### Getting Started
149
150As of Zed Stable v0.208 you should be able to use Codex directly from Zed.
151Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Codex thread.
152
153If 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` command to include:
154
155```json
156[
157 {
158 "bindings": {
159 "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "codex" }]
160 }
161 }
162]
163```
164
165### Authentication
166
167Authentication to Zed's Codex installation is decoupled entirely from Zed's agent.
168That 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.
169
170To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread).
171The first time you will be prompted to authenticate with one of three methods:
172
1731. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_
1742. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`.
1753. `OPENAI_API_KEY` - uses an API key you have set in your environment under the variable `OPENAI_API_KEY`.
176
177If you are already logged in and want to change your authentication method, type `/logout` in the thread and authenticate again.
178
179If 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.
180
181#### Installation
182
183The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp).
184This installation is only available to Zed and is kept up to date as you use the agent.
185
186Zed will always use this managed version of Codex even if you have it installed globally.
187
188### Usage
189
190Similar to Zed's first-party agent, you can use Codex to do anything that you need.
191And to give it context, you can @-mention files, symbols, or fetch the web.
192
193> Note that some first-party agent features don't yet work with Codex: editing past messages, resuming threads from history, and checkpointing.
194> We hope to add these features in the near future.
195
196## Add More Agents {#add-more-agents}
197
198### Via Agent Server Extensions
199
200<div class="warning">
201
202Note that starting from v0.221.x, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
203Learn more about it in [the release blog post](https://zed.dev/blog/acp-registry).
204At some point in the near future, Agent Server extensions should be deprecated.
205
206</div>
207
208Add more external agents to Zed by installing [Agent Server extensions](../extensions/agent-servers.md).
209
210See 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).
211
212### Via The ACP Registry
213
214#### Overview
215
216As mentioned above, the Agent Server extensions should be deprecated in the near future to give room to the ACP Registry.
217
218[The ACP Registry](https://github.com/agentclientprotocol/registry) is an easy way for developers to distribute their ACP-compatible agents to any client that speaks the protocol.
219And for clients, it's the easiest way to get the latest version of the agent.
220
221At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods).
222
223#### Using it in Zed
224
225Use the `zed: acp registry` command to quickly go to the ACP Registry page.
226There's also a button ("Add Agent") that takes you there in the Agent Pane's configuration view.
227
228From there, you can just install agents from the registry and use them right away in Zed's Agent Panel.
229
230If you installed the same agent through both the extension and the registry, the registry version takes precedence.
231
232### Custom Agents
233
234You can also add agents through your `settings.json`, by specifying certain fields under `agent_servers`, like so:
235
236```json [settings]
237{
238 "agent_servers": {
239 "My Custom Agent": {
240 "type": "custom",
241 "command": "node",
242 "args": ["~/projects/agent/index.js", "--acp"],
243 "env": {}
244 }
245 }
246}
247```
248
249This can be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it.
250
251It's also possible to specify a custom path, arguments, or environment for the builtin integrations by using the `claude` and `gemini` names.
252
253## Debugging Agents
254
255When using external agents in Zed, you can access the debug view via with `dev: open acp logs` from the Command Palette.
256This lets you see the messages being sent and received between Zed and the agent.
257
258
259
260## MCP Servers
261
262Note that for external agents, access to MCP servers [installed from Zed](./mcp.md) may vary depending on the ACP agent implementation.
263
264Regarding the built-in ones, Claude Code and Codex both support it, and Gemini CLI does not yet.
265In the meantime, learn how to add MCP server support to Gemini CLI through [their documentation](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#using-mcp-servers).