Zed + Claude Code via ACP: Setup (2026)

Run Claude Code in Zed's agent panel via ACP, or add QCode.cc as an Anthropic- or OpenAI-compatible provider in settings.json; 1M context on Opus 5 / 4.8 / 4.7.

Need an API key? Sign up →·Endpoints & base URLs →

Last verified: 2026-09-18 · 📄 Per official docs (Zed stable v1.20.2, released 2026-09-17)

At a glance¶

QCode uses a single API Key throughout (starting with cr_). The same key supports the Anthropic, OpenAI Chat, OpenAI Responses, and image protocols, and maps to three ingress domains — api / asia / us (mainland-China users should prefer asia.qcode.cc).

Why Use Zed¶

• Native ACP integration: open Claude Code sessions inside the agent panel and watch agent reasoning plus tool calls live in the editor
• 1M context: BYOK mode supports the full 1M-token context window of Opus 5 / 4.8 / 4.7
• Rust performance: blazingly fast cold start and an order of magnitude lower memory footprint than VS Code / Electron-based editors
• Multi-pane layout: editor + terminal + agent panel side-by-side for a compact workflow
• Two integration paths: run via the Claude Code CLI (full tool surface), or add QCode as a built-in provider in settings.json

Comparing the Two Integration Paths¶

Zed offers two complementary paths to reach QCode — pick based on your needs:

The "Configuration Steps" section below covers Path A; "Configuring a Provider in settings.json" covers Path B.

Prerequisites¶

