1# External Agents
2
3Zed supports terminal-based agents 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) is also included by default, and you can [add custom ACP-compatible agents](#add-custom-agents) as well.
7
8Zed's affordance for external agents is strictly UI-based; the billing and legal/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.
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).
13
14Under the hood we run Gemini CLI in the background, and talk to it over ACP.
15This 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.
16
17### Getting Started
18
19As 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.
20
21If 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:
22
23```json [keymap]
24[
25 {
26 "bindings": {
27 "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }]
28 }
29 }
30]
31```
32
33#### Installation
34
35The first time you create a Gemini CLI thread, Zed will install [@google/gemini-cli](https://github.com/zed-industries/claude-code-acp). This installation is only available to Zed and is kept up to date as you use the agent.
36
37By 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:
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". This 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.
54
55You can also use the "Gemini API Key". If you select this, and have the `GEMINI_API_KEY` set, then we will use that. Otherwise 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.
56
57The "Vertex AI" option is for those who are using [Vertex AI](https://cloud.google.com/vertex-ai), and have already configured their environment correctly.
58
59For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).
60
61### Usage
62
63Similar to Zed's first-party agent, you can use Gemini CLI to do anything that you need.
64And to give it context, you can @-mention files, recent threads, symbols, or fetch the web.
65
66> Note that some first-party agent features don't yet work with Gemini CLI: editing past messages, resuming threads from history, checkpointing, and using the agent in SSH projects.
67> We hope to add these features in the near future.
68
69## Claude Code
70
71Similar to Gemini CLI, you can also run [Claude Code](https://www.anthropic.com/claude-code) directly via Zed's [agent panel](./agent-panel.md).
72Under the hood, Zed runs Claude Code and communicate to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/claude-code-acp).
73
74### Getting Started
75
76Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Claude Code thread.
77
78If 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:
79
80```json [keymap]
81[
82 {
83 "bindings": {
84 "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude_code" }]
85 }
86 }
87]
88```
89
90### Authentication
91
92As 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. 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 Code for authentication and billing.
93
94To ensure you're using your billing method of choice, [open a new Claude Code 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.
95
96#### Installation
97
98The first time you create a Claude Code thread, Zed will install [@zed-industries/claude-code-acp](https://github.com/zed-industries/claude-code-acp). This installation is only available to Zed and is kept up to date as you use the agent.
99
100Zed 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.
101
102If 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.
103
104```json
105{
106 "agent_servers": {
107 "claude": {
108 "env": {
109 "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable"
110 }
111 }
112 }
113}
114```
115
116## Codex CLI
117
118You can also run [Codex CLI](https://github.com/openai/codex) directly via Zed's [agent panel](./agent-panel.md).
119Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/codex-acp).
120
121### Getting Started
122
123As of Zed Stable v0.208 you should be able to use Codex directly from Zed. Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Codex thread.
124
125If 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:
126
127```json
128[
129 {
130 "bindings": {
131 "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "codex" }]
132 }
133 }
134]
135```
136
137### Authentication
138
139Authentication 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.
140
141To 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:
142
1431. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_
1442. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`.
1453. `OPENAI_API_KEY` - uses an API key you have set in your environment under the variable `OPENAI_API_KEY`.
146
147If you are already logged in and want to change your authentication method, type `/logout` in the thread and authenticate again.
148
149#### Installation
150
151The 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.
152
153Zed will always use this managed version of Codex even if you have it installed globally.
154
155### Usage
156
157Similar to Zed's first-party agent, you can use Claude Code to do anything that you need.
158And to give it context, you can @-mention files, recent threads, symbols, or fetch the web.
159
160In 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.
161However, the SDK doesn't yet expose everything needed to fully support all of them:
162
163- 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.
164- [Subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) are supported.
165- [Hooks](https://docs.anthropic.com/en/docs/claude-code/hooks-guide) are currently _not_ supported.
166
167> 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, checkpointing, and using the agent in SSH projects.
168> We hope to add these features in the near future.
169
170#### CLAUDE.md
171
172Claude Code in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory.
173
174If you don't have a `CLAUDE.md` file, you can ask Claude Code to create one for you through the `init` slash command.
175
176## Add Custom Agents {#add-custom-agents}
177
178You can run any agent speaking ACP in Zed by changing your settings as follows:
179
180```json [settings]
181{
182 "agent_servers": {
183 "Custom Agent": {
184 "command": "node",
185 "args": ["~/projects/agent/index.js", "--acp"],
186 "env": {}
187 }
188 }
189}
190```
191
192This can also be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it.
193
194You can also specify a custom path, arguments, or environment for the builtin integrations by using the `claude` and `gemini` names.
195
196## Debugging Agents
197
198When using external agents in Zed, you can access the debug view via with `dev: open acp logs` from the Command Palette. This lets you see the messages being sent and received between Zed and the agent.
199
200