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