The Zed Agent Cockpit

Why Zed, why now: the $10-vs-$0 math

Zed shipped 1.0 in April 2026 with parallel agents and full Mac/Windows/Linux parity, and as of July 2026 it's at ~1.4.x. The speed story is real, not marketing: Rust and GPU-native rendering at ~120fps, files open roughly 5x faster than Cursor, and it idles at 200-400MB of RAM where Cursor sits at 500-800MB.

But speed isn't why I moved my agent work here. The economics are. On May 6, 2026 Zed cut Pro from $20 to $10/mo, and more importantly: BYO API keys and external agents are unlimited and free, even on the Free plan. Zed takes zero cut of your Anthropic/OpenAI/Google spend. Cursor and Zed's own hosted plan both mark up heavy usage (Zed's hosted overage is API list price +10%). If you're burning $200+/mo in tokens, the editor that charges you nothing to bring your own key wins on math alone.

The other reason: ACP openness. Zed co-created the Agent Client Protocol (JetBrains adopted it in late 2025), which means Claude Code, Codex CLI, Gemini CLI, and even Cursor's own agent run side-by-side inside Zed's Agent Panel. No other editor lets you do that. Plus the best MCP control plane I've used (per-tool permissions, profile-based filtering) and real-time human multiplayer with voice.

And where Claude Code beats both on raw autonomy, Zed's answer is not to compete. It's to run Claude Code inside Zed. Section 5 covers that.

The full settings.json: one file, whole cockpit

Everything below lives in one file: ~/.config/zed/settings.json (open with cmd-, in Zed). Zed's settings file accepts comments, so the download is fully annotated. Here's the complete config, then I'll walk the four blocks that matter.

{
  "agent": {
    "default_profile": "write",

    // Cheap-model routing: don't burn Opus on commit messages.
    "inline_assistant_model": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "commit_message_model":  { "provider": "anthropic", "model": "claude-haiku-4-5" },
    "thread_summary_model":  { "provider": "anthropic", "model": "claude-haiku-4-5" },
    "subagent_model":        { "provider": "anthropic", "model": "claude-sonnet-4-5" },

    // Summarize the thread automatically near the context ceiling.
    // Manual trigger any time: /compact
    "auto_compact": { "enabled": true, "threshold": "90%" },

    // Per-model sampling overrides.
    "model_parameters": [
      { "provider": "anthropic", "model": "claude-opus-4-7", "temperature": 0.2 },
      { "temperature": 0.4 } // fallback for everything else
    ],

    // Stop babysitting: get pinged when the agent blocks or finishes.
    "notify_when_agent_waiting": "all_screens",
    "play_sound_when_agent_done": true
  }
}

The routing block is the quiet money-saver. Zed lets you assign a different model to inline assists, commit messages, thread summaries, and subagents. Haiku writes commit messages exactly as well as Opus does, at a fraction of the price. Set it once, forget it.

auto_compact is what keeps 3-hour threads alive. At the 90% threshold Zed summarizes the conversation into a compact context instead of dying at the ceiling. Leave it on; drop the threshold to 80% if you work with huge files.

Tool permissions: allow reads, confirm writes, deny the footguns

"agent": {
  "tool_permissions": {
    // Three values: "allow" | "confirm" | "deny"
    "default": "confirm",

    // Reads are safe. Auto-approve so the agent doesn't nag.
    "read_file": "allow",
    "grep": "allow",
    "find_path": "allow",
    "list_directory": "allow",
    "diagnostics": "allow",

    // Writes: edits fine, terminal asks, deletes never.
    "edit_file": "allow",
    "terminal": "confirm",
    "fetch": "confirm",
    "delete_path": "deny",

    // Per-MCP-tool granularity: "mcp:<server>:<tool>"
    "mcp:github:get_pull_request": "allow",
    "mcp:github:list_issues": "allow",
    "mcp:github:create_pull_request": "confirm",
    "mcp:github:merge_pull_request": "deny",
    "mcp:postgres:query": "allow",
    "mcp:postgres:execute": "deny"
  }
}

The mcp:<server>:<tool> syntax is the part most people miss. You don't approve or reject a whole MCP server; you approve individual tools on it. My rule across every server: reads get allow, mutations get confirm, irreversible mutations (merge, execute, delete) get deny. The agent can still ask you to run those manually, which is exactly the friction you want.

Edit predictions: Zeta 2, and the free local option

"edit_predictions": {
  // Providers (pluggable since Feb 2026):
  // zeta | mercury | sweep | codestral | ollama | copilot
  "provider": "zeta",
  "mode": "eager",
  "disabled_globs": ["**/.env*", "**/secrets/**", "**/*.pem", "**/*.md"]

  // Unlimited + local via Ollama (Zeta 2 is open weights):
  // "provider": "ollama",
  // "ollama": {
  //   "api_url": "http://localhost:11434",
  //   "model": "zeta2",
  //   "prompt_format": "infer",
  //   "max_output_tokens": 512
  // }
}

Zeta 2 is open weights (built on ByteDance's Seed Coder 8B) with ~30% better acceptance than Zeta 1. The free plan caps you at 2,000 accepted predictions/mo on the hosted version. Two ways out: pay the $10, or run Zeta 2 locally through Ollama for unlimited predictions at $0. The disabled_globs line keeps predictions out of your .env files, which you want regardless of provider.

Three profiles: Write, Ask, Review (tool toggles are the product)

Profiles are saved bundles of tool toggles + MCP enablement + a default model, switchable per-thread from the Agent Panel. Zed ships Write, Ask, and Minimal built in. I run three: the built-in Write tuned up, a locked-down Ask, and a custom Review profile that can read code and GitHub but physically cannot edit anything. A review agent that can't touch files can't 'helpfully fix' things mid-review.

"agent": {
  "profiles": {
    "write": {
      "name": "Write",
      "tools": {
        "read_file": true, "grep": true, "find_path": true,
        "list_directory": true, "diagnostics": true,
        "edit_file": true, "terminal": true, "fetch": true,
        "copy_path": true, "create_directory": true,
        "delete_path": false
      },
      "enable_all_context_servers": true,
      "default_model": { "provider": "anthropic", "model": "claude-opus-4-7" }
    },

    "ask": {
      "name": "Ask",
      "tools": {
        "read_file": true, "grep": true, "find_path": true,
        "list_directory": true, "diagnostics": true, "fetch": true,
        "edit_file": false, "terminal": false, "delete_path": false
      },
      "enable_all_context_servers": false,
      "context_servers": {},
      "default_model": { "provider": "anthropic", "model": "claude-sonnet-4-5" }
    },

    "review": {
      "name": "Review",
      "tools": {
        "read_file": true, "grep": true, "find_path": true,
        "list_directory": true, "diagnostics": true,
        "edit_file": false, "terminal": false, "fetch": false,
        "delete_path": false
      },
      "enable_all_context_servers": false,
      "context_servers": { "github": true },
      "default_model": { "provider": "anthropic", "model": "claude-opus-4-7" }
    }
  }
}

Skills replaced Rules in 1.4.2 (and almost nobody noticed)

In 1.4.2 Zed deprecated the Rules Library and split its job in two. Instructions (AGENTS.md and friends) are the always-on layer: injected into every thread, every time. Skills are the on-demand layer: folders of instructions the agent pulls in only when relevant, or that you invoke as a slash command. Skills are also Zed's slash-command mechanism now. If you're still stuffing everything into one giant rules file, you're paying context tax on every message for instructions that apply 5% of the time.

SKILL.md format: the frontmatter rules that actually reject files

A skill is a folder containing a SKILL.md, optionally plus scripts/, references/, and assets/ subfolders. The frontmatter is validated, and these limits are real, not suggestions:

• [ ]name: max 64 chars, lowercase letters and hyphens only. This becomes the /slash-command.
• [ ]description: under 1,024 bytes. This is the ONLY thing the model sees when deciding whether to load the skill, so write it like a trigger condition ('Use when...'), not a title.
• [ ]disable-model-invocation: true (optional): skill only fires when YOU invoke it via /name or @skill, never autonomously. Set it on anything with side effects.
• [ ]Body under 500 lines. Push long reference material into references/ files the skill points to.
• [ ]Flat layout: skill folders sit directly in the skills dir, no nesting.
• [ ]All skill descriptions together share a ~50KB catalog budget. Hoarding skills with bloated descriptions crowds out the rest.
• [ ]Skills live-reload: edit SKILL.md, it's active in the next message. No restart.

Complete example: the ship-check skill

Here's a full skill I actually use: a pre-deploy review that runs as /ship-check before anything hits production. It checks the branch diff for secrets, debug leftovers, missing error handling, untested changes, and unsafe migrations, then returns a SHIP / SHIP WITH NOTES / HOLD verdict. Folder layout:

~/.agents/skills/
  ship-check/
    SKILL.md          <- the whole skill (below)
    references/       <- optional: your deploy runbook, past incident notes
    scripts/          <- optional: a diff-stat helper the skill can run

---
name: ship-check
description: Pre-deploy review of the current branch. Use before merging or deploying. Checks the diff for secrets, debug leftovers, missing error handling, untested changes, and migration risks, then returns a SHIP / HOLD verdict with a fix list. Run via /ship-check or ask "run a ship check".
---

# ship-check

You are running a pre-deploy review. Be strict. A false SHIP costs more
than a false HOLD.

## Scope
Review ONLY the diff between the current branch and the default branch...

## Checks (run all, in order)
1. Secrets and credentials  -> any live credential = automatic HOLD
2. Debug leftovers          -> console.log, debugger, hardcoded localhost
3. Error handling           -> every new external call: what happens on failure?
4. Tests                    -> new logic / money / auth paths without tests
5. Migrations               -> deploy-order safety; destructive ops = HOLD
6. Dependency + config drift

## Rules
- Read-only. Report, never fix, during the check.
- Cite file:line for every finding.
- No style nitpicks.

## Output format
SHIP-CHECK: <SHIP | SHIP WITH NOTES | HOLD>
CRITICAL / WARNINGS / NOTES, then a 1-2 sentence verdict rationale.

Notice the description does three jobs in one sentence: what it is, when to trigger it, and how to invoke it. That's the pattern for every skill you write. Pair it with the Review profile from section 3 and the read-only rule is enforced by tooling, not by hoping the model listens.

Claude Code inside Zed: registry, /login, and the auth gotcha

Zed's native agent is good. Claude Code is still deeper on autonomy, and since the ACP Registry launched (~Jan 2026) you run it as a first-class panel inside Zed instead of alt-tabbing to a terminal. Setup is 5 minutes:

1. 1

   Open the ACP Registry

   Command palette, run zed: acp registry. Or Agent Settings, then Add Agent, then Install from Registry. The registry also carries Codex CLI, Copilot CLI, OpenCode, Gemini CLI, Cursor's agent, and Pi.

2. 2

   Install "Claude Agent"

   That's Claude Code's registry name. Zed handles the binary; you don't install anything with npm.

3. 3

   Start a thread with it

   In the Agent Panel, open a new thread and pick Claude Agent instead of the native Zed agent. Same panel, same @-mentions for files.

4. 4

   Run /login in the thread

   Authenticate inside the thread with either an Anthropic API key or your existing Claude subscription. If you already pay for Claude, this is the move: your subscription now powers an agent inside Zed at no extra cost.

5. 5

   Verify with a real task

   Give it one scoped task ('read src/auth.ts and explain the token refresh flow') before trusting it with edits. Confirm file reads work and diffs render in the panel.

Also know what you lose in the panel: Zed profiles and Skills do not apply to external agents (Claude Code reads its own CLAUDE.md and skills), some Claude Code slash commands are unsupported in the Agent window, and checkpoint/token-display behavior varies per agent.

When to use a Terminal Thread instead

Terminal Threads (~v1.3.5) host any CLI or TUI agent as a persistent sidebar thread. It's the full real Claude Code, every slash command, every feature, just docked in Zed. Decision rule:

The power move: one prompt, edits across 30 files

This is the workflow that doesn't exist anywhere else, because it composes three Zed primitives: multibuffers (many excerpts from many files in one editable view), multi-cursor, and inline assist (ctrl-enter). Multi-cursor inline assist runs the same prompt at every cursor simultaneously. Point it at a multibuffer and you get one AI transform applied across the whole codebase, with every change visible in a single scroll.

1. 1

   Project search into a multibuffer

   cmd-shift-f for the pattern you're changing, e.g. every call site of a deprecated function. Zed renders all results as one multibuffer: every match, editable, with surrounding context.

2. 2

   Multi-cursor every match

   Select the pattern and place a cursor at each occurrence (select-all-matches). 30 files, 45 hits, 45 cursors, one view.

3. 3

   Inline assist with one prompt

   ctrl-enter. The same prompt runs at every cursor in parallel. Be mechanical and constraint-rich; this is a transform, not a conversation. @-mention the target file so every excerpt gets the same reference context (you can even @thread to pull in an agent conversation).

4. 4

   Review in place, then sweep

   Every proposed edit appears inline in the multibuffer. Scroll once, eyeball everything, accept or reject per hunk. Then save-all and run your tests. If results are inconsistent, inline_alternatives can generate candidates from multiple models in parallel and let you pick per-site.

Rewrite this call site from [OLD_API, e.g. fetchUser(id, callback)] to [NEW_API, e.g. await getUser({ id })] per the signature in [@-mention the new module file].

Rules:
- Change ONLY the call expression and what its result flows into. Do not touch surrounding logic, imports handled separately, no reformatting of neighboring lines.
- Preserve the existing variable names and error-handling style of THIS file.
- If this specific site cannot be migrated mechanically (dynamic args, wrapped in a helper), leave the code unchanged and add: // TODO(migrate): [reason]

Output: the replacement code only. No explanation, no markdown fences.

Inline assist also works in the terminal and in channel notes, and keybindings can prefill prompts. If you run the same transform weekly, bind it: one keystroke, prompt pre-filled, cursor in the slot.

Driving it daily: threads, checkpoints, and the review pass

The Agent Panel runs multiple threads in parallel, each with an independent context window. My loop: one Write thread building, one Ask thread for questions so I don't pollute the builder's context, Claude Agent on the gnarly refactor. cmd-alt-j opens the Threads Sidebar, ctrl-tab cycles recent threads.

• [ ]Before a risky agent run: note the checkpoint. Every agent action gets a Restore Checkpoint you can jump back to. It's the undo button for 'the agent rewrote half my router'.
• [ ]After every run: ctrl-shift-r opens Review Changes, a multibuffer diff of everything the agent touched, accept/reject per hunk. Never bulk-accept an agent session you haven't scrolled.
• [ ]Hold cmd when submitting to follow the agent as it works, watching it move through files beats reading a summary after.
• [ ]Queue follow-up messages while the agent works; they run in order. Edit past messages to fork a thread instead of re-explaining.
• [ ]Watch the token usage display. Past ~70% context, quality dips before auto_compact kicks in at 90%. /compact manually at natural task boundaries.
• [ ]Feed context with @-mentions: files, directories, symbols, previous threads, skills, diagnostics, branch diffs, URLs. Drag in images. cmd-> sends the current selection to the thread.

Task: [ONE SENTENCE, e.g. add rate limiting to the public API routes]

Context you must read first: [@-mention 2-4 files and the relevant AGENTS.md section]
Branch diff context: [@-mention the branch diff if mid-feature]

Constraints:
- Scope: only [DIRECTORIES/FILES]. Anything outside scope: propose, don't edit.
- Follow the existing [PATTERN, e.g. middleware pattern in src/middleware/].
- Definition of done: [OBSERVABLE CHECK, e.g. `npm test` passes and hitting /api/x 11 times in 10s returns 429].

Process:
1. Read the context, then post a plan as a file list with one line per file on what changes. Wait for my OK.
2. Implement.
3. Run [TEST COMMAND] and paste the output.
4. End with the file -> change bullet list.

Gotchas: the nine things that will bite you (July 2026)

Every one of these is a real sharp edge in current Zed, not a hypothetical. Expand what's relevant.

The 15-minute setup checklist

• [ ]Install Zed, open settings with cmd-, and paste in the downloaded zed-settings.json (merge if you have existing settings).
• [ ]Add your Anthropic (and/or OpenAI, Google, Ollama) key via the provider settings UI. Confirm the Free plan shows unlimited BYO usage.
• [ ]Save the AGENTS.md starter to ~/.config/zed/AGENTS.md and trim it to rules you actually hold.
• [ ]Create ~/.agents/skills/ship-check/ and drop in the downloaded SKILL.md. Type /ship-check in a thread to confirm it registered.
• [ ]Open the ACP Registry (zed: acp registry), install Claude Agent, run /login in a Claude Agent thread.
• [ ]Start a Write-profile thread with the kickoff template on a small real task. Review with ctrl-shift-r before accepting.
• [ ]Run one multibuffer + multi-cursor + inline-assist transform on a low-stakes rename so the move is in your fingers before you need it at 45 call sites.

That's the cockpit. One config file, three profiles, one skill, one external agent, one power move. The whole thing costs $0/mo on BYO keys, and every piece above is in the three downloads. Set it up, run /ship-check before your next deploy, and reply with what it caught.