Zed’s AI Agent: Built-In Agent, ACP and Claude Code

Zed AI is the set of AI features in Zed, the open-source code editor, and its center is the Agent Panel. From there you can run three kinds of agent. The Zed Agent is Zed’s own, running on whichever models you configure. External Agents are other companies’ agents, such as Claude, Codex, Gemini CLI, OpenCode, Copilot and Cursor, connected through the Agent Client Protocol (ACP) and keeping their own sign-in and billing. Terminal Threads run any agent CLI, Claude Code included, in a terminal that Zed organizes like a thread. Zed also supports MCP servers, reads AGENTS.md and other instructions files, and lets you run several agents at once in separate Git worktrees.

The Agent Panel

Open it with agent: new thread from the Command Palette or the sparkle icon in the status bar. Zed’s Agent Panel documentation↗ (opens in a new tab) covers what happens there:

• Context: type @ to mention files, directories, symbols, earlier threads, skills, diagnostics, branch diffs or URLs, or add a selection from the editor or terminal.
• Checkpoints: after every edit a Restore Checkpoint button takes the code back to where it was before that message, even if you stopped the agent midway.
• Review: Review Changes opens a multibuffer with every edit, and you keep or reject each hunk or the whole set.
• Queued messages: anything you send while the agent works is queued; with the Zed Agent, Steer delivers it at the next step instead of waiting.
• Compaction: long Zed Agent threads are summarized automatically near the token limit, or with /compact.
• Parallel threads: the Threads Sidebar groups every thread by project, and the worktree picker puts a thread in its own Git worktree so two agents do not edit the same files.

Some of these depend on the agent. Zed notes that checkpoints, restoring threads from history and token counts vary for External Agents, and Steer works only with the Zed Agent because Zed cannot see an external agent’s turn boundaries.

Models and providers for the Zed Agent

The Zed Agent runs on models you choose from the model selector. Zed’s LLM providers page lists five routes: Zed-hosted models billed through a Zed plan, which currently include Anthropic’s Claude, OpenAI’s GPT and Google’s Gemini models; your own API keys; an existing subscription where Zed supports it, such as ChatGPT Plus or Pro or GitHub Copilot; a gateway such as OpenRouter, Vercel AI Gateway or Amazon Bedrock; or a local model through Ollama, LM Studio or llama.cpp. Keys you save are stored in the system keychain, not in settings.json.

One subscription does not work this way: Zed says Claude Pro and Max have no direct provider path in Zed. To use a Claude subscription, run Claude as an External Agent or Claude Code in a Terminal Thread, both covered below.

The Zed Agent’s behavior is shaped by profiles and permissions. The built-in profiles are Write, which can read, edit and run commands; Ask, for read-only questions; and Minimal, with no project tools. Tool permissions decide what runs without asking: the default is confirm, per-tool rules can always allow, always confirm or always deny by regex, and a few rules that block rm -rf on the root, home or current directory cannot be overridden.

External agents over ACP: Claude, Gemini CLI and others

The Agent Client Protocol↗ (opens in a new tab) standardizes how editors talk to coding agents, much as the Language Server Protocol did for language tools. Local agents run as a subprocess of the editor and talk JSON-RPC over stdio; remote agents are a work in progress. Zed created ACP, and other editors now use it too, including JetBrains IDEs and Devin Desktop.

In Zed, you install these agents from the ACP Registry (zed: acp registry, or Add Agent in Agent Settings) and pick one from the new-thread menu. Zed’s External Agents page↗ (opens in a new tab) lists Claude, Codex, OpenCode, Copilot, Cursor and Pi as common choices, with setup notes for Gemini CLI and Poolside too, and says the list is curated rather than complete. The dividing line is ownership: the external agent runs as its own process and usually owns its model choice, sign-in, tools and billing, and Zed does not charge for it. Zed profiles and skills do not apply to it.