• Zed installed (macOS / Linux)
• Claude Code CLI installed (Zed's ACP integration uses the CLI as the backend; skip this if you only use Path B)
• A QCode.cc API Key (starts with cr_), available from the dashboard
• Claude Code CLI already configured with QCode environment variables (per the Quick Start)

Configuration Steps (Path A: ACP / Claude Code)¶

Step 1: Verify the Claude Code CLI Works in Your Terminal¶

Zed launches ACP by spawning a claude process, so verify the CLI works in a terminal first:

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_xxxxxxxx"
claude --version   # should print a version number (trust this machine + official Releases)
echo "ping" | claude   # simple echo test

ANTHROPIC_BASE_URL must not have a trailing slash; the Anthropic SDK appends /v1/messages itself. Persist these two environment variables in your shell config (~/.zshrc / ~/.bashrc) so Zed inherits them at startup.

Step 2: Open Zed's Agent Panel¶

• macOS: Cmd + ?
• Linux: Ctrl + ?

The first time you open it, Zed asks you to choose an agent provider — pick Claude Code (do not pick BYOK Anthropic API; that path bypasses the CLI and requires you to fill in a base URL separately in Zed settings — see Path B).

Step 3: Verify the Agent Session¶

Type into the agent panel input: "List the exported symbols in the current file." Zed passes the currently open file as context to Claude Code, and the agent invokes the read / grep tools to parse and respond.

If the agent process fails to start, the ACP agent command can be pinned explicitly via agent_servers.<name>.command / args / env in settings.json (there is no agent.path setting key). Names and fields: follow the official docs.

Zed's agent / assistant settings evolve quickly between releases; for exact key names, defer to the Zed official docs.

Configuring a Provider in settings.json (Path B)¶

If you'd rather not install the CLI, add QCode in settings.json — the JSON file itself opens via Cmd+Alt+, (Ctrl+Alt+, on Linux; Cmd+, opens the settings editor UI); it lives at ~/.config/zed/settings.json (Windows: %APPDATA%/Zed/settings.json) and applies without a restart. For third-party gateways the officially recommended entries are the anthropic_compatible / openai_compatible custom providers. QCode speaks both protocols with the same cr_ key.

Anthropic-Compatible Provider¶

Point Zed's built-in Anthropic provider base at QCode's Anthropic endpoint:

{
  "language_models": {
    "anthropic_compatible": {
      "QCode": {
        "api_url": "https://api.qcode.cc/api"
      }
    }
  }
}

Supply the key via an environment variable (inherited by Zed at startup):

export QCODE_API_KEY="cr_xxxxxxxx"

The built-in language_models.anthropic.api_url also exists and works, but Zed's documented entry point for third-party gateways is the anthropic_compatible provider shown above. The base URL ends at /api — no /v1 — Zed appends /v1/messages itself. Do not put API keys in settings.json (official rule); use the generated <PROVIDER_NAME>_API_KEY variable.

OpenAI-Compatible Provider¶

Zed also supports an OpenAI-compatible provider, which can reach QCode's GPT-family models. Point the base at QCode's OpenAI Chat endpoint:

{
  "language_models": {
    "openai_compatible": {
      "QCodeOpenAI": {
        "api_url": "https://api.qcode.cc/openai/v1",
        "available_models": [
          { "name": "gpt-5.6-terra" },
          { "name": "gpt-5.6" },
          { "name": "glm-5.3" },
          { "name": "deepseek-v4-flash" }
        ]
      }
    }
  }
}

The key also comes from an environment variable:

export QCODEOPENAI_API_KEY="cr_xxxxxxxx"

The OpenAI Chat base is https://api.qcode.cc/openai/v1 (the SDK then appends /chat/completions). No trailing slash. The field names in available_models (name / max_tokens, etc.) should follow the Zed official docs.

Model Selection¶

The same QCode key exposes models from multiple vendors. Switch as needed from the model dropdown in the agent panel or assistant:

Which protocol: claude-* only works on the Anthropic provider (https://api.qcode.cc/api); gpt-* only works on the OpenAI provider (https://api.qcode.cc/openai/v1). Mixing them returns model_not_available_on_endpoint.

The table above is the current recommendation. 4.x IDs such as claude-sonnet-4-6, claude-opus-4-8, and claude-opus-4-7 remain on sale; the live list is qcode.cc/models.

• On Path A (Claude Code), the model is determined by Claude Code's own configuration (switch with /model or set ANTHROPIC_MODEL).
• On Path B with the Anthropic provider, use claude-* model IDs; with the OpenAI provider, use gpt-* model IDs.
• The image (gpt-image-2) protocol isn't necessarily exposed natively in Zed's assistant; call it directly from the CLI / scripts — see Endpoints and API Paths and gpt-image-2 Image Generation.

Usage Examples¶

Agent Panel: Cross-File Tasks¶

The agent panel shines on multi-step, cross-file tasks. For example:

"Convert all synchronous IO under utils/ to async and update the callers."

The agent will grep to locate, read to inspect, and edit to modify, showing diffs step by step in the editor so you can accept / reject each one.

Feeding Screenshots to the Agent (Vision Input)¶

Claude Opus 5 / Sonnet 5 and GPT-5.x are all vision-capable. You can hand UI mockups, error screenshots, or architecture diagrams to the agent as input:

• Paste an image (Ctrl+V) or drag-drop it into the agent panel input
• Or reference a local image file path in your prompt

Typical use cases: build UI from a mockup, debug from an error screenshot, read architecture diagrams / charts.

Note: this is about feeding images to the model (vision input), not generating images. To generate images use gpt-image-2 — see gpt-image-2 Image Generation.

Dynamic Workflows (Background Sub-Agent Orchestration)¶

Claude Code supports Dynamic Workflows: orchestrate tens to hundreds of background sub-agents, ideal for codebase-wide review, migration, and research tasks. Trigger it by including the keyword ultracode in your prompt or simply asking to "run a workflow"; view active runs with the /workflows command. Sub-agents keep running in the background while you continue other work. It runs on whatever model Claude Code is configured with — so it works when Claude Code points at QCode. Further reading: Subagents.

Headless / Automation Output Formats¶

When calling Claude Code in CI / scripts, use claude -p with --output-format:

# JSON: one structured object with result / total_cost_usd / usage / session_id
claude -p "Summarize this change" --output-format json | jq .result

# stream-json: newline-delimited JSON event stream, good for real-time pipelines
claude -p "Refactor this module" --output-format stream-json

# text: plain text (default)
claude -p "Explain this code" --output-format text

More usage in Automation & CI/CD.

Other Endpoints¶

If the current endpoint is unreachable, switch ANTHROPIC_BASE_URL (or the api_url in settings.json):

For the OpenAI-compatible path, swap the domain the same way — e.g., the Asia OpenAI Chat base is https://asia.qcode.cc/openai/v1. For the full endpoint reference, see Endpoints and API Paths.

Shared Quota¶

The Claude Code agent inside Zed shares the same QCode API Key and quota with the CLI / Claude Desktop / Codex CLI — there is no double-billing. Path A and Path B also share the same key's quota. See Billing for details.

Limitations and Notes¶

• Zed's BYOK Anthropic direct mode uses Zed's built-in Anthropic provider and does not go through the Claude Code CLI. It requires you to manually set api_url in Zed settings to point at QCode (Path B). The ACP / Claude Code mode covered here (Path A) is preferred — it preserves the full CLI tool surface (hooks, skills, MCP).
• The base URL must not have a trailing slash. A self-check request hitting a base path returns 401, which is expected (the path is correct, it just lacks auth).
• The ACP integration is in Public Beta (since 2026-04); a few APIs may still change. If you observe behavioral differences, the Zed official documentation is authoritative.
• Linux sandbox users: if Zed is installed via Flatpak, spawning the claude subprocess may be blocked by the sandbox. We recommend installing the .deb / AppImage / Homebrew build directly.
• The Gemini CLI is retired (EOL 2026-06-18 for the non-enterprise editions; enterprise paid keys unaffected); its successor is the Google Antigravity CLI. Note that Antigravity CLI only accepts a Gemini-compatible endpoint (via GOOGLE_GEMINI_BASE_URL), not an OpenAI-compatible one. QCode does not currently offer Gemini models — see Antigravity CLI.

FAQ¶

Agent panel reports "Failed to start agent"¶

• Does claude start correctly in your terminal? Rule out CLI-side configuration issues first.
• Did Zed inherit the ANTHROPIC_* environment variables? On macOS, launching Zed via open -a Zed from the terminal guarantees inheritance.
• Does the agent.path in your settings point to a valid path? Verify with which claude.

settings.json provider returns 401 / auth failure¶

• Confirm the right environment variable is set and is a cr_-prefixed QCode key: custom providers use <PROVIDER_NAME>_API_KEY (e.g. QCODE_API_KEY / QCODEOPENAI_API_KEY); only the built-in providers use ANTHROPIC_API_KEY / OPENAI_API_KEY.
• Did Zed inherit that environment variable? Launch Zed from the terminal to verify.
• Did api_url accidentally get a trailing slash? Remove it.

The model I want isn't in the dropdown¶

• The Path B OpenAI provider requires models to be listed explicitly in available_models before they appear in the dropdown.
• Path A's available models are determined by Claude Code; use /model to view and switch.

"Invalid model" / 404¶

• Double-check the model ID spelling matches the table exactly (e.g., claude-opus-5).
• Make sure the base URL protocol matches the model: claude-* uses the Anthropic endpoint, gpt-* uses the OpenAI endpoint.

Difference vs. BYOK Anthropic Mode¶

Next Steps¶

• Claude Code Tutorial — full CLI feature reference
• Endpoints and API Paths — full reference for all three ingress domains
• Subagents — Dynamic Workflows and multi-agent orchestration
• Automation & CI/CD — headless mode and output formats
• gpt-image-2 Image Generation — image generation (distinct from vision input)
• VS Code Integration — comparison with Electron-based editors
• Billing — shared quota rules

Want live pricing and context specs for each model? Head to the QCode pricing page.

Enterprise →