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
8## Gemini CLI {#gemini-cli}
9
10Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md).
11
12Under the hood we run Gemini CLI in the background, and talk to it over ACP.
13This 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.
14
15### Getting Started
16
17As 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.
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` command to include:
20
21```json
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/zed-industries/claude-code-acp). This installation is only available to Zed and is kept up to date as you use the agent.
34
35By 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:
36
37```json
38{
39 "agent_servers": {
40 "gemini": {
41 "ignore_system_version": false
42 }
43 }
44}
45```
46
47#### Authentication
48
49After you have Gemini CLI running, you'll be prompted to choose your authentication method.
50
51Most 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.
52
53You 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.
54
55The "Vertex AI" option is for those who are using [Vertex AI](https://cloud.google.com/vertex-ai), and have already configured their environment correctly.
56
57For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).
58
59### Usage
60
61Similar to Zed's first-party agent, you can use Gemini CLI to do anything that you need.
62And to give it context, you can @-mention files, recent threads, symbols, or fetch the web.
63
64> 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.
65> We hope to add these features in the near future.
66
67## Claude Code
68
69Similar to Gemini CLI, you can also run [Claude Code](https://www.anthropic.com/claude-code) directly via Zed's [agent panel](./agent-panel.md).
70Under the hood, Zed runs Claude Code and communicate to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/claude-code-acp).
71
72### Getting Started
73
74Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Claude Code thread.
75
76If 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:
77
78```json
79[
80 {
81 "bindings": {
82 "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude_code" }]
83 }
84 }
85]
86```
87
88#### Installation
89
90The 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.
91
92Zed will always use this managed version of Claude Code even if you have it installed globally.
93
94### Usage
95
96Similar to Zed's first-party agent, you can use Claude Code to do anything that you need.
97And to give it context, you can @-mention files, recent threads, symbols, or fetch the web.
98
99In 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.
100However, the SDK doesn't yet expose everything needed to fully support all of them:
101
102- 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.
103- [Subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) are supported.
104- [Hooks](https://docs.anthropic.com/en/docs/claude-code/hooks-guide) are currently _not_ supported.
105
106> 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.
107> We hope to add these features in the near future.
108
109#### CLAUDE.md
110
111Claude Code in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory.
112
113If you don't have a `CLAUDE.md` file, you can ask Claude Code to create one for you through the `init` slash command.
114
115## Add Custom Agents {#add-custom-agents}
116
117You can run any agent speaking ACP in Zed by changing your settings as follows:
118
119```json
120{
121 "agent_servers": {
122 "Custom Agent": {
123 "command": "node",
124 "args": ["~/projects/agent/index.js", "--acp"],
125 "env": {}
126 }
127 }
128}
129```
130
131This 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.
132
133You can also specify a custom path, arguments, or environment for the builtin integrations by using the `claude` and `gemini` names.
134
135## Debugging Agents
136
137When 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.
138
139