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

• 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.

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.

• 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.

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

{
  "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>.

• 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.