Summary: Zed is a fast, open-source code editor with a built-in AI agent, and the editor itself is free. You can run its agent on the free Personal plan with your own API keys, a local Ollama model, or an external agent such as Claude Agent or Codex, while Zed's hosted models and its Zeta edit predictions need Pro ($10/month with $5 of tokens included). This guide walks through the setup in the order most people need it, and shows where the free path stops.
What you get in Zed's AI, in plain terms
Zed's AI features split into three parts, and knowing which part you are touching saves a lot of confusion later:
- Zed Agent: the native agent that lives in the Agent Panel. It reads and searches your project, edits files, runs terminal commands, and shows its changes in a review view. It uses whatever model you configure under LLM Providers.
- External Agents: other coding agents (Claude Agent, Codex, OpenCode, Copilot, Cursor, Pi Coding Agent and more) that plug into the same panel through the Agent Client Protocol (ACP). They keep their own login, model choice and billing. Zed's docs state that Zed does not charge for External Agents.
- Edit Prediction: tab-to-accept completions while you type. The default provider is Zeta, Zed's own open model, which needs a Pro, trial, Student or Business plan. On Free you can switch the provider to GitHub Copilot, Codestral, Mercury Coder or a local model.
There is also an Inline Assistant for rewriting a selection, and Terminal Threads for running an agent CLI inside a terminal-backed thread. If you only want an editor, you can switch every AI feature off with the disable_ai setting.
Step 1: Install Zed
The official installation page lists these routes:
- macOS: download from zed.dev/download, or run
brew install --cask zed. - Windows: download the installer, or run
winget install -e --id ZedIndustries.Zed. - Linux: run
curl -f https://zed.dev/install.sh | sh(a preview channel and pinned versions are also supported through environment variables).
The editor works without signing in. You only need a Zed account for hosted models, Zeta predictions, and collaboration features.
Step 2: Open the Agent Panel and pick a model path
Open the Command Palette and run agent: new thread, or click the sparkle icon in the status bar. The first time, the panel asks you to configure either a model for the Zed Agent or an External Agent. You have four realistic choices:
Option A: Your own API key (free plan)
Run agent: open settings, go to LLM Providers, and paste a key. The docs list first-class support for Anthropic, OpenAI, Google AI, Mistral, DeepSeek, xAI and OpenCode, plus any OpenAI-compatible or Anthropic-compatible endpoint. Keys saved this way go into your system keychain, not into settings.json. One detail worth knowing: a non-empty environment variable such as a provider key in your shell profile takes precedence over the keychain value, so if Zed keeps using an old key, unset the variable and restart Zed.
Option B: A local model with Ollama (free)
- Install Ollama from ollama.com/download.
- Pull a model, for example
ollama pull mistral. - Make sure the server is running (open Ollama.app on macOS, or run
ollama serve). - Pick the model in Zed's model dropdown. Zed discovers pulled models automatically.
Zed sends a context length of 4,096 tokens to Ollama by default. That is small for agent work, where the model has to hold file contents and tool results, so raise language_models.ollama.context_window (the docs example uses 8192) if answers start losing track of your files.
Option C: An External Agent you already pay for
Run zed: acp registry, or go to Agent Settings, External Agents, Add Agent, Install from Registry. Once installed, the agent shows up in the panel's "New Thread" menu. The important gotcha: an Anthropic or OpenAI key you gave the Zed Agent does not configure Claude Agent or Codex. Each external agent logs in on its own; for Claude Agent, the docs tell you to open a thread and run /login.
Option D: Zed Pro hosted models
Pro gives you Zed-hosted models from several labs without managing keys. Usage is metered in tokens and billed at the provider's list price plus 10%, with $5 included each month.
Step 3: Give the agent context and rules
Type @ in the message box to attach files, folders, symbols, earlier threads, diagnostics, branch diffs or a URL. The agent can search on its own, but the docs note that explicit context improves quality and reduces latency.
For rules that should apply every time, Zed reads instruction files. Personal instructions live in ~/.config/zed/AGENTS.md (under %APPDATA%\Zed\ on Windows). For a project, Zed uses the first matching file from a list that includes .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md and GEMINI.md. Because only the first match is used, a leftover .cursorrules from an old setup can silently win over the AGENTS.md you just wrote.
Step 4: Decide what the agent may do without asking
Tool permissions control which actions run automatically. Since Zed v0.224.0 the main switch is agent.tool_permissions.default (older versions used the boolean agent.always_allow_tool_actions). You can then write per-tool regex rules for the terminal, file edits, deletes, moves, fetches and web search. A sensible starting point is the pattern from the docs: allow by default, but keep the terminal on confirm, auto-approve only known build and test commands, and always confirm anything with sudo. Deny rules block an action even when the default is set to allow.
Step 5: Review, keep or roll back
After the agent edits files, the panel shows how many files and lines changed. Click Review Changes to open every change in one multi-file tab, where you can accept or reject each hunk. Every message that produced edits also gets a Restore Checkpoint button, which returns the project to its state before that message, even if you stopped the agent midway. For long sessions, "New From Summary" starts a fresh thread seeded with a summary of the old one, which helps when you approach the model's context limit.
Zed plans compared
| Plan | Price | AI included | Edit predictions (Zeta) | Best for |
|---|---|---|---|---|
| Personal (Free) | $0, forever | Own API keys, local models and External Agents; no Zed-hosted models | Not included; use Copilot, Codestral or a local model instead | People who already have keys or an agent subscription |
| Pro | $10/month | All Zed-hosted models, $5 of tokens per month, then list price +10% | Unlimited | Solo developers who want one bill and no key management |
| Business | $30/seat/month | Hosted models at usage rates (no bundled credit) or your own keys | Unlimited | Teams that need model policies, data controls and one invoice |
Also listed in the docs: a Student plan, free for one year for verified university students, with $10/month in token credit and most hosted models. The Pro trial lasts 14 days with $5 of usage on one model (GPT-6 Luna), needs no credit card, and falls back to Free on its own.
Editor's note
Good fit: developers who want an agent inside a fast native editor and already pay for an API key, Claude, ChatGPT/Codex or Copilot. The free plan covers that without a Zed bill.
Not a fit: anyone who expects free AI autocomplete out of the box. Zeta predictions are a paid feature, and teams that need SSO today should note that the pricing page lists SSO, SAML and SCIM as planned, not available.
Gotchas I checked in the docs:
- "My key works for the Zed Agent but Claude Agent asks me to log in." Expected. External agents have their own auth; run their login flow.
- Zed uses the wrong API key. An environment variable overrides the keychain. Unset it and restart.
- The agent ignores my AGENTS.md. Check for an older rules file earlier in the list, such as
.rulesor.cursorrules. - Pro bill higher than $10. The default monthly spend limit is $10 on top of the subscription, so up to $20 total. Set it to $0 on the billing page at dashboard.zed.dev to cap spend at exactly $10.
- Local model forgets files mid-task. Raise the Ollama context window from the 4,096 default.
FAQ
Can I use Zed's AI agent completely free?
Yes, with your own API key, a local model, or an External Agent. You pay the model provider (or nothing, for local models), not Zed. Only Zed-hosted models and Zeta predictions require Pro.
What happens when the $5 of Pro tokens runs out?
Extra usage is billed at API list price plus 10%, charged at the end of the month or for every additional $10, whichever comes first, up to the spend limit you set. When the limit is hit, hosted usage stops until it resets on your billing date.
Does the Business plan include AI credits?
No. Business seats have no fixed credit allotment; members use hosted models at standard usage rates or bring the company's own provider keys. There is no minimum seat count and no free trial for Business.
Related on lightmind24: if you prefer an agent that runs as a VS Code extension, see the Cline tutorial on plan, act and rollback. If Option B fails at the Ollama step, the Ollama troubleshooting guide covers server and GPU errors, and the Codex CLI fixes post helps if Codex as an External Agent will not log in.
Start on the free plan with a key you already have, and pay for Pro only if you find yourself missing hosted models or Zeta predictions.
Screenshots: official zed.dev pricing and documentation pages, captured by the author; see the official screenshots at the end of this post.
Last verified: 2026-11-02
Sources:
Zed pricing
Zed docs: Plans and Pricing
Zed docs: AI Quick Start
Zed docs: Agent Panel
Zed docs: External Agents
Zed docs: Use API Access
Zed docs: Use a Local Model
Zed docs: Instructions
Zed docs: Tool Permissions
Zed docs: Edit Prediction
Zed docs: Installation
댓글
댓글 쓰기