• Claude Agent: install it from the registry, open a thread and run /login to choose an API key or Claude Code sign-in. An Anthropic key set for the Zed Agent does not carry over, and the agent may read CLAUDE.md itself.
• Gemini CLI: signs in with Google, Vertex AI or another Gemini route. If you set a Google AI key for Zed, Zed passes it to Gemini CLI as GEMINI_API_KEY.
• Codex: uses its own login, whether ChatGPT, a Codex key or an OpenAI key.
• Your own agent: add a custom entry under agent_servers with the command that starts it.

Agents installed as Zed extensions are deprecated; the registry replaced them, and old extension agents are migrated automatically. To debug the connection, run dev: open acp logs.

Claude Code in a terminal thread

If you prefer Claude Code’s own interface, open a Terminal Thread from the Agent Panel’s new-thread menu. The CLI keeps its own sign-in, settings, instructions and MCP configuration, and Zed only organizes the session beside your other threads. Set agent.terminal_init_command to claude to start it automatically in every new terminal thread, and set Claude Code’s notification channel to the terminal bell so Zed tells you when it finishes or needs permission. Claude Code inside other editors is covered in Claude Code in VS Code and Claude Code in JetBrains.

MCP: context servers

Zed’s settings call MCP servers context servers. According to Zed’s MCP documentation↗ (opens in a new tab), it currently supports MCP’s tools and prompts, reloads a server’s tool list when it changes, and connects local servers by command and remote servers by URL. When a remote server has no Authorization header configured, Zed runs the standard MCP OAuth flow. Add servers under Settings > AI > MCP Servers or directly in your settings file; a green dot means the server is active.

{
  "context_servers": {
    "fenbs": {
      "url": "https://fenbs.ai/api/mcp"
    }
  },
  "agent": {
    "terminal_init_command": "claude"
  }
}

MCP tools pass through the same permissions as built-in tools, keyed as mcp:<server>:<tool>, so you can require confirmation for one write tool and allow the rest. Servers you configure in Zed may be forwarded to External Agents over ACP, while Terminal Threads read only the CLI’s own configuration. If a tool is missing in an external agent, check both places.

Rules are now Instructions and Skills

Zed used to have a Rules feature. Its Instructions page↗ (opens in a new tab) now says Rules have been replaced: always-on rules become personal instructions in ~/.config/zed/AGENTS.md (on Windows, %APPDATA%\Zed\AGENTS.md), and reusable, on-demand rules become Skills. For a project, Zed uses the first file it finds in this order: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. Project instructions win over personal ones.

Two traps follow. First, a leftover .cursorrules or .rules file is picked before your AGENTS.md, so delete stale ones. Second, this loader serves the Zed Agent only; External Agents and Terminal Threads read their own files, so Claude reads CLAUDE.md natively whatever Zed does. Keeping one shared AGENTS.md is covered in AI context files compared.

Privacy

Zed’s AI privacy page says Zed does not retain prompts or code context by default, and that for Zed-hosted models its provider agreements prohibit training and require zero data retention, except for models a provider designates for safety retention; it names Anthropic’s Claude Fable models, which Anthropic retains for at least 30 days. Zed keeps AI data only when you rate a response or opt in to edit prediction training data. With your own key, a gateway or an external agent, that provider’s terms apply instead. On the Business plan, admins can switch off hosted models, edit predictions and feedback for the whole organization.

Where Zed fits next to Cursor

Cursor is an editor built around one agent, its own, with cloud agents and a CLI. Zed is an editor that hosts agents: its own, and any that speak ACP, including Cursor’s. Pick Zed if you want a fast native editor and the freedom to switch agents without switching editors; pick Cursor if you want its agent, rules system and cloud agents as one product. The other options are mapped in Cursor alternatives.

Whichever agent you run in Zed, the list of work should outlive the thread. With fenbs added as a context server, the Zed Agent reads the same tasks as Claude Code in the next thread: lanes To Do, Next Up, In Progress and Completed, each task with a note, a plan and a test status, and History recording which assistant changed what. Sign in with OAuth when Zed prompts, or issue a token with a name, scopes and an optional expiry.