Skip to content
AgentAtlas

Use Claude, Codex and Gemini CLI in Zed: External Agents and agent_servers (ACP)

How do I use Claude, Codex or Gemini CLI as an agent inside Zed?

Install them as External Agents from the ACP Registry with the zed: acp registry command, then start a thread from the Agent Panel agent selector. Each external agent handles its own login and billing. For agents not in the registry, add a custom entry under agent_servers in your settings.

Install an agent from the registry

  • Run the command zed: acp registry.
  • Or run agent: open settings, open External Agents, click Add Agent, and choose Install from Registry.
  • Agents covered in the docs include Claude Agent, Codex, Gemini CLI, OpenCode, Copilot, Cursor, Pi Coding Agent and Poolside.

Start a thread

Open the Agent Panel and pick the agent from the agent selector or the new thread menu. To bind a key to a specific agent, use the action agent: new external agent thread.

Sign in

  • Claude Agent: run /login in a Claude Agent thread to choose billing. An Anthropic key set for Zed Agent does not configure it.
  • Codex: use the thread's own login flow. An OpenAI key set for Zed Agent does not configure it.
  • Gemini CLI: uses GEMINI_API_KEY or GOOGLE_AI_API_KEY if set. Otherwise Zed passes your Google AI provider key as GEMINI_API_KEY.
  • Zed does not charge for External Agents. Billing is between you and the provider.

Add a custom ACP agent

Open Agent Settings, go to External Agents, click Add Agent, and choose Add Custom Agent. Zed opens your settings with an agent_servers entry.

Zed settings

{
  "agent_servers": {
    "my-agent": {
      "type": "custom",
      "command": "node",
      "args": ["~/projects/agent/index.js", "--acp"],
      "env": {}
    }
  }
}

Registry agents can also take per agent settings under agent_servers.<agent-id>.

What carries over and what does not

  • Zed Agent profiles and Zed Skills generally do not apply to external agent threads.
  • The agent owns its model, provider and auth.
  • Zed MCP servers may be forwarded over ACP, and the agent may also read its own MCP config. Check both if a tool is missing.
  • Tool permissions depend on Zed's ACP forwarding and the agent's own settings.
  • Extension provided agents are deprecated and migrate to registry versions.
  • For debugging, run dev: open acp logs.

Sources

More Zed guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →