From 3d700c5042c6437fd209bc11da4a7bf8bdac6072 Mon Sep 17 00:00:00 2001 From: morgankrey Date: Thu, 4 Jun 2026 10:55:21 -0500 Subject: [PATCH] Restructure AI docs (#57614) ## Summary - Restructures the AI docs around quick routing, agent paths, provider access, and company-specific entry points. - Moves account-owned AI billing/model pages into Account & Billing while preserving legacy AI redirects. - Adds focused pages for Zed Agent, external agents, terminal threads, agent profiles, skills, instructions, API access, subscriptions, gateways, and local models. - Updates related links across Git, authentication, business, migration, and settings reference docs. ## Validation - `pnpm dlx prettier@3.5.0 . --write` - `pnpm dlx prettier@3.5.0 . --check` - `git diff --check -- docs/src` - Changed-doc local markdown link sanity check - `mdbook build docs` was attempted; it is currently blocked by an unrelated existing `docs/src/vim.md:542` action schema error for `vim::HelixJumpToWord`. ## Follow-up - Create a ticket to align Zed's in-app AI configuration surfaces with this documentation model, including Agent Settings, Configure buttons, Tools, Profiles, MCP, Skills/Instructions, and plain settings. ## Suggested .rules additions N/A Release Notes: - N/A --- docs/.conventions/CONVENTIONS.md | 2 +- docs/.doc-examples/complex-feature.md | 2 +- docs/.doc-examples/configuration.md | 2 +- docs/book.toml | 11 +- docs/src/SUMMARY.md | 56 +- docs/src/{ai => account}/billing.md | 8 +- .../plans-and-pricing.md} | 26 +- docs/src/account/zed-hosted-models.md | 129 +++ docs/src/ai/agent-panel.md | 201 +--- docs/src/ai/agent-profiles.md | 76 ++ docs/src/ai/agent-settings.md | 421 ++------ docs/src/ai/agents.md | 35 + docs/src/ai/ai-improvement.md | 167 ++-- docs/src/ai/by-company.md | 107 ++ docs/src/ai/configuration.md | 27 - docs/src/ai/edit-prediction.md | 6 +- docs/src/ai/external-agents.md | 383 ++----- docs/src/ai/inline-assistant.md | 13 +- docs/src/ai/instructions.md | 66 ++ docs/src/ai/llm-providers.md | 933 +----------------- docs/src/ai/mcp.md | 14 +- docs/src/ai/models.md | 142 --- docs/src/ai/overview.md | 55 +- docs/src/ai/parallel-agents.md | 25 +- docs/src/ai/privacy-and-security.md | 81 +- docs/src/ai/quick-start.md | 92 ++ docs/src/ai/rules.md | 71 +- docs/src/ai/skills.md | 17 +- docs/src/ai/subscription.md | 18 - docs/src/ai/terminal-threads.md | 155 +++ docs/src/ai/text-threads.md | 2 +- docs/src/ai/tool-permissions.md | 22 + docs/src/ai/tools.md | 14 +- docs/src/ai/use-a-gateway.md | 218 ++++ docs/src/ai/use-a-local-model.md | 110 +++ docs/src/ai/use-an-existing-subscription.md | 57 ++ docs/src/ai/use-api-access.md | 454 +++++++++ docs/src/ai/zed-agent.md | 41 + docs/src/authentication.md | 4 +- docs/src/business/admin-controls.md | 8 +- docs/src/business/overview.md | 6 +- docs/src/business/privacy.md | 4 +- docs/src/configuring-zed.md | 2 +- docs/src/getting-started.md | 4 + docs/src/git.md | 8 +- docs/src/migrate/intellij.md | 6 +- docs/src/migrate/pycharm.md | 6 +- docs/src/migrate/rustrover.md | 6 +- docs/src/migrate/vs-code.md | 6 +- docs/src/migrate/webstorm.md | 6 +- docs/src/reference/all-settings.md | 2 +- docs/src/telemetry.md | 6 +- docs/src/windows-and-projects.md | 2 + 53 files changed, 2149 insertions(+), 2186 deletions(-) rename docs/src/{ai => account}/billing.md (95%) rename docs/src/{ai/plans-and-usage.md => account/plans-and-pricing.md} (66%) create mode 100644 docs/src/account/zed-hosted-models.md create mode 100644 docs/src/ai/agent-profiles.md create mode 100644 docs/src/ai/agents.md create mode 100644 docs/src/ai/by-company.md delete mode 100644 docs/src/ai/configuration.md create mode 100644 docs/src/ai/instructions.md delete mode 100644 docs/src/ai/models.md create mode 100644 docs/src/ai/quick-start.md delete mode 100644 docs/src/ai/subscription.md create mode 100644 docs/src/ai/terminal-threads.md create mode 100644 docs/src/ai/use-a-gateway.md create mode 100644 docs/src/ai/use-a-local-model.md create mode 100644 docs/src/ai/use-an-existing-subscription.md create mode 100644 docs/src/ai/use-api-access.md create mode 100644 docs/src/ai/zed-agent.md diff --git a/docs/.conventions/CONVENTIONS.md b/docs/.conventions/CONVENTIONS.md index b2d49420ae..d9d822e347 100644 --- a/docs/.conventions/CONVENTIONS.md +++ b/docs/.conventions/CONVENTIONS.md @@ -229,7 +229,7 @@ Include the version number and what changed. This helps users on older versions Link to other docs using relative paths: - `[Vim mode](./vim.md)` -- `[AI configuration](./ai/configuration.md)` +- `[AI Quick Start](./ai/quick-start.md)` ### External Links diff --git a/docs/.doc-examples/complex-feature.md b/docs/.doc-examples/complex-feature.md index 745e6b3bcd..dd44d9a031 100644 --- a/docs/.doc-examples/complex-feature.md +++ b/docs/.doc-examples/complex-feature.md @@ -226,7 +226,7 @@ Zed currently supports LLM-powered commit message generation. You can ask AI to generate a commit message by focusing on the message editor within the Git Panel and either clicking on the pencil icon in the bottom left, or reaching for the {#action git::GenerateCommitMessage} ({#kb git::GenerateCommitMessage}) keybinding. > **Note:** You need to have an LLM provider configured either via your own API keys or through Zed's hosted AI models. -> Visit [the AI configuration page](./ai/configuration.md) to learn how to do so. +> Visit [AI Quick Start](./ai/quick-start.md) to learn how to do so. You can specify your preferred model to use by providing a `commit_message_model` agent setting. See [Feature-specific models](./ai/agent-settings.md#feature-specific-models) for more information. diff --git a/docs/.doc-examples/configuration.md b/docs/.doc-examples/configuration.md index 45fa7e3873..d4be4c74eb 100644 --- a/docs/.doc-examples/configuration.md +++ b/docs/.doc-examples/configuration.md @@ -154,5 +154,5 @@ These are useful for sharing configuration tips or linking from documentation. - [Appearance](./appearance.md) — Themes, fonts, and visual customization - [Key bindings](./key-bindings.md) — Customize keyboard shortcuts -- [AI Configuration](./ai/configuration.md) — Set up AI providers, models, and agent settings +- [AI Quick Start](./ai/quick-start.md) — Set up AI providers, models, and agent settings - [All Settings](./reference/all-settings.md) — Complete settings reference diff --git a/docs/book.toml b/docs/book.toml index 27a7bd7e5d..f3ebf4187e 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -46,16 +46,21 @@ enable = false "/assistant/assistant-panel.html" = "/docs/ai/agent-panel.html" "/assistant/assistant.html" = "/docs/ai/overview.html" "/assistant/commands.html" = "/docs/ai/text-threads.html" -"/assistant/configuration.html" = "/docs/ai/configuration.html" +"/assistant/configuration.html" = "/docs/ai/quick-start.html" "/assistant/context-servers.html" = "/docs/ai/mcp.html" "/assistant/contexts.html" = "/docs/ai/text-threads.html" "/assistant/inline-assistant.html" = "/docs/ai/inline-assistant.html" "/assistant/model-context-protocol.html" = "/docs/ai/mcp.html" -"/assistant/prompting.html" = "/docs/ai/rules.html" +"/assistant/prompting.html" = "/docs/ai/skills.html" "/language-model-integration.html" = "/docs/assistant/assistant.html" "/model-improvement.html" = "/docs/ai/ai-improvement.html" "/ai/temperature.html" = "/docs/ai/agent-settings.html#model-temperature" -"/ai/subscription.html" = "/docs/ai/plans-and-usage.html" +"/ai/subscription.html" = "/docs/account/zed-hosted-models.html" +"/ai/models.html" = "/docs/account/zed-hosted-models.html" +"/ai/plans-and-usage.html" = "/docs/account/plans-and-pricing.html" +"/ai/billing.html" = "/docs/account/billing.html" +"/ai/configuration.html" = "/docs/ai/quick-start.html" +"/ai/set-up-ai.html" = "/docs/ai/quick-start.html" # Core "/configuring-zed.html" = "/docs/reference/all-settings.html" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d673b58a65..1763269674 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -8,24 +8,6 @@ - [Uninstall](./uninstall.md) - [Troubleshooting](./troubleshooting.md) -# AI - -- [Overview](./ai/overview.md) -- [Agent Panel](./ai/agent-panel.md) - - [Tools](./ai/tools.md) - - [Tool Permissions](./ai/tool-permissions.md) - - [External Agents](./ai/external-agents.md) -- [Parallel Agents](./ai/parallel-agents.md) -- [Inline Assistant](./ai/inline-assistant.md) -- [Edit Prediction](./ai/edit-prediction.md) -- [Skills](./ai/skills.md) -- [Rules](./ai/rules.md) -- [Model Context Protocol](./ai/mcp.md) -- [Configuration](./ai/configuration.md) - - [Agent Settings](./ai/agent-settings.md) -- [Models](./ai/models.md) -- [Providers](./ai/llm-providers.md) - # Working with Code - [Windows & Projects](./windows-and-projects.md) @@ -59,11 +41,40 @@ - [Environment Variables](./environment.md) - [Dev Containers](./dev-containers.md) +# AI + +- [Overview](./ai/overview.md) +- [AI Quick Start](./ai/quick-start.md) +- [AI by Company](./ai/by-company.md) +- [Agents](./ai/agents.md) + - [Zed Agent](./ai/zed-agent.md) + - [External Agents](./ai/external-agents.md) + - [Terminal Threads](./ai/terminal-threads.md) +- [Agent Panel](./ai/agent-panel.md) + - [Agent Settings](./ai/agent-settings.md) + - [Agent Profiles](./ai/agent-profiles.md) + - [Tools](./ai/tools.md) + - [Tool Permissions](./ai/tool-permissions.md) + - [Model Context Protocol](./ai/mcp.md) + - [Skills](./ai/skills.md) + - [Instructions](./ai/instructions.md) +- [Parallel Agents](./ai/parallel-agents.md) +- [Inline Assistant](./ai/inline-assistant.md) +- [LLM Providers](./ai/llm-providers.md) + - [Use API Access](./ai/use-api-access.md) + - [Use an Existing Subscription](./ai/use-an-existing-subscription.md) + - [Use a Gateway](./ai/use-a-gateway.md) + - [Use a Local Model](./ai/use-a-local-model.md) +- [Edit Prediction](./ai/edit-prediction.md) +- [AI Privacy](./ai/privacy-and-security.md) + - [Feedback and Training Data](./ai/ai-improvement.md) + # Account & Billing - [Authenticate](./authentication.md) -- [Plans & Pricing](./ai/plans-and-usage.md) -- [Billing](./ai/billing.md) +- [Plans & Pricing](./account/plans-and-pricing.md) +- [Zed-Hosted Models](./account/zed-hosted-models.md) +- [Billing](./account/billing.md) # Zed Business @@ -75,9 +86,7 @@ # Privacy & Security -- [Overview](./ai/privacy-and-security.md) - - [Worktree Trust](./worktree-trust.md) - - [AI Improvement](./ai/ai-improvement.md) +- [Worktree Trust](./worktree-trust.md) - [Privacy for Business](./business/privacy.md) - [Telemetry](./telemetry.md) - [SOC2](./soc2.md) @@ -188,6 +197,7 @@ - [Icon Theme Extensions](./extensions/icon-themes.md) - [Snippets Extensions](./extensions/snippets.md) - [MCP Server Extensions](./extensions/mcp-extensions.md) +- [Agent Server Extensions](./extensions/agent-servers.md) # Coming From… diff --git a/docs/src/ai/billing.md b/docs/src/account/billing.md similarity index 95% rename from docs/src/ai/billing.md rename to docs/src/account/billing.md index 6d175cd428..88a32467fc 100644 --- a/docs/src/ai/billing.md +++ b/docs/src/account/billing.md @@ -7,7 +7,7 @@ description: Manage billing for your Zed subscription, including payment methods Zed uses Stripe for payment processing. All plans that require payment do so via credit card or other supported payment methods. Individual Pro subscriptions also use Orb for invoicing and metering. -For details on what's included in each plan and how token usage works, see [Plans & Pricing](./plans-and-usage.md). +For details on what's included in each plan and how token usage works, see [Plans & Pricing](./plans-and-pricing.md). ## Individual billing {#individual} @@ -22,13 +22,13 @@ Zed is billed on a monthly basis based on the date you initially subscribe. You' ### Zed Pro threshold billing {#threshold-billing} -For individual Zed Pro subscriptions, Zed uses threshold billing to ensure timely payment collection. Threshold billing controls when already-allowed token usage is invoiced during the month; your [monthly spend limit](./plans-and-usage.md#usage-spend-limits) still controls when hosted model usage stops. +For individual Zed Pro subscriptions, Zed uses threshold billing to ensure timely payment collection. Threshold billing controls when already-allowed token usage is invoiced during the month; your [monthly spend limit](./plans-and-pricing.md#usage-spend-limits) still controls when hosted model usage stops. Threshold invoices start at $10 of pre-tax incremental token spend. For higher token usage, Zed may automatically raise your pre-tax invoicing threshold in $10 increments, up to $100, so you receive fewer mid-cycle invoices. Once raised, the invoicing threshold is not automatically lowered during the same subscription. For Zed Business billing, see [Organization billing](#organization). -For example: +For example, - You subscribe on February 1. Your first invoice is $10. - You use $12 of incremental tokens in the month of February, with the first $10 spent on February 15. You'll receive an invoice for $10 on February 15. @@ -56,7 +56,7 @@ Use the Billing Manager role for someone who needs billing access but does not n ### AI usage {#ai-usage} -AI usage across the organization is metered on a token basis at the same rates as individual Pro subscriptions. See [Plans & Pricing](./plans-and-usage.md#usage) for rate details. +AI usage across the organization is metered on a token basis at the same rates as individual Pro subscriptions. See [Plans & Pricing](./plans-and-pricing.md#usage) for rate details. Administrators can set an org-wide AI spend limit from the Data & Privacy page in the organization dashboard. The limit starts at $0, so it must be increased before members can use any hosted models. Once the limit is reached, members will see an error when attempting to use hosted models. diff --git a/docs/src/ai/plans-and-usage.md b/docs/src/account/plans-and-pricing.md similarity index 66% rename from docs/src/ai/plans-and-usage.md rename to docs/src/account/plans-and-pricing.md index 70984e2040..e76819cddb 100644 --- a/docs/src/ai/plans-and-usage.md +++ b/docs/src/account/plans-and-pricing.md @@ -11,23 +11,23 @@ Zed works without AI features or a subscription. No [authentication](../authenti ## Plans {#plans} -| | Free | Pro | Student | Business | -| ----------------------------------------- | ------- | --------- | --------- | --------- | -| Zed-hosted AI models | — | ✓ | ✓ | ✓ | -| [AI via own API keys](./llm-providers.md) | ✓ | ✓ | ✓ | ✓ | -| [External agents](./external-agents.md) | ✓ | ✓ | ✓ | ✓ | -| Edit Predictions | Limited | Unlimited | Unlimited | Unlimited | -| Org-wide admin controls | — | — | — | ✓ | -| Roles & permissions | — | — | — | ✓ | -| Consolidated billing | — | — | — | ✓ | +| | Free | Pro | Student | Business | +| ---------------------------------------------- | ------- | --------- | --------- | --------- | +| Zed-hosted AI models | — | ✓ | ✓ | ✓ | +| [AI via own API keys](../ai/use-api-access.md) | ✓ | ✓ | ✓ | ✓ | +| [External Agents](../ai/external-agents.md) | ✓ | ✓ | ✓ | ✓ | +| Edit Predictions | Limited | Unlimited | Unlimited | Unlimited | +| Org-wide admin controls | — | — | — | ✓ | +| Roles & permissions | — | — | — | ✓ | +| Consolidated billing | — | — | — | ✓ | ### Zed Free {#free} -Zed is free to use. You can configure AI agents with your own API keys via [Providers](./llm-providers.md). [Edit Predictions](./edit-prediction.md) are available on a limited basis. Zed's hosted models require a Pro subscription. +Zed is free to use. You can configure AI agents with your own API keys via [Use API Access](../ai/use-api-access.md). [Edit Predictions](../ai/edit-prediction.md) are available on a limited basis. Zed's hosted models require a Pro subscription. ### Zed Pro {#pro} -Zed Pro includes access to all hosted AI models and Edit Predictions. The plan includes $5 of monthly token credit; usage beyond that is billed at the rates listed on [the Models page](./models.md). A trial of Zed Pro includes $20 of credit, usable for 14 days. +Zed Pro includes access to all hosted AI models and Edit Predictions. The plan includes $5 of monthly token credit; usage beyond that is billed at the rates listed on [Zed-Hosted Models](./zed-hosted-models.md). A trial of Zed Pro includes $20 of credit, usable for 14 days. For details on billing and payment, see [Individual Billing](./billing.md). @@ -39,11 +39,11 @@ For a full feature overview, see [Zed Business](../business/overview.md). For bi ### Student Plan {#student} -The [Zed Student plan](https://zed.dev/education) includes all Zed Pro features: unlimited [Edit Predictions](./edit-prediction.md), all [hosted AI models](./models.md) except Claude Opus, and $10/month in token credits. Available free for one year to verified university students. +The [Zed Student plan](https://zed.dev/education) includes all Zed Pro features: unlimited [Edit Predictions](../ai/edit-prediction.md), all [hosted AI models](./zed-hosted-models.md) except Claude Opus, and $10/month in token credits. Available free for one year to verified university students. ## Usage {#usage} -Usage of Zed's hosted models is measured on a token basis, converted to dollars at the rates listed on [the Models page](./models.md) (list price from the provider, +10%). +Usage of Zed's hosted models is measured on a token basis, converted to dollars at the rates listed on [Zed-Hosted Models](./zed-hosted-models.md) (list price from the provider, +10%). Monthly included credit resets on your monthly billing date. To view your current usage, navigate to the Billing page at [dashboard.zed.dev](https://dashboard.zed.dev). Usage data from our metering provider, Orb, is embedded on that page. diff --git a/docs/src/account/zed-hosted-models.md b/docs/src/account/zed-hosted-models.md new file mode 100644 index 0000000000..a74fd81b57 --- /dev/null +++ b/docs/src/account/zed-hosted-models.md @@ -0,0 +1,129 @@ +--- +title: Zed-Hosted Models - Zed +description: AI models available via Zed Pro including Claude, GPT-5.5, Gemini 3.1 Pro, and Gemini 3.5 Flash. Pricing, context windows, and tool call support. +--- + +# Zed-Hosted Models + +Zed's plans offer hosted versions of major LLMs with higher rate limits than direct API access. Model availability is updated regularly. To use your own API keys instead, see [LLM Providers](../ai/llm-providers.md). For general setup, see [AI Quick Start](../ai/quick-start.md). + +> **Note:** Claude Opus models, GPT-5.5 pro, and GPT-5.4 pro are only available on Zed Pro and Zed Business. + +| Model | Provider | Token Type | Provider Price per 1M tokens | Zed Price per 1M tokens | +| ----------------- | --------- | ------------------- | ---------------------------- | ----------------------- | +| Claude Opus 4.5 | Anthropic | Input | $5.00 | $5.50 | +| | Anthropic | Output | $25.00 | $27.50 | +| | Anthropic | Input - Cache Write | $6.25 | $6.875 | +| | Anthropic | Input - Cache Read | $0.50 | $0.55 | +| Claude Opus 4.6 | Anthropic | Input | $5.00 | $5.50 | +| | Anthropic | Output | $25.00 | $27.50 | +| | Anthropic | Input - Cache Write | $6.25 | $6.875 | +| | Anthropic | Input - Cache Read | $0.50 | $0.55 | +| Claude Opus 4.7 | Anthropic | Input | $5.00 | $5.50 | +| | Anthropic | Output | $25.00 | $27.50 | +| | Anthropic | Input - Cache Write | $6.25 | $6.875 | +| | Anthropic | Input - Cache Read | $0.50 | $0.55 | +| Claude Opus 4.8 | Anthropic | Input | $5.00 | $5.50 | +| | Anthropic | Output | $25.00 | $27.50 | +| | Anthropic | Input - Cache Write | $6.25 | $6.875 | +| | Anthropic | Input - Cache Read | $0.50 | $0.55 | +| Claude Sonnet 4.5 | Anthropic | Input | $3.00 | $3.30 | +| | Anthropic | Output | $15.00 | $16.50 | +| | Anthropic | Input - Cache Write | $3.75 | $4.125 | +| | Anthropic | Input - Cache Read | $0.30 | $0.33 | +| Claude Sonnet 4.6 | Anthropic | Input | $3.00 | $3.30 | +| | Anthropic | Output | $15.00 | $16.50 | +| | Anthropic | Input - Cache Write | $3.75 | $4.125 | +| | Anthropic | Input - Cache Read | $0.30 | $0.33 | +| Claude Haiku 4.5 | Anthropic | Input | $1.00 | $1.10 | +| | Anthropic | Output | $5.00 | $5.50 | +| | Anthropic | Input - Cache Write | $1.25 | $1.375 | +| | Anthropic | Input - Cache Read | $0.10 | $0.11 | +| GPT-5.5 pro | OpenAI | Input | $30.00 | $33.00 | +| | OpenAI | Output | $180.00 | $198.00 | +| GPT-5.5 | OpenAI | Input | $5.00 | $5.50 | +| | OpenAI | Output | $30.00 | $33.00 | +| | OpenAI | Cached Input | $0.50 | $0.55 | +| GPT-5.4 pro | OpenAI | Input | $30.00 | $33.00 | +| | OpenAI | Output | $180.00 | $198.00 | +| GPT-5.4 | OpenAI | Input | $2.50 | $2.75 | +| | OpenAI | Output | $15.00 | $16.50 | +| | OpenAI | Cached Input | $0.025 | $0.0275 | +| GPT-5.3-Codex | OpenAI | Input | $1.75 | $1.925 | +| | OpenAI | Output | $14.00 | $15.40 | +| | OpenAI | Cached Input | $0.175 | $0.1925 | +| GPT-5.2 | OpenAI | Input | $1.75 | $1.925 | +| | OpenAI | Output | $14.00 | $15.40 | +| | OpenAI | Cached Input | $0.175 | $0.1925 | +| GPT-5.2-Codex | OpenAI | Input | $1.75 | $1.925 | +| | OpenAI | Output | $14.00 | $15.40 | +| | OpenAI | Cached Input | $0.175 | $0.1925 | +| GPT-5 mini | OpenAI | Input | $0.25 | $0.275 | +| | OpenAI | Output | $2.00 | $2.20 | +| | OpenAI | Cached Input | $0.025 | $0.0275 | +| GPT-5 nano | OpenAI | Input | $0.05 | $0.055 | +| | OpenAI | Output | $0.40 | $0.44 | +| | OpenAI | Cached Input | $0.005 | $0.0055 | +| Gemini 3.1 Pro | Google | Input | $2.00 | $2.20 | +| | Google | Output | $12.00 | $13.20 | +| Gemini 3.5 Flash | Google | Input | $1.50 | $1.65 | +| | Google | Output | $9.00 | $9.90 | +| Gemini 3 Flash | Google | Input | $0.50 | $0.55 | +| | Google | Output | $3.00 | $3.30 | + +## Recent Model Retirements + +As of February 19, 2026, Zed Pro serves newer model versions in place of the retired models below: + +- Claude Opus 4.1 → Claude Opus 4.5, Claude Opus 4.6, Claude Opus 4.7, or Claude Opus 4.8 +- Claude Sonnet 4 → Claude Sonnet 4.5 or Claude Sonnet 4.6 +- Claude Sonnet 3.7 (retired Feb 19) → Claude Sonnet 4.5 or Claude Sonnet 4.6 +- GPT-5.1 and GPT-5 → GPT-5.2 or GPT-5.2-Codex +- Gemini 2.5 Pro → Gemini 3.1 Pro +- Gemini 3 Pro → Gemini 3.1 Pro +- Gemini 2.5 Flash → Gemini 3 Flash or Gemini 3.5 Flash + +## Usage {#usage} + +Any usage of a Zed-hosted model will be billed at the Zed Price (rightmost column above). See [Plans & Pricing](./plans-and-pricing.md) for details on Zed's plans and limits for use of hosted models. + +Because Zed-hosted Gemini models do not use Google context caching, Gemini usage is billed only as input and output tokens; there is no separate cached-input price for these models. This preserves zero-data-retention behavior for hosted Gemini requests. For background, see Google's Vertex AI documentation on [context caching](https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview) and [zero data retention](https://cloud.google.com/vertex-ai/generative-ai/docs/vertex-ai-zero-data-retention). + +> LLMs can enter unproductive loops that require user intervention. Monitor longer-running tasks and interrupt if needed. + +## Context Windows {#context-windows} + +A context window is the maximum span of text and code an LLM can consider at once, including both the input prompt and output generated by the model. + +| Model | Provider | Zed-Hosted Context Window | +| ----------------- | --------- | ------------------------- | +| Claude Opus 4.5 | Anthropic | 200k | +| Claude Opus 4.6 | Anthropic | 1M | +| Claude Opus 4.7 | Anthropic | 1M | +| Claude Opus 4.8 | Anthropic | 1M | +| Claude Sonnet 4.5 | Anthropic | 200k | +| Claude Sonnet 4.6 | Anthropic | 1M | +| Claude Haiku 4.5 | Anthropic | 200k | +| GPT-5.5 pro | OpenAI | 272k input / 400k total | +| GPT-5.5 | OpenAI | 272k input / 400k total | +| GPT-5.4 pro | OpenAI | 272k input / 400k total | +| GPT-5.4 | OpenAI | 272k input / 400k total | +| GPT-5.3-Codex | OpenAI | 272k input / 400k total | +| GPT-5.2 | OpenAI | 272k input / 400k total | +| GPT-5.2-Codex | OpenAI | 272k input / 400k total | +| GPT-5 mini | OpenAI | 272k input / 400k total | +| GPT-5 nano | OpenAI | 272k input / 400k total | +| Gemini 3.1 Pro | Google | 200k | +| Gemini 3.5 Flash | Google | 1M | +| Gemini 3 Flash | Google | 1M | + +> Zed currently limits hosted Gemini 3.1 Pro requests to 200k tokens because pricing changes above that context size. + +Each Agent thread in Zed maintains its own context window. +The more prompts, attached files, and responses included in a session, the larger the context window grows. + +Start a new thread for each distinct task to keep context focused. + +## Tool Calls {#tool-calls} + +Models can use [tools](../ai/tools.md) to interface with your code, search the web, and perform other useful functions. diff --git a/docs/src/ai/agent-panel.md b/docs/src/ai/agent-panel.md index b7d17bba88..e0d019655d 100644 --- a/docs/src/ai/agent-panel.md +++ b/docs/src/ai/agent-panel.md @@ -8,26 +8,25 @@ description: Use Zed's AI coding agent to generate, refactor, and debug code wit The Agent Panel is where you interact with AI agents that can read, write, and run code in your project. It's the core of Zed's AI code editing experience — use it for code generation, refactoring, debugging, documentation, and general questions. -Open it with {#action agent::NewThread} from [the Command Palette](../getting-started.md#command-palette) or click the ✨ icon in the status bar. +Open it with {#action agent::NewThread} from [the Command Palette](../command-palette.md) or click the ✨ icon in the status bar. ## Getting Started {#getting-started} -If you're using the Agent Panel for the first time, you need to have at least one LLM provider or external agent configured. -You can do that by: +If you're using the Agent Panel for the first time, configure either a model for the [Zed Agent](./zed-agent.md) or an [External Agent](./external-agents.md). -1. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models -2. [using your own API keys](./llm-providers.md#use-your-own-keys), either from model providers like Anthropic or model gateways like OpenRouter. -3. using an [external agent](./external-agents.md) like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Agent](./external-agents.md#claude-agent) +- Use [LLM Providers](./llm-providers.md) for Zed-hosted models, API access, subscriptions, gateways, and local models. +- Use [External Agents](./external-agents.md) for ACP-integrated agents. +- Use [AI Quick Start](./quick-start.md) if you are not sure which path to choose. ## Overview {#overview} -With an LLM provider or external agent configured, type in the message editor and press `enter` to submit. +With an LLM provider or External Agent configured, type in the message editor and press `enter` to submit. Expand the editor with {#kb agent::ExpandMessageEditor} if you need more room. Responses stream in with indicators showing [which tools](./tools.md) the model is using. The sections below cover what you can do from here. -> Note that for external agents, like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Agent](./external-agents.md#claude-agent), some of the features outlined below may _not_ be supported—for example, _restoring threads from history_, _checkpoints_, _token usage display_, and others. +> Note that some Agent Panel features may not be available for every External Agent. Restoring threads from history, checkpoints, token usage display, and similar features depend on the agent integration. > Their availability varies depending on the agent. ### Creating New Threads {#new-thread} @@ -38,11 +37,11 @@ Start a new thread with {#kb agent::NewThread}, or open the "New Thread…" menu From the "New Thread…" menu you can: -- Pick **Zed Agent** or any installed [external agent](./external-agents.md) to start a new thread with that agent. +- Pick **Zed Agent** or any installed [External Agent](./external-agents.md) to start a new thread with that agent. - Choose **New From Summary** to start a fresh Zed Agent thread seeded with a summary of the current conversation — useful for compacting long threads as you approach the context window limit. - Choose **Terminal** to open a terminal thread directly in the Agent Panel — see [Terminal Threads](#terminal-threads) for details. -{#action agent::NewExternalAgentThread} creates a new thread with the specified external agent id. +{#action agent::NewExternalAgentThread} creates a new thread with the specified External Agent id. You can also start a new thread from the [Threads Sidebar](./parallel-agents.md#threads-sidebar), scoped to a specific project — see [Running Multiple Threads](./parallel-agents.md#running-multiple-threads). @@ -65,7 +64,7 @@ You can click on the card that contains your message and re-submit it with an ad Messages sent while the agent is in the generating state get, by default, queued. -For the Zed agent, queued messages get sent at the next turn boundary, which is usually between a tool call and a response, whereas for external agents, the message gets sent at the end of the generation. +For the Zed Agent, queued messages get sent at the next turn boundary, which is usually between a tool call and a response, whereas for External Agents, the message gets sent at the end of the generation. You can edit or remove (an individual or all) queued messages. You can also still interrupt the agent immediately if you want by either clicking on the stop button or by clicking the "Send Now" (double-enter) on a queued message. @@ -125,115 +124,14 @@ keep/reject hunk controls as the multi-buffer review pane. This temporarily over ## Terminal Threads {#terminal-threads} -The Agent Panel can host terminal threads alongside your agent threads. Each terminal thread appears as its own entry in the [Threads Sidebar](./parallel-agents.md#threads-sidebar) with a terminal icon, letting you switch between conversations and shell sessions from the same list. - -External agents like Claude Agent and Codex can also run as terminal threads. Some support terminal signals — such as bell notifications or title updates — that Zed uses to show useful context in the sidebar. - -### Opening a Terminal Thread {#opening-a-terminal-thread} - -Open the menu using the agent selector button on the left (in the empty state) or the `+` icon in the top-right of the panel toolbar, and choose **Terminal**. The terminal thread opens in the panel body, just like switching to a thread. You can open as many as you like — each gets its own sidebar entry. - -### Terminal Thread Titles {#terminal-thread-titles} - -The terminal title in the toolbar updates automatically to reflect the running shell or process. You can also set a custom name by clicking the title or the pencil icon that appears on hover. - -### Notifications {#terminal-thread-notifications} - -When a terminal produces a bell character while not in focus, Zed notifies you the same way it does when an agent finishes — with a visual pop-up and an optional sound. Clicking the notification brings the terminal into focus and clears the indicator. The same `agent.notify_when_agent_waiting` and `agent.play_sound_when_agent_done` settings apply. - -### Closing Terminal Threads {#closing-terminal-threads} - -Unlike agent threads, terminal threads are closed rather than archived — they don't go to Thread History. To close one, hover over it in the Threads Sidebar and click the **×** button, or select it and press {#kb agent::ArchiveSelectedThread}. - -### Claude Code Notifications {#claude-code-notifications} - -Claude Code can notify you when it finishes a task or pauses for permission. To enable this, set `preferredNotifChannel` to `"terminal_bell"` in your Claude Code user settings: - -```json -{ - "preferredNotifChannel": "terminal_bell" -} -``` - -You can also set this from within Claude Code by running `/config`, selecting `Local Notifications`, and choosing `Terminal Bell`. - -> If you run Claude Code inside tmux, bell notifications may not reach the outer terminal unless passthrough is enabled. Add this to `~/.tmux.conf`: -> -> ``` -> set -g allow-passthrough on -> ``` - -For more, see the [Claude Code documentation](https://code.claude.com/docs/en/terminal-config). - -### Amp Notifications {#amp-notifications} - -Amp updates terminal titles automatically and can also notify you when it needs your attention. To enable notifications in Zed terminal threads, add `AMP_FORCE_BEL=1` to your terminal environment settings: - -```json [settings] -{ - "terminal": { - "env": { - "AMP_FORCE_BEL": "1" - } - } -} -``` - -Restart Amp after adding the environment variable. - -### OpenCode Notifications {#opencode-notifications} - -OpenCode can update terminal titles automatically. For Zed notifications, add an OpenCode plugin that emits a terminal bell when OpenCode needs your attention. - -Create `.opencode/plugins/zed-bell.js` in your project, or `~/.config/opencode/plugins/zed-bell.js` to use it globally: - -```js -export const ZedBell = async () => { - return { - event: async ({ event }) => { - if (event.type === "session.idle" || event.type === "permission.asked") { - process.stdout.write("\x07"); - } - }, - }; -}; -``` - -Restart OpenCode after adding the plugin. - -### Pi Notifications {#pi-notifications} - -Pi can use an extension to emit a notification when it finishes a turn. Create `.pi/extensions/zed-bell.ts` in your project, or `~/.pi/agent/extensions/zed-bell.ts` to use it globally: - -```ts -import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; - -export default function (pi: ExtensionAPI) { - pi.on("agent_end", async () => { - process.stdout.write("\x07"); - }); -} -``` - -Restart Pi after adding the extension, or run `/reload` if the extension is in one of Pi's auto-discovered extension locations. - -### Codex Terminal Titles {#codex-terminal-titles} - -Codex can update the terminal title as it works, which Zed uses to show useful context for Codex terminal threads in the sidebar — such as the project, current status, branch, model, or task progress. - -To configure this from within Codex, run `/title` and use the picker to choose which fields appear and in what order. Codex saves the selection to `tui.terminal_title` in `~/.codex/config.toml`. You can also edit it directly: - -```toml -[tui] -terminal_title = ["spinner", "project-name", "run-state", "thread-title"] -``` +The Agent Panel can host Terminal Threads alongside your agent threads. For opening, closing, notifications, terminal titles, and CLI/TUI-specific setup, see [Terminal Threads](./terminal-threads.md). ## Adding Context {#adding-context} The agent can search your codebase to find relevant context, but providing it explicitly improves response quality and reduces latency. Add context by typing `@` in the message editor. -You can mention files, directories, symbols, previous threads, skills, and diagnostics. +You can mention files, directories, symbols, previous threads, skills, instruction files, and diagnostics. When you paste multi-line code selections copied from a buffer, Zed automatically formats them as @-mentions with the file context. To paste content without this automatic formatting, use {#kb agent::PasteRaw} to paste raw text directly. @@ -247,7 +145,7 @@ Additionally, you can also select text in a buffer or terminal and add it as con It's also possible to attach images in your prompt for providers that support vision models. OpenAI GPT-4o and later, Anthropic Claude 3 and later, Google Gemini 1.5 and 2.0, and Bedrock vision models (Claude 3+, Amazon Nova Pro and Lite, Meta Llama 3.2 Vision, Mistral Pixtral) all support image inputs. -To add an image, you can either search in your project's directory by @-mentioning it, or drag it from your file system directly into the agent panel message editor. +To add an image, you can either search in your project's folder by @-mentioning it, or drag it from your file system directly into the Agent Panel message editor. Copying an image and pasting it is also supported. ## Token Usage {#token-usage} @@ -259,7 +157,7 @@ You can also do this at any time with an ongoing thread via the "Agent Options" ## Changing Models {#changing-models} -After you've configured your LLM providers—either via [a custom API key](./llm-providers.md) or through [Zed's hosted models](./models.md)—you can switch between their models by clicking on the model selector on the message editor or by using the {#kb agent::ToggleModelSelector} keybinding. +After you've configured your LLM providers—either via [API access](./use-api-access.md) or through [Zed-hosted models](../account/zed-hosted-models.md)—you can switch between their models by clicking on the model selector on the message editor or by using the {#kb agent::ToggleModelSelector} keybinding. > The same model can be offered via multiple providers - for example, Claude Sonnet 4.5 is available via Zed Pro, OpenRouter, Anthropic directly, and more. > Make sure you've selected the correct model **_provider_** for the model you'd like to use, delineated by the logo to the left of the model in the model selector. @@ -270,65 +168,13 @@ You can mark specific models as favorites either through the model selector, by Cycle through your favorites with {#kb agent::CycleFavoriteModels} without opening the model selector. -## Using Tools {#using-tools} +## Using Tools and Profiles {#using-tools} -The Agent Panel supports tool calling, which enables agentic editing. -Zed includes several [built-in tools](./tools.md) for searching your codebase, editing files, running terminal commands, and more. +The Agent Panel supports tool calling, which enables agentic editing. Zed includes [built-in tools](./tools.md) for searching your codebase, editing files, running terminal commands, and more. -You can also extend the set of available tools via [MCP Servers](./mcp.md). +Use [Agent Profiles](./agent-profiles.md) to choose which built-in tools and MCP tools are available in a Zed Agent thread. Use [Tool Permissions](./tool-permissions.md) to control whether permission-gated tool calls are allowed, denied, or confirmed. -### Profiles {#profiles} - -Profiles act as a way to group tools. -Zed offers three built-in profiles and you can create as many custom ones as you want. - -#### Built-in Profiles {#built-in-profiles} - -- `Write`: A profile with tools to allow the LLM to write to your files and run terminal commands. - This one essentially has all built-in tools turned on. -- `Ask`: A profile with read-only tools. - Best for asking questions about your code base without the concern of the agent making changes. -- `Minimal`: A profile with no tools. - Best for general conversations with the LLM where no knowledge of your code base is necessary. - -You can explore the exact tools enabled in each profile by clicking on the profile selector button > `Configure` button > the one you want to check out. - -Alternatively, you can also use either the command palette, by running {#action agent::ManageProfiles}, or the keybinding directly, {#kb agent::ManageProfiles}, to have access to the profile management modal. - -Use {#kb agent::CycleModeSelector} to cycle through available profiles without opening the modal. - -#### Custom Profiles {#custom-profiles} - -You can also create a custom profile through the Agent Profile modal. -From there, you can choose to `Add New Profile` or fork an existing one with a custom name and your preferred set of tools. - -It's also possible to override built-in profiles. -In the Agent Profile modal, select a built-in profile, navigate to `Configure Tools`, and rearrange the tools you'd like to keep or remove. - -Zed will store this profile in your settings using the same profile name as the default you overrode. - -All custom profiles can be edited via the UI or by hand under the `agent.profiles` key in your settings file. - -To delete a custom profile, open the Agent Profile modal, select the profile you want to remove, and click the delete button. - -### Tool Permissions - -> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`. -> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`). - -Zed's Agent Panel provides the `agent.tool_permissions.default` setting to control tool approval behavior: - -- `"confirm"` (default) — Prompts for approval before running any tool action -- `"allow"` — Auto-approves tool actions without prompting -- `"deny"` — Blocks all tool actions - -When the agent requests permission for an action, the confirmation menu includes options to allow or deny once, plus "Always for " choices that set a tool-level default. -When Zed can extract a safe pattern from the input, it also offers pattern-based "Always for ..." choices that add `always_allow`/`always_deny` rules. -MCP tools only support tool-level defaults. - -Even with `"default": "allow"`, per-tool `always_deny` and `always_confirm` patterns are still respected — so you can auto-approve most actions while blocking or gating specific ones. - -Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details. +You can add external tools with [MCP Servers](./mcp.md). ### Model Support {#model-support} @@ -336,7 +182,7 @@ Tool calling needs to be individually supported by each model and model provider Therefore, despite the presence of built-in tools, some models may not have the ability to pick them up. You should see a "No tools" label if you select a model that falls into this case. -All [Zed's hosted models](./models.md) support tool calling out-of-the-box. +All [Zed-hosted models](../account/zed-hosted-models.md) support tool calling out-of-the-box. ### MCP Servers {#mcp-servers} @@ -353,10 +199,13 @@ You can also open threads as Markdown by clicking on the file icon button, to th You can rate agent responses to help improve Zed's system prompt and tools. -> Note that rating responses will send your data related to that response to Zed's servers. -> See [AI Improvement](./ai-improvement.md) and [Privacy and Security](./privacy-and-security.md) for more information about Zed's approach to AI improvement, privacy, and security. +> **Warning:** Rating an AI response sends the conversation thread to Zed. The +> conversation thread includes your messages, AI responses, and thread metadata. +> See [Feedback and Training Data](./ai-improvement.md) and +> [AI Privacy](./privacy-and-security.md) for more information. > **_If you don't want data persisted on Zed's servers, don't rate_**. -> We will not collect data for improving our Agentic offering without you explicitly rating responses. +> We will not collect data for improving Zed's agent experience without you +> explicitly rating responses. To help improve Zed's system prompt and tools, rate responses with the thumbs up/down controls at the end of each response. In case of a thumbs down, a new text area will show up where you can add more specifics about what happened. diff --git a/docs/src/ai/agent-profiles.md b/docs/src/ai/agent-profiles.md new file mode 100644 index 0000000000..2ae8924776 --- /dev/null +++ b/docs/src/ai/agent-profiles.md @@ -0,0 +1,76 @@ +--- +title: Agent Profiles - Zed +description: Configure Zed Agent profiles for model selection, built-in tool availability, and MCP tool availability. +--- + +# Agent Profiles + +Agent profiles control how the [Zed Agent](./zed-agent.md) behaves in a thread. A profile can set a default model and choose which built-in tools and MCP tools are available. + +Profiles do not decide whether a tool call is allowed automatically. Use [Tool Permissions](./tool-permissions.md) to control allow, deny, and confirm behavior. + +## Built-in Profiles {#built-in-profiles} + +Zed includes three built-in profiles: + +- `Write`: enables tools for reading, editing, and running commands. +- `Ask`: focuses on read-only codebase questions. +- `Minimal`: uses no project tools. + +## Configure Profiles {#configure-profiles} + +Open the profile selector in the Agent Panel, then click `Configure`. + +You can also run {#action agent::ManageProfiles} from the command palette. + +From the profile modal, you can: + +- create a custom profile +- fork an existing profile +- configure a profile default model +- configure built-in tools +- configure MCP tools +- delete custom profiles + +## Profiles and Settings {#settings} + +Profiles are stored under `agent.profiles` in your settings. + +```json [settings] +{ + "agent": { + "profiles": { + "ask": { + "name": "Ask", + "tools": { + "read_file": true, + "grep": true, + "terminal": false, + "edit_file": false + }, + "enable_all_context_servers": false, + "context_servers": {}, + "default_model": { + "provider": "zed.dev", + "model": "claude-sonnet-4-5" + } + } + } + } +} +``` + +The exact model IDs and provider IDs depend on your configured [LLM Providers](./llm-providers.md). + +## Profiles vs. Tool Permissions {#profiles-vs-tool-permissions} + +| Setting | Controls | Example | +| ---------------- | --------------------------------------------------------------------- | ----------------------------------------- | +| Agent profile | Whether a tool is available in a profile | Disable `terminal` in a read-only profile | +| Tool permissions | Whether a permission-gated tool call is allowed, denied, or confirmed | Always confirm `terminal` commands | + +If a tool is not available in the active profile, the Zed Agent cannot use it. If the tool is available and permission-gated, [Tool Permissions](./tool-permissions.md) still controls whether the tool call requires approval. + +## Agent Path Boundaries {#agent-path-boundaries} + +Agent profiles apply to the Zed Agent. External Agents and Terminal Threads do not use Zed Agent profiles unless their integration explicitly supports similar behavior. diff --git a/docs/src/ai/agent-settings.md b/docs/src/ai/agent-settings.md index 51de506c47..f421f2765c 100644 --- a/docs/src/ai/agent-settings.md +++ b/docs/src/ai/agent-settings.md @@ -1,70 +1,47 @@ --- -title: AI Agent Settings - Zed -description: "Customize Zed's AI agent: default models, temperature, tool approval, auto-run commands, notifications, and panel options." +title: Agent Settings - Zed +description: Map the Agent Settings panel to Zed AI setup pages for LLM providers, External Agents, MCP servers, and related settings. --- # Agent Settings -Settings for Zed's Agent Panel, including model selection, UI preferences, and tool permissions. +Agent Settings is the in-panel configuration view for model providers, External Agents, and MCP servers. Open it with {#action agent::OpenSettings} or from the top-right menu in the [Agent Panel](./agent-panel.md). -## Model Settings {#model-settings} +Agent Settings is different from the Settings Editor. -### Default Model {#default-model} +| Surface | Opens with | Use it for | +| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------ | +| Agent Settings panel | {#action agent::OpenSettings} | LLM providers, External Agents, MCP servers | +| Settings Editor | {#action zed::OpenSettings} | General Zed settings, `disable_ai`, tool permissions, edit prediction provider setup | +| Settings file | {#action zed::OpenSettingsFile} | Direct JSON edits and settings not exposed in UI | -If you're using [Zed's hosted LLM service](./subscription.md), it sets `claude-sonnet-4-5` as the default model for agentic work (agent panel, inline assistant) and `gpt-5-nano` as the default "fast" model (thread summarization, git commit messages). If you're not subscribed or want to change these defaults, you can manually edit the `default_model` object in your settings: +For general settings mechanics, see [Configuring Zed](../configuring-zed.md). -```json [settings] -{ - "agent": { - "default_model": { - "provider": "openai", - "model": "gpt-4o" - } - } -} -``` +## LLM Providers {#llm-providers} -### Feature-specific Models {#feature-specific-models} +The `LLM Providers` section configures model providers for Zed AI features, including Zed Agent, Inline Assistant, Git commit generation, thread summaries, and similar model-backed features. -You can assign distinct and specific models for the following AI-powered features: +Use this section to: -- Thread summary model: Used for generating thread summaries -- Inline assistant model: Used for the inline assistant feature -- Commit message model: Used for generating Git commit messages -- Subagent model: Used for subagents spawned by the Agent Panel. If not set, the subagent will inherit the model settings from the parent thread. +- sign in to supported subscription-backed providers +- enter provider API keys +- add OpenAI-compatible providers +- remove providers -```json [settings] -{ - "agent": { - "default_model": { - "provider": "zed.dev", - "model": "claude-sonnet-4-5" - }, - "inline_assistant_model": { - "provider": "anthropic", - "model": "claude-3-5-sonnet" - }, - "commit_message_model": { - "provider": "openai", - "model": "gpt-4o-mini" - }, - "thread_summary_model": { - "provider": "google", - "model": "gemini-2.0-flash" - }, - "subagent_model": { - "provider": "zed.dev", - "model": "gpt-5-mini" - } - } -} -``` +For the model-access paths and provider-specific setup, see [LLM Providers](./llm-providers.md). -> If a custom model isn't set for one of these features, they automatically fall back to using the default model. +## Feature-Specific Settings {#feature-specific-settings} -### Commit Message Instructions {#commit-message-instructions} +Some Zed AI features have their own model or prompt settings in `settings.json`, including: -You can provide custom instructions that are included in the prompt whenever a Git commit message is generated. Unlike rules files (such as `.rules` or `AGENTS.md`), these instructions apply only to commit message generation: +- `agent.inline_assistant_model` +- `agent.commit_message_model` +- `agent.thread_summary_model` +- `agent.subagent_model` +- `agent.commit_message_instructions` +- `agent.inline_alternatives` + +Use `agent.commit_message_instructions` for instructions that apply only to generated Git commit messages: ```json [settings] { @@ -74,318 +51,82 @@ You can provide custom instructions that are included in the prompt whenever a G } ``` -These instructions are sent in addition to any project rules files that are present. +For feature-specific model examples, see [Feature-specific Models](#feature-specific-models). -### Alternative Models for Inline Assists {#alternative-assists} +## External Agents {#external-agents} -With the Inline Assistant in particular, you can send the same prompt to multiple models at once. +The External Agents section configures ACP-integrated agents. -Here's how you can customize your settings file ([how to edit](../configuring-zed.md#settings-files)) to add this functionality: +Use `Add Agent` to: -```json [settings] -{ - "agent": { - "default_model": { - "provider": "zed.dev", - "model": "claude-sonnet-4-5" - }, - "inline_alternatives": [ - { - "provider": "zed.dev", - "model": "gpt-5-mini" - } - ] - } -} -``` +- `Install from Registry` +- `Add Custom Agent` -When multiple models are configured, you'll see in the Inline Assistant UI buttons that allow you to cycle between outputs generated by each model. +For setup details and support boundaries, see [External Agents](./external-agents.md). -The models you specify here are always used in _addition_ to your [default model](#default-model). +## MCP Servers {#mcp-servers} -For example, the following configuration will generate three outputs for every assist. -One with Claude Sonnet 4.5 (the default model), another with GPT-5-mini, and another one with Gemini 3 Flash. +The `Model Context Protocol (MCP) Servers` section configures MCP servers connected to Zed. -```json [settings] -{ - "agent": { - "default_model": { - "provider": "zed.dev", - "model": "claude-sonnet-4-5" - }, - "inline_alternatives": [ - { - "provider": "zed.dev", - "model": "gpt-5-mini" - }, - { - "provider": "zed.dev", - "model": "gemini-3-flash" - } - ] - } -} -``` +Use `Add Server` to: -### Model Temperature +- `Add Custom Server` +- `Install from Extensions` -Specify a custom temperature for a provider and/or model: +Each configured server can expose actions such as: + +- `Configure Server` +- `View Tools` + +For MCP setup, auth, server status, and agent-path boundaries, see [MCP](./mcp.md). + +## Related Configuration {#related-configuration} + +Some AI settings are not configured in the Agent Settings panel: + +| Task | Go to | +| ------------------------------------------------------------ | ---------------------------------------------- | +| Choose which tools are available in a Zed Agent thread | [Agent Profiles](./agent-profiles.md) | +| Control whether tool calls are allowed, denied, or confirmed | [Tool Permissions](./tool-permissions.md) | +| Configure reusable task instructions | [Skills](./skills.md) | +| Configure always-on personal or project instructions | [Instructions](./instructions.md) | +| Configure edit prediction providers | [Edit Prediction](./edit-prediction.md) | +| Turn AI off | [AI Quick Start](./quick-start.md#turn-ai-off) | +| Edit raw settings JSON | [Configuring Zed](../configuring-zed.md) | + +## Feature-Specific Models {#feature-specific-models} + +Zed supports feature-specific model settings for Inline Assistant, Git commit generation, thread summaries, and subagents. Configure these in settings when you need a different model for a specific workflow. + +See [LLM Providers](./llm-providers.md) for model access, and [All Settings](../reference/all-settings.md) for the complete settings reference. + +## Model Temperature {#model-temperature} + +Most Zed AI features use the selected model's default generation behavior. +Use `agent.model_parameters` when you need to set a temperature for a provider, +a model, or a specific provider/model pair. ```json [settings] { "agent": { "model_parameters": [ - // To set parameters for all requests to OpenAI models: { - "provider": "openai", - "temperature": 0.5 - }, - // To set parameters for all requests in general: - { - "temperature": 0 - }, - // To set parameters for a specific provider and model: - { - "provider": "zed.dev", + "provider": "anthropic", "model": "claude-sonnet-4-5", - "temperature": 1.0 + "temperature": 0.2 } ] } } ``` -## Agent Panel Settings {#agent-panel-settings} +Zed checks matching entries from last to first. An entry can omit `provider` or +`model` to apply more broadly. For provider-specific model configuration such as +custom model entries, context windows, or gateway routing, see +[LLM Providers](./llm-providers.md) and the provider setup pages. -Note that some of these settings are also surfaced in the Agent Panel's settings UI, which you can access either via the {#action agent::OpenSettings} action or by the dropdown menu on the top-right corner of the panel. +## Rules, Skills, and Instructions {#rules-skills-instructions} -### Font Size +Reusable Rules have been replaced by [Skills](./skills.md). Always-on Rules have moved to [Instructions](./instructions.md), including personal `AGENTS.md` and project instruction files. -Use the `agent_ui_font_size` setting to change the font size of rendered agent responses in the panel. - -```json [settings] -{ - "agent_ui_font_size": 18 -} -``` - -> Editors in the Agent Panel—such as the main message textarea—use monospace fonts and are controlled by `agent_buffer_font_size` (which defaults to `buffer_font_size` when unset). - -### Default Tool Permissions - -> **Note:** In Zed v0.224.0 and above, tool approval uses the `agent.tool_permissions` settings described below. - -The `agent.tool_permissions.default` setting controls the baseline tool approval behavior for Zed's native agent: - -- `"confirm"` (default) — Prompts for approval before running any tool action -- `"allow"` — Auto-approves tool actions without prompting -- `"deny"` — Blocks all tool actions - -```json [settings] -{ - "agent": { - "tool_permissions": { - "default": "confirm" - } - } -} -``` - -Even with `"default": "allow"`, per-tool `always_deny` and `always_confirm` patterns are still respected, so you can auto-approve most actions while keeping guardrails on dangerous or sensitive ones. - -### Per-tool Permission Rules {#per-tool-permission-rules} - -For granular control over individual tool actions, use the `tools` key inside `tool_permissions` to configure regex-based rules that auto-approve, auto-deny, or always require confirmation for specific inputs. - -Each tool entry supports the following keys: - -- `default` — Fallback when no patterns match: `"confirm"`, `"allow"`, or `"deny"` -- `always_allow` — Array of patterns that auto-approve matching actions -- `always_deny` — Array of patterns that block matching actions immediately -- `always_confirm` — Array of patterns that always prompt for confirmation - -```json [settings] -{ - "agent": { - "tool_permissions": { - "default": "allow", - "tools": { - "terminal": { - "default": "confirm", - "always_allow": [ - { "pattern": "^cargo\\s+(build|test|check)" }, - { "pattern": "^git\\s+(status|log|diff)" } - ], - "always_deny": [{ "pattern": "rm\\s+-rf\\s+(/|~)" }], - "always_confirm": [{ "pattern": "sudo\\s" }] - }, - "edit_file": { - "always_deny": [ - { "pattern": "\\.env" }, - { "pattern": "\\.(pem|key)$" } - ] - } - } - } - } -} -``` - -#### Pattern Precedence - -When evaluating a tool action, rules are checked in the following order (highest priority first): - -1. **Built-in security rules** — Hardcoded protections (e.g., `rm -rf /`) that cannot be overridden -2. **`always_deny`** — Blocks matching actions immediately -3. **`always_confirm`** — Requires confirmation for matching actions -4. **`always_allow`** — Auto-approves matching actions. For the terminal tool with chained commands (e.g., `echo hello && rm file`), **all** sub-commands must match an `always_allow` pattern -5. **Tool-specific `default`** — Per-tool fallback when no patterns match (e.g., `tools.terminal.default`) -6. **Global `default`** — Falls back to `tool_permissions.default` - -#### Case Sensitivity - -Patterns are **case-insensitive** by default. To make a pattern case-sensitive, set `case_sensitive` to `true`: - -```json [settings] -{ - "agent": { - "tool_permissions": { - "tools": { - "edit_file": { - "always_deny": [ - { - "pattern": "^Makefile$", - "case_sensitive": true - } - ] - } - } - } - } -} -``` - -#### `copy_path` and `move_path` Patterns - -For the `copy_path` and `move_path` tools, patterns are matched independently against both the source and destination paths. A `deny` or `confirm` match on **either** path takes effect. For `always_allow`, **both** paths must match for auto-approval. - -#### MCP Tool Permissions - -MCP tools use the key format `mcp::` in the `tools` configuration. For example: - -```json [settings] -{ - "agent": { - "tool_permissions": { - "tools": { - "mcp:github:create_issue": { - "default": "confirm" - }, - "mcp:github:create_pull_request": { - "default": "deny" - } - } - } - } -} -``` - -The `default` key on each MCP tool entry is the primary mechanism for controlling MCP tool permissions. Pattern-based rules (`always_allow`, `always_deny`, `always_confirm`) match against an empty string for MCP tools, so most patterns won't match — use the tool-level `default` instead. - -See the [Tool Permissions](./tool-permissions.md) documentation for more examples and complete details. - -> **Note:** Before Zed v0.224.0, tool approval was controlled by the `agent.always_allow_tool_actions` boolean (default `false`). Set it to `true` to auto-approve tool actions, or leave it `false` to require confirmation for edits and tool calls. - -### Edit Display Mode - -Control whether to display review actions (accept & reject) in single buffers after the agent is done performing edits. -The default value is `false`. - -```json [settings] -{ - "agent": { - "single_file_review": false - } -} -``` - -### Sound Notification - -Control whether to hear a notification sound when the agent is done generating changes or needs your input. The default value is `never`. - -- `"never"` (default) — Never play the sound. -- `"when_hidden"` — Only play the sound when the agent panel is not visible. -- `"always"` — Always play the sound on completion. - -```json [settings] -{ - "agent": { - "play_sound_when_agent_done": "never" - } -} -``` - -### Message Editor Size - -Use the `message_editor_min_lines` setting to control the minimum number of lines of height the agent message editor should have. -It is set to `4` by default, and the max number of lines is always double of the minimum. - -```json [settings] -{ - "agent": { - "message_editor_min_lines": 4 - } -} -``` - -### Modifier to Send - -Require a modifier (`cmd` on macOS, `ctrl` on Linux) to send messages. Prevents accidental sends while editing. -The default value is `false`. - -```json [settings] -{ - "agent": { - "use_modifier_to_send": true - } -} -``` - -### Edit Card - -Use the `expand_edit_card` setting to control whether edit cards show the full diff in the Agent Panel. -It is set to `true` by default, but if set to false, the card's height is capped to a certain number of lines, requiring a click to be expanded. - -```json [settings] -{ - "agent": { - "expand_edit_card": false - } -} -``` - -### Terminal Card - -Use the `expand_terminal_card` setting to control whether terminal cards show the command output in the Agent Panel. -It is set to `true` by default, but if set to false, the card will be fully collapsed even while the command is running, requiring a click to be expanded. - -```json [settings] -{ - "agent": { - "expand_terminal_card": false - } -} -``` - -### Feedback Controls - -Control whether to display the thumbs up/down buttons at the bottom of each agent response, allowing you to give Zed feedback about the agent's performance. -The default value is `true`. - -```json [settings] -{ - "agent": { - "enable_feedback": false - } -} -``` +Older builds or transitional UI may still refer to `Rules`. Use [Skills](./skills.md) for reusable task instructions and [Instructions](./instructions.md) for always-on context. diff --git a/docs/src/ai/agents.md b/docs/src/ai/agents.md new file mode 100644 index 0000000000..bed5e7184e --- /dev/null +++ b/docs/src/ai/agents.md @@ -0,0 +1,35 @@ +--- +title: AI Agents in Zed +description: Compare Zed Agent, External Agents, and Terminal Threads. +--- + +# Agents + +Zed supports three agent paths. Choose the path based on how you want agentic work to run. + +| Agent path | Runs in | Uses | Best when | +| ----------------------------------------- | ------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [Zed Agent](./zed-agent.md) | Agent Panel and Threads Sidebar | Zed-configured LLM providers, native tools, skills, instructions, MCP | You want Zed's native agent integration | +| [External Agents](./external-agents.md) | Agent Panel and Threads Sidebar | ACP agent process and its own auth/config | You want Claude, Codex, OpenCode, Copilot, Cursor, Pi, or another ACP-integrated agent | +| [Terminal Threads](./terminal-threads.md) | Threads Sidebar and terminal | Native CLI/TUI auth/config | You want the tool's command-line experience organized in Zed | + +An agent path is sometimes called a harness. It is the way agentic work is started, displayed, configured, and controlled in Zed. + +## Agent Path vs. LLM Provider {#agent-path-vs-llm-provider} + +| Question | Start here | +| ----------------------------------------- | ----------------------------------- | +| Which agent or CLI should run the work? | This page | +| Which model should power Zed AI features? | [LLM Providers](./llm-providers.md) | + +The [Zed Agent](./zed-agent.md) uses models configured in Zed. [External Agents](./external-agents.md) and [Terminal Threads](./terminal-threads.md) may use their own model setup. + +## Thread Types {#thread-types} + +Threads are the units shown in the [Threads Sidebar](./parallel-agents.md#threads-sidebar). Thread types include: + +- [Zed Agent](./zed-agent.md) threads +- [External Agent](./external-agents.md) threads +- [Terminal Threads](./terminal-threads.md) + +Use [Parallel Agents](./parallel-agents.md) to run and manage multiple threads at once. diff --git a/docs/src/ai/ai-improvement.md b/docs/src/ai/ai-improvement.md index b1fda4cbf6..08cec1389a 100644 --- a/docs/src/ai/ai-improvement.md +++ b/docs/src/ai/ai-improvement.md @@ -1,96 +1,83 @@ --- -title: AI Improvement and Data Collection - Zed -description: Zed's opt-in approach to AI data collection for improving the agent panel and edit predictions. +title: Feedback and Training Data - Zed +description: Understand opt-in AI feedback ratings, Edit Prediction training data, and when Zed may retain AI data. --- -# Zed AI Features and Privacy +# Feedback and Training Data -## Overview +Normal AI requests are not retained by Zed. For +[Zed-hosted models](../account/zed-hosted-models.md), provider agreements require +zero data retention and prohibit training on your prompts or code context. This +page covers the cases where Zed may retain AI data because you explicitly shared +it or opted in. AI features in Zed include: - [Agent Panel](./agent-panel.md) -- [Edit Predictions](./edit-prediction.md) -- [Inline Assist](./inline-assistant.md) -- Auto Git Commit Message Generation +- [Edit Prediction](./edit-prediction.md) +- [Inline Assistant](./inline-assistant.md) +- [Git commit generation](../git.md#ai-support-in-git) -By default, Zed does not store your prompts or code context. This data is sent to your selected AI provider (e.g., Anthropic, OpenAI, Google, or xAI) to generate responses, then discarded. Zed will not use your data to evaluate or improve AI features unless you explicitly share it (see [AI Feedback with Ratings](#ai-feedback-with-ratings)) or you opt in to edit prediction training data collection (see [Edit Predictions](#edit-predictions)). +For the broader request path and provider data boundaries, see +[AI Privacy](./privacy-and-security.md). -Zed is model-agnostic by design, and none of this changes based on which provider you choose. You can use your own API keys or Zed's hosted models without any data being retained. +## Zed-Hosted Model Commitments {#data-retention-and-training} -### Data Retention and Training +Zed-hosted model zero-data-retention and no-training commitments are documented +on [AI Privacy](./privacy-and-security.md#data-retention-and-training). -Zed's Agent Panel can be used via: +## Response Ratings and Feedback {#ai-feedback-with-ratings} -- [Zed's hosted models](./subscription.md) -- [connecting a non-Zed AI service via API key](./llm-providers.md) -- using an [external agent](./external-agents.md) via ACP +You can rate AI responses or submit feedback to help improve Zed's system prompt, +tools, and AI product experience. Each share is opt-in, and sharing once does not +grant permission for future collection. -When using Zed's hosted models, we require assurances from our service providers that your user content won't be used for training models. +> **Warning:** Rating an AI response sends the conversation thread to Zed. The +> conversation thread includes your messages, AI responses, and thread metadata. +> If you do not want the thread persisted by Zed, do not rate the response. -| Provider | No Training Guarantee | Zero-Data Retention (ZDR) | -| --------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| Anthropic | [Yes](https://www.anthropic.com/legal/commercial-terms) | [Yes](https://privacy.anthropic.com/en/articles/8956058-i-have-a-zero-data-retention-agreement-with-anthropic-what-products-does-it-apply-to) | -| Google | [Yes](https://cloud.google.com/terms/service-terms) | [Yes](https://cloud.google.com/terms/service-terms), see Service Terms sections 17 and 19h | -| OpenAI | [Yes](https://openai.com/enterprise-privacy/) | [Yes](https://platform.openai.com/docs/guides/your-data) | -| xAI | [Yes](https://x.ai/legal/faq-enterprise) | [Yes](https://x.ai/legal/faq-enterprise) | +### Data Collected from Feedback {#data-collected-ai-feedback} -When you use your own API keys or external agents, **Zed does not have control over how your data is used by that service provider.** -You should reference your agreement with each service provider to understand what terms and conditions apply. +For conversation threads you explicitly share through ratings or feedback, Zed +may store: -### AI Feedback with Ratings +- your messages and AI responses in the conversation thread +- any commentary you include with your rating or feedback +- thread metadata, such as model used, token counts, and timestamps +- metadata about your Zed installation -You can provide feedback on Zed's AI features by rating specific AI responses in Zed and sharing details related to those conversations with Zed. Each share is opt-in, and sharing once will not cause future content or data to be shared again. +If you do not rate responses or submit feedback, Zed does not store Customer Data +related to your AI feature usage for improvement. -> **Rating = Data Sharing:** When you rate a response, your entire conversation thread is sent to Zed. This includes messages, AI responses, and thread metadata. -> **_If you don't want data persisted on Zed's servers, don't rate_**. We will not collect data for improving our AI features without you explicitly rating responses. +Telemetry related to Zed's AI features is collected separately. This includes +metadata such as the AI feature being used and high-level interactions with the +feature to understand performance, such as agent response time or edit acceptance +and rejection. See [Telemetry](../telemetry.md) for details. -### Data Collected (AI Feedback) +Collected feedback data is stored in Snowflake. Zed periodically reviews this +data to refine prompts, tools, and product behavior. Stored feedback data is +anonymized and stripped of sensitive information such as access tokens, user IDs, +and email addresses. -For conversations you have explicitly shared with us via rating, Zed may store: +## Edit Prediction Training Data {#edit-predictions} -- All messages in the thread (your prompts and AI responses) -- Any commentary you include with your rating -- Thread metadata (model used, token counts, timestamps) -- Metadata about your Zed installation +Zed does not collect training data for the Edit Prediction model unless all of +these conditions are met: -If you do not rate responses, Zed will not store Customer Data (code, conversations, responses) related to your usage of the AI features. +1. You opt in by toggling **Training Data Collection** under the **Privacy** + section of the Edit Prediction status bar menu. +2. The project is open source, detected by the presence of a license file. See + the [license detection logic](https://github.com/zed-industries/zed/blob/main/crates/edit_prediction/src/license_detection.rs). +3. The file is not excluded by `edit_predictions.disabled_globs`. -Telemetry related to Zed's AI features is collected. This includes metadata such as the AI feature being used and high-level interactions with the feature to understand performance (e.g., Agent response time, edit acceptance/rejection in the Agent panel or edit completions). You can read more in Zed's [telemetry](../telemetry.md) documentation. +Edit Prediction setup and provider configuration live on the +[Edit Prediction](./edit-prediction.md) page. This page only covers training data +collection and retention. -Collected data is stored in Snowflake, a private database. We periodically review this data to refine the agent's system prompt and tool use. All data is anonymized and stripped of sensitive information (access tokens, user IDs, email addresses). +### File Exclusions {#file-exclusions} -## Edit Predictions - -Edit predictions can be powered by **Zed's Zeta model** or by **third-party providers** like GitHub Copilot. - -### Zed's Zeta Model (Default) - -Zed sends a limited context window to the model to generate predictions: - -- A code excerpt around your cursor (not the full file) -- Recent edits as diffs -- Relevant excerpts from related open files - -This data is processed transiently to generate predictions and is not retained afterward. - -### Third-Party Providers - -When using third-party providers like GitHub Copilot, **Zed does not control how your data is handled** by that provider. You should consult their Terms and Conditions directly. - -Note: Zed's `disabled_globs` settings will prevent predictions from being requested, but third-party providers may receive file content when files are opened. - -### Training Data: Opt-In for Open Source Projects - -Zed does not collect training data for our edit prediction model unless the following conditions are met: - -1. **You opt in** – Toggle "Training Data Collection" under the **Privacy** section of the edit prediction status bar menu (click the edit prediction icon in the status bar). -2. **The project is open source** — detected via LICENSE file ([see detection logic](https://github.com/zed-industries/zed/blob/main/crates/edit_prediction/src/license_detection.rs)) -3. **The file isn't excluded** — via `disabled_globs` - -### File Exclusions - -Certain files are always excluded from edit predictions—regardless of opt-in status: +Certain files are always excluded from Edit Prediction training data collection, +regardless of opt-in status: ```json [settings] { @@ -101,13 +88,16 @@ Certain files are always excluded from edit predictions—regardless of opt-in s "**/*.key", "**/*.cert", "**/*.crt", + "**/.dev.vars", "**/secrets.yml" ] } } ``` -Users may explicitly exclude additional paths and/or file extensions by adding them to [`edit_predictions.disabled_globs`](https://zed.dev/docs/reference/all-settings#edit-predictions) in their Zed settings file ([how to edit](../configuring-zed.md#settings-files)): +You can explicitly exclude additional paths or file extensions by adding them to +[`edit_predictions.disabled_globs`](https://zed.dev/docs/reference/all-settings#edit-predictions) +in your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): ```json [settings] { @@ -117,22 +107,39 @@ Users may explicitly exclude additional paths and/or file extensions by adding t } ``` -### Data Collected (Edit Prediction Training Data) +### Data Collected from Edit Prediction Training {#data-collected-edit-prediction-training} -For open source projects where you've opted in, Zed may collect: +For open source projects where you opted in, Zed may collect: -- Code excerpt around your cursor -- Recent edit diffs -- The generated prediction -- Repository URL and git revision -- Buffer outline and diagnostics +- code excerpts around your cursor +- recent edit diffs +- the generated prediction +- repository URL and git revision +- buffer outline and diagnostics -Collected data is stored in Snowflake. We periodically review this data to select training samples for inclusion in our model training dataset. We ensure any included data is anonymized and contains no sensitive information (access tokens, user IDs, email addresses, etc). This training dataset is publicly available at [huggingface.co/datasets/zed-industries/zeta](https://huggingface.co/datasets/zed-industries/zeta). +Collected data is stored in Snowflake. Zed periodically reviews this data to +select training samples for inclusion in the model training dataset. Included +data is anonymized and stripped of sensitive information such as access tokens, +user IDs, and email addresses. -### Model Output +The training dataset is publicly available at +[huggingface.co/datasets/zed-industries/zeta](https://huggingface.co/datasets/zed-industries/zeta). -We then use this training dataset to fine-tune [Qwen2.5-Coder-7B](https://huggingface.co/Qwen/Qwen2.5-Coder-7B) and make the resulting model available at [huggingface.co/zed-industries/zeta](https://huggingface.co/zed-industries/zeta). +### Training Dataset and Model Output {#training-dataset-and-model-output} -## Applicable terms +Zed uses this training dataset to fine-tune +[Qwen2.5-Coder-7B](https://huggingface.co/Qwen/Qwen2.5-Coder-7B) and makes the +resulting model available at +[huggingface.co/zed-industries/zeta](https://huggingface.co/zed-industries/zeta). -Please see the [Zed Terms of Service](https://zed.dev/terms) for more. +## Business Controls {#business-controls} + +On Zed Business, data sharing is off by default and controlled by organization +administrators. Administrators can prevent members from submitting agent thread +feedback or opting into Edit Prediction training data collection. See +[Privacy for Business](../business/privacy.md) and +[Admin Controls](../business/admin-controls.md#data-sharing). + +## Applicable Terms {#applicable-terms} + +See the [Zed Terms of Service](https://zed.dev/terms) for more. diff --git a/docs/src/ai/by-company.md b/docs/src/ai/by-company.md new file mode 100644 index 0000000000..5eb3d27a7c --- /dev/null +++ b/docs/src/ai/by-company.md @@ -0,0 +1,107 @@ +--- +title: AI by Company - Zed +description: Find the right Zed setup path for OpenAI, ChatGPT, Codex, Claude, Gemini, Copilot, Cursor, OpenCode, Pi, OpenRouter, Bedrock, local models, and other AI tools. +--- + +# AI by Company + +Use this page when you know the company, subscription, provider, agent, or CLI you want to use in Zed. + +For detailed setup, follow the links in the `Setup` column. This page answers routing questions; it does not replace the setup pages. + +## Zed {#zed} + +| Path | Support level | What you get | Account / billing | Setup | +| -------------------- | -------------- | --------------------------------- | ----------------------- | ---------------------------------------------------- | +| Zed-hosted models | Built into Zed | Hosted models for Zed AI features | Billed through Zed | [Zed-Hosted Models](../account/zed-hosted-models.md) | +| Zeta edit prediction | Built into Zed | Edit predictions while you type | Included by plan limits | [Edit Prediction](./edit-prediction.md) | + +## OpenAI / ChatGPT / Codex {#openai-chatgpt-codex} + +| Path | Support level | What you get | Account / billing | Setup | +| -------------------- | ----------------- | ----------------------------------------------------- | --------------------- | ------------------------------------------------------------------------- | +| ChatGPT Subscription | Configured in Zed | Subscription-backed OpenAI models for Zed AI features | ChatGPT Plus or Pro | [Use an Existing Subscription](./use-an-existing-subscription.md#chatgpt) | +| OpenAI API | Configured in Zed | OpenAI models through API access | OpenAI API billing | [Use API Access](./use-api-access.md#openai) | +| Codex via ACP | Hosted in Zed | Codex in an External Agent thread | Owned by Codex/OpenAI | [External Agents](./external-agents.md#codex-cli) | +| Codex CLI | Run in terminal | Native Codex CLI experience in a Terminal Thread | Owned by Codex/OpenAI | [Terminal Threads](./terminal-threads.md) | + +## Anthropic / Claude / Claude Code {#anthropic-claude} + +| Path | Support level | What you get | Account / billing | Setup | +| -------------------- | ----------------- | -------------------------------------------------- | --------------------------------------- | ---------------------------------------------------- | +| Anthropic API | Configured in Zed | Claude models through API access | Anthropic API billing | [Use API Access](./use-api-access.md#anthropic) | +| Claude Agent via ACP | Hosted in Zed | Claude in an External Agent thread | Owned by Claude/Anthropic | [External Agents](./external-agents.md#claude-agent) | +| Claude Code CLI | Run in terminal | Native Claude Code experience in a Terminal Thread | Claude subscription or Claude Code auth | [Terminal Threads](./terminal-threads.md) | + +Claude Pro and Max subscriptions are separate from Anthropic API credits. If you want Claude subscription-limit behavior, use Claude Agent or Claude Code where supported. See [Use an Existing Subscription](./use-an-existing-subscription.md#claude). + +## Google / Gemini / Gemini CLI {#google-gemini} + +| Path | Support level | What you get | Account / billing | Setup | +| ------------- | -------------------------------- | ------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------- | +| Google AI API | Configured in Zed | Gemini models through API access | Google AI API billing | [Use API Access](./use-api-access.md#google-ai) | +| Gemini CLI | Hosted in Zed or run in terminal | Gemini CLI as an External Agent or native CLI/TUI | Owned by Gemini CLI | [External Agents](./external-agents.md#gemini-cli), [Terminal Threads](./terminal-threads.md) | + +## GitHub / Copilot {#github-copilot} + +| Path | Support level | What you get | Account / billing | Setup | +| ----------------------- | ----------------- | ---------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------- | +| GitHub Copilot Chat | Configured in Zed | Copilot Chat models for Zed AI features | GitHub Copilot/Copilot Chat | [Use an Existing Subscription](./use-an-existing-subscription.md#github-copilot) | +| Copilot edit prediction | Built into Zed | Edit prediction provider option | GitHub Copilot | [Edit Prediction](./edit-prediction.md) | +| Copilot External Agent | Hosted in Zed | Copilot in an External Agent thread, where available | Owned by Copilot | [External Agents](./external-agents.md#copilot) | +| Copilot CLI | Run in terminal | Native CLI experience, where available | Owned by Copilot | [Terminal Threads](./terminal-threads.md) | + +## OpenCode / Zen / Go {#opencode} + +| Path | Support level | What you get | Account / billing | Setup | +| ----------------------- | ----------------- | ----------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------ | +| OpenCode provider | Configured in Zed | OpenCode models for Zed AI features | OpenCode API key; Zen or Go affects available models | [Use API Access](./use-api-access.md#opencode) | +| OpenCode External Agent | Hosted in Zed | OpenCode in an External Agent thread, where available | Owned by OpenCode | [External Agents](./external-agents.md#opencode) | +| `opencode` CLI | Run in terminal | Native OpenCode CLI experience | Owned by OpenCode | [Terminal Threads](./terminal-threads.md) | + +## Cursor {#cursor} + +| Path | Support level | What you get | Account / billing | Setup | +| --------------------- | --------------- | ------------------------------------------------------ | --------------------------- | ---------------------------------------------- | +| Cursor External Agent | Hosted in Zed | Cursor in an External Agent thread, where available | Cursor account/subscription | [External Agents](./external-agents.md#cursor) | +| Cursor CLI/TUI | Run in terminal | Native Cursor command-line experience, where available | Cursor account/subscription | [Terminal Threads](./terminal-threads.md) | + +Cursor subscriptions do not configure Zed's LLM provider settings. If you want to use a work Cursor subscription in Zed, use the Cursor External Agent or a Terminal Threads workflow where available. + +## Pi Coding Agent {#pi} + +| Path | Support level | What you get | Account / billing | Setup | +| --------------- | --------------- | -------------------------------------------------- | ----------------- | ------------------------------------------ | +| Pi Coding Agent | Hosted in Zed | Pi in an External Agent thread, where available | Owned by Pi | [External Agents](./external-agents.md#pi) | +| Pi CLI/TUI | Run in terminal | Native Pi command-line experience, where available | Owned by Pi | [Terminal Threads](./terminal-threads.md) | + +Pi is an agent harness, not a Zed LLM subscription. Pi may support provider auth such as ChatGPT, Claude, or Copilot through its own setup flow. + +## DeepSeek {#deepseek} + +| Path | Support level | What you get | Account / billing | Setup | +| ------------ | ----------------- | ----------------------------------- | ----------------------------------------------- | ---------------------------------------------- | +| DeepSeek API | Configured in Zed | DeepSeek models for Zed AI features | DeepSeek API credits, top-ups, or usage billing | [Use API Access](./use-api-access.md#deepseek) | + +Paid DeepSeek usage is API access in Zed, not subscription sign-in. + +## Gateways and Cloud Platforms {#gateways} + +| Provider | Support level | What you get | Account / billing | Setup | +| ----------------- | ----------------- | ------------------------------------ | ------------------ | ----------------------------------------------------- | +| OpenRouter | Configured in Zed | Gateway access to multiple providers | OpenRouter billing | [Use a Gateway](./use-a-gateway.md#openrouter) | +| Vercel AI Gateway | Configured in Zed | Gateway access through Vercel | Vercel billing | [Use a Gateway](./use-a-gateway.md#vercel-ai-gateway) | +| Amazon Bedrock | Configured in Zed | AWS-hosted model access | AWS billing | [Use a Gateway](./use-a-gateway.md#amazon-bedrock) | + +## Local Models {#local-models} + +| Tool | Support level | What you get | Account / billing | Setup | +| --------------------------------- | ----------------- | -------------------------------------- | ----------------- | ------------------------------------------------------------- | +| Ollama | Configured in Zed | Local models for Zed AI features | Local/self-hosted | [Use a Local Model](./use-a-local-model.md#ollama) | +| LM Studio | Configured in Zed | Local models for Zed AI features | Local/self-hosted | [Use a Local Model](./use-a-local-model.md#lm-studio) | +| Local OpenAI-compatible server | Configured in Zed | Local or self-hosted model endpoint | Local/self-hosted | [Use a Local Model](./use-a-local-model.md#openai-compatible) | +| Local/self-hosted edit prediction | Configured in Zed | Edit predictions from a local provider | Local/self-hosted | [Edit Prediction](./edit-prediction.md) | + +## Other API Providers {#other-api-providers} + +For Mistral, xAI, and OpenAI-compatible endpoints that are not listed above, see [Use API Access](./use-api-access.md). diff --git a/docs/src/ai/configuration.md b/docs/src/ai/configuration.md deleted file mode 100644 index 28ec021acc..0000000000 --- a/docs/src/ai/configuration.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Configure AI in Zed - Providers, Models, and Settings -description: Set up AI in Zed with hosted models, your own API keys, or external agents. Includes how to disable AI entirely. ---- - -# Configuration - -You can configure multiple dimensions of AI usage in Zed: - -1. Which LLM providers you can use - - Zed's hosted models, which require [authentication](../authentication.md) and [subscription](./subscription.md) - - [Using your own API keys](./llm-providers.md), which do not require the above - - Using [external agents like Claude Agent](./external-agents.md), which also do not require the above -2. [Model parameters and usage](./agent-settings.md#model-settings) -3. [Interactions with the Agent Panel](./agent-settings.md#agent-panel-settings) - -## Turning AI Off Entirely - -To disable all AI features, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "disable_ai": true -} -``` - -See [this blog post](https://zed.dev/blog/disable-ai-features) for further context on this option. diff --git a/docs/src/ai/edit-prediction.md b/docs/src/ai/edit-prediction.md index fda36a39cd..de1eb23ae4 100644 --- a/docs/src/ai/edit-prediction.md +++ b/docs/src/ai/edit-prediction.md @@ -10,6 +10,10 @@ Each keystroke sends a new request to the edit prediction provider, which return The default provider is [Zeta, an open source model developed by Zed](https://zed.dev/blog/zeta2), but you can also use [other providers](#other-providers) like GitHub Copilot, Mercury Coder, and Codestral. +For privacy and training data details, see +[AI Privacy](./privacy-and-security.md) and +[Feedback and Training Data](./ai-improvement.md#edit-predictions). + ## Configuring Zeta To use Zeta, [sign in](../authentication.md#what-features-require-signing-in). @@ -31,7 +35,7 @@ The Z icon in the status bar also indicates Zeta is active. ### Pricing and Plans -The free plan includes 2,000 Zeta predictions per month. The [Pro plan](../ai/plans-and-usage.md) removes this limit. See [Zed's pricing page](https://zed.dev/pricing) for details. +The free plan includes 2,000 Zeta predictions per month. The [Pro plan](../account/plans-and-pricing.md) removes this limit. See [Zed's pricing page](https://zed.dev/pricing) for details. ### Switching Modes {#switching-modes} diff --git a/docs/src/ai/external-agents.md b/docs/src/ai/external-agents.md index 53f5e9cee1..fcb1e4ea1f 100644 --- a/docs/src/ai/external-agents.md +++ b/docs/src/ai/external-agents.md @@ -1,209 +1,141 @@ --- -title: Use Claude Agent, Gemini CLI, and Codex in Zed -description: Run Claude Agent, Gemini CLI, Codex, and other AI coding agents directly in Zed via the Agent Client Protocol (ACP). +title: External Agents - Zed +description: Install and use ACP-integrated External Agents such as Claude, Codex, OpenCode, Copilot, Cursor, and Pi Coding Agent in Zed. --- # External Agents -Zed supports many external agents, including CLI-based ones, through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). +External Agents are agents that integrate with Zed through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). Zed hosts the thread in the [Agent Panel](./agent-panel.md) and [Threads Sidebar](./parallel-agents.md#threads-sidebar), while the External Agent usually owns its own runtime, auth, model selection, tools, and native configuration. -Zed supports [Gemini CLI](https://github.com/google-gemini/gemini-cli) (the reference ACP implementation), [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview), [Codex](https://developers.openai.com/codex), [GitHub Copilot](https://github.com/github/copilot-language-server-release), and [additional agents](#add-more-agents) you can configure. +Use [Terminal Threads](./terminal-threads.md) instead when you want to run a CLI or TUI directly in a terminal-backed thread. -For Zed's built-in agent and the full list of tools it can use natively, see [Agent Tools](./tools.md). +External Agents run through their own process and provider relationship. Billing, legal terms, retention, and data handling are between you and the agent provider. Zed does not charge for External Agents. -> Note that Zed's interaction with external agents is strictly UI-based; the billing, legal, and terms arrangement is directly between you and the agent provider. -> Zed does not charge for use of external agents, and our [zero-data retention agreements/privacy guarantees](./ai-improvement.md) are **_only_** applicable for Zed's hosted models. +For Zed-hosted models and Zed-managed AI features, see [AI Privacy](./privacy-and-security.md) and [Feedback and Training Data](./ai-improvement.md). + +## Install from the ACP Registry {#registry} + +The ACP Registry is the primary way to install common External Agents in Zed. + +Open the registry with {#action zed::AcpRegistry}, or open [Agent Settings](./agent-settings.md) with {#action agent::OpenSettings}, click `Add Agent`, and choose `Install from Registry`. + +After installation, the agent appears in the new-thread menu in the Agent Panel and Threads Sidebar. + +## Common Agents {#common-agents} + +Common External Agents include: + +- Claude +- Codex +- OpenCode +- Copilot +- Cursor +- Pi Coding Agent + +This list is curated, not exhaustive. Open the ACP Registry in Zed for the current list of available agents. + +For company-specific setup paths, including Claude, Codex, Gemini, OpenCode, Copilot, Cursor, and Pi, see [AI by Company](./by-company.md). + +## Claude Agent {#claude-agent} + +Use Claude Agent when you want Claude running as an ACP-integrated External Agent in Zed. + +Install Claude Agent from the [ACP Registry](#registry), then start a Claude Agent thread from the Agent Panel or Threads Sidebar. Claude Agent owns its own authentication and billing. An Anthropic API key configured for [Zed Agent](./zed-agent.md) does not automatically configure Claude Agent. + +To choose your billing method, open a Claude Agent thread, run `/login`, and authenticate with an API key or with Claude Code where supported. Claude-specific files such as `CLAUDE.md` may be read by Claude Agent directly. + +## Codex {#codex-cli} + +Use Codex when you want Codex running as an ACP-integrated External Agent in Zed. + +Install Codex from the [ACP Registry](#registry), then start a Codex thread from the Agent Panel or Threads Sidebar. Codex owns its own authentication and billing. An OpenAI API key configured for [Zed Agent](./zed-agent.md) does not automatically configure Codex. + +Codex may support ChatGPT login, Codex API keys, OpenAI API keys, or Codex-native configuration depending on the installed version and environment. To change authentication, use the Codex thread's native login/logout flow. ## Gemini CLI {#gemini-cli} -Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md). -Under the hood we run Gemini CLI in the background, and talk to it over ACP. +Use Gemini CLI when you want Gemini running as an ACP-integrated External Agent in Zed. -### Getting Started +Install Gemini CLI from the [ACP Registry](#registry), then start a Gemini CLI thread from the Agent Panel or Threads Sidebar. Gemini CLI owns its own authentication and may prompt you to log in with Google, Vertex AI, or another Gemini-supported flow. -First open the agent panel with {#kb agent::ToggleFocus}, and then start a new Gemini CLI thread using the agent selector button on the left (in the empty state) or the `+` button in the top right. +If `GEMINI_API_KEY` or `GOOGLE_AI_API_KEY` is available to the agent process, Gemini CLI may use that key. Zed-configured Google AI provider settings are separate from Gemini CLI's native configuration. -If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include: +## OpenCode {#opencode} -```json [keymap] -[ - { - "bindings": { - "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }] - } - } -] -``` +Use OpenCode when you want OpenCode running as an ACP-integrated External Agent in Zed. -#### Installation +Install OpenCode from the [ACP Registry](#registry), then start an OpenCode thread from the Agent Panel or Threads Sidebar. OpenCode owns its own auth, model selection, and subscription behavior. To use OpenCode models in Zed Agent instead, configure [OpenCode API access](./use-api-access.md#opencode). -The first time you create a Gemini CLI thread, Zed will install [@google/gemini-cli](https://github.com/google-gemini/gemini-cli). -This installation is only available to Zed and is kept up to date as you use the agent. +## Copilot {#copilot} -#### Authentication +Use Copilot External Agents where available when you want Copilot running as an ACP-integrated External Agent in Zed. -After you have Gemini CLI running, you'll be prompted to authenticate. +Copilot agent auth is owned by the Copilot integration. To use Copilot Chat models in Zed Agent or Copilot for edit prediction, see [Use an Existing Subscription](./use-an-existing-subscription.md#github-copilot). -Click the "Login" button to open the Gemini CLI interactively, where you can log in with your Google account or [Vertex AI](https://cloud.google.com/vertex-ai) credentials. -Zed does not see your OAuth or access tokens in this case. +## Cursor {#cursor} -If the `GEMINI_API_KEY` environment variable (or `GOOGLE_AI_API_KEY`) is already set, or you have configured a Google AI API key in Zed's [language model provider settings](./llm-providers.md#google-ai), it will be passed to Gemini CLI automatically. +Use Cursor External Agents where available when you want Cursor running as an ACP-integrated External Agent in Zed. -For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md). +Cursor subscriptions do not configure Zed's LLM provider settings. Use Cursor's external-agent or CLI/TUI setup where available. -### Usage +## Pi Coding Agent {#pi} -Gemini CLI supports the same workflows as Zed's first-party agent: code generation, refactoring, debugging, and Q&A. Add context by @-mentioning files, recent threads, or symbols. +Use Pi Coding Agent when you want Pi running as an ACP-integrated External Agent in Zed. -> Some agent panel features are not yet available with Gemini CLI: editing past messages, resuming threads from history, and checkpointing. +Pi is an agent harness, not a Zed LLM subscription. Configure any provider auth, subscriptions, tools, or model choices in Pi. -## Claude Agent +## Start an External Agent Thread {#start-thread} -Similar to Gemini CLI, you can also run [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview) directly via Zed's [agent panel](./agent-panel.md). -Under the hood, Zed runs the Claude Agent SDK, which runs Claude Code under the hood, and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/claude-agent-acp). +Open the [Agent Panel](./agent-panel.md), then use the agent selector or the new-thread menu to start a thread with an installed External Agent. -### Getting Started +You can also create keybindings for specific agents with {#action agent::NewExternalAgentThread}. -Open the agent panel with {#kb agent::ToggleFocus}, and then start a new Claude Agent thread using the agent selector button on the left (in the empty state) or the `+` button in the top right. +## Configuration Boundaries {#configuration-boundaries} -If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include: +External Agents run as separate processes that communicate with Zed over ACP. This creates a boundary between Zed configuration and agent-native configuration. -```json [keymap] -[ - { - "bindings": { - "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude-acp" }] - } - } -] -``` +| Capability | Behavior in External Agent threads | +| -------------------------------- | ------------------------------------------------------------------------------------------ | +| Model/provider config | Usually owned by the External Agent | +| Auth/API keys/subscriptions | Usually owned by the External Agent | +| Zed Agent profiles | Do not apply unless the integration says otherwise | +| Zed Skills | Do not apply as Zed Skills | +| Native agent skills/instructions | Depends on the agent | +| Zed MCP servers | May be forwarded over ACP | +| Native MCP config | May also be read by the agent | +| Tool permissions | Zed ACP/tool forwarding permissions may apply; native tool permissions depend on the agent | -### Authentication +For Zed's native agent configuration, see [Zed Agent](./zed-agent.md). -As of version `0.202.7`, authentication to Zed's Claude Agent installation is decoupled entirely from Zed's agent. -That is to say, an Anthropic API key added via the [Zed Agent's settings](./llm-providers.md#anthropic) will _not_ be utilized by Claude Agent for authentication and billing. +## Agent-Specific Auth and Config {#agent-auth-config} -To ensure you're using your billing method of choice, [open a new Claude Agent thread](./agent-panel.md#new-thread). -Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription. +External Agents may have their own sign-in flow, API key setup, subscription behavior, environment variables, and config files. -#### Installation +Examples: -The first time you create a Claude Agent thread, Zed will install [@zed-industries/claude-agent-acp](https://github.com/zed-industries/claude-agent-acp). -This installation is only available to Zed and is kept up to date as you use the agent. +- Claude Agent may use Claude Code auth and Claude-native config. +- Codex may use ChatGPT login, Codex API keys, OpenAI API keys, or Codex-native config. +- Cursor subscriptions do not configure Zed's LLM provider settings; use Cursor's agent or CLI setup where available. +- Pi Coding Agent is an agent harness. Configure provider auth in Pi. -Zed will always use this managed version of the Claude Agent adapter, which includes a vendored version of the Claude Code CLI, even if you have it installed globally. +If an External Agent supports subscription-backed behavior, configure that in the agent unless the agent's Zed integration says otherwise. -If you want to override the executable used by the adapter, you can set the `CLAUDE_CODE_EXECUTABLE` environment variable in your settings to the path of your preferred executable. +## Remote Projects {#remote-projects} -```json -{ - "agent_servers": { - "claude-acp": { - "type": "registry", - "env": { - "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable" - } - } - } -} -``` +External Agents may read credentials locally, remotely, or through their own sign-in flow. Check the specific agent's setup path when using SSH, dev containers, or other remote projects. -### Usage +Zed LLM provider API keys saved in the local keychain are not automatically the same as an External Agent's credentials. -Claude Agent supports the same workflows as Zed's first-party agent. Add context by @-mentioning files, recent threads, diagnostics, or symbols. +## Custom Agents {#custom-agents} -In complement to talking to it [over ACP](https://agentclientprotocol.com), Zed relies on the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) to support some of its specific features. -However, the SDK doesn't yet expose everything needed to fully support all of them: +Use custom agents when you are developing an ACP-compatible agent or need to run an agent that is not in the registry. -- Slash Commands: [Custom slash commands](https://code.claude.com/docs/en/slash-commands#custom-slash-commands) are fully supported, and have been merged into skills. A subset of [built-in commands](https://code.claude.com/docs/en/slash-commands#built-in-slash-commands) are supported. -- [Subagents](https://code.claude.com/docs/en/sub-agents) are supported. -- [Agent teams](https://code.claude.com/docs/en/agent-teams) are currently _not_ supported. -- [Hooks](https://code.claude.com/docs/en/hooks-guide) are currently _not_ supported. - -> Some [agent panel](./agent-panel.md) features are not yet available with Claude Agent: editing past messages, resuming threads from history, and checkpointing. - -#### CLAUDE.md - -Claude Agent in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory. - -If you don't have a `CLAUDE.md` file, you can ask Claude Agent to create one for you through the `init` slash command. - -## Codex CLI - -You can also run [Codex CLI](https://github.com/openai/codex) directly via Zed's [agent panel](./agent-panel.md). -Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/codex-acp). - -### Getting Started - -As of version `0.208`, you should be able to use Codex directly from Zed. -Open the agent panel with {#kb agent::ToggleFocus}, and then start a new Codex thread using the agent selector button on the left (in the empty state) or the `+` button in the top right. - -If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include: - -```json -[ - { - "bindings": { - "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "codex-acp" }] - } - } -] -``` - -### Authentication - -Authentication to Zed's Codex installation is decoupled entirely from Zed's agent. -That is to say, an OpenAI API key added via the [Zed Agent's settings](./llm-providers.md#openai) will _not_ be utilized by Codex for authentication and billing. - -To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread). -The first time you will be prompted to authenticate with one of three methods: - -1. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_ -2. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`. -3. `OPENAI_API_KEY` - uses an API key you have set in your environment under the variable `OPENAI_API_KEY`. - -If you are already logged in and want to change your authentication method, type `/logout` in the thread and authenticate again. - -If you want to use a third-party provider with Codex, you can configure that with your [Codex config.toml](https://github.com/openai/codex/blob/main/docs/config.md#model-selection) or pass extra [args/env variables](https://github.com/openai/codex/blob/main/docs/config.md#model-selection) to your Codex agent servers settings. - -#### Installation - -The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp). -This installation is only available to Zed and is kept up to date as you use the agent. - -Zed will always use this managed version of Codex even if you have it installed globally. - -### Usage - -Codex supports the same workflows as Zed's first-party agent. Add context by @-mentioning files or symbols. - -> Some agent panel features are not yet available with Codex: editing past messages, resuming threads from history, and checkpointing. - -## Add More Agents {#add-more-agents} - -### Via The ACP Registry - -[The ACP Registry](https://github.com/agentclientprotocol/registry) lets developers distribute ACP-compatible agents to any client that implements the protocol. Agents installed from the registry update automatically. - -At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods). - -#### Using it in Zed - -Use the {#action zed::AcpRegistry} command to quickly go to the ACP Registry page. -There's also a button ("Add Agent") that takes you there in the agent panel's configuration view. - -From there, you can click to install your preferred agent and it will become available right away in the `+` icon button in the agent panel. - -> If you installed the same agent through both the extension and the registry, the registry version takes precedence. - -### Custom Agents - -You can also add agents through your settings file ([how to edit](../configuring-zed.md#settings-files)) by specifying certain fields under `agent_servers`, like so: +Open [Agent Settings](./agent-settings.md), click `Add Agent`, and choose `Add Custom Agent`. Zed opens your settings file with an `agent_servers` entry. ```json [settings] { "agent_servers": { - "My Custom Agent": { + "my-agent": { "type": "custom", "command": "node", "args": ["~/projects/agent/index.js", "--acp"], @@ -213,133 +145,32 @@ You can also add agents through your settings file ([how to edit](../configuring } ``` -This can be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it. +Registry-installed agents can also have per-agent settings under `agent_servers.`. -It's also possible to customize environment variables for registry-installed agents like Claude Agent, Codex, and Gemini CLI by using their registry names (`claude-acp`, `codex-acp`, `gemini`) with `"type": "registry"` in your settings. +## Extension-Provided Agents {#extension-agents} + +Some extensions can provide agents. Registry installation is the primary path for common agents, but extension-provided agents still exist. + +For extension authoring, see [Agent Server Extensions](../extensions/agent-servers.md). ## Importing Threads {#importing-threads} -Zed can import existing threads from your external agent so they show up in your [Thread History](./agent-panel.md#multiple-threads) alongside the rest of your threads. This is useful when you've been working with Claude Agent, Codex, or another agent elsewhere and want to continue those conversations in Zed. +Zed can import existing threads from configured External Agents so they appear in your [Thread History](./agent-panel.md#multiple-threads) alongside the rest of your threads. -### Starting an Import +Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar}, then open Thread History by clicking the clock icon at the bottom of the sidebar or running {#action agents_sidebar::ToggleThreadHistory} from the Command Palette. Click **Import Threads**, choose the agents you want to import from, then click **Import Threads** again. -Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar} and open Thread History by clicking the clock icon at the bottom of the sidebar (or run {#action agents_sidebar::ToggleThreadHistory} from the Command Palette). Then click the **Import Threads** button (the download icon) in the Thread History toolbar. +Zed connects to each selected agent over ACP and adds sessions that are not already in your history. Imported threads are archived entries; open one to restore it and continue where you left off. -This opens the **Import External Agent Threads** dialog, which lists every external agent you have configured. Choose the agents you want to import from, then click **Import Threads**. Zed connects to each selected agent, retrieves its sessions over [ACP](https://agentclientprotocol.com), and adds any that aren't already in your history. When the import finishes, a notification reports how many threads were added. +Only configured External Agents appear in the import dialog. Sessions without an associated working directory are skipped, and re-importing is safe because threads already in your history are skipped. -### What to Expect +## MCP {#mcp} -- **The agent must be configured in Zed.** Only agents you've already set up (see the sections above and [Add More Agents](#add-more-agents)) appear in the dialog. -- **Imported threads are archived.** They're added to Thread History as archived entries; open one to restore it and continue where you left off. See [Managing Multiple Threads](./agent-panel.md#multiple-threads). -- **Only threads tied to a project folder are imported.** Sessions that an agent reports without an associated working directory are skipped. -- **Re-importing is safe.** Threads you've already imported are skipped, so you can run the import again later to pick up new sessions without creating duplicates. -- **Local and remote projects are supported.** Threads are gathered from the agents available in your current local and [remote](../remote-development.md) projects. +Zed-configured [MCP servers](./mcp.md) may be forwarded to External Agents over ACP. External Agents may also read their own native MCP configuration. -## Debugging Agents +If an MCP tool does not appear in an External Agent, check both Zed's MCP server configuration and the agent's native MCP configuration. -When using external agents in Zed, you can access the debug view via {#action dev::OpenAcpLogs} from the Command Palette. -This lets you see the messages being sent and received between Zed and the agent. +## Debugging {#debugging-agents} -![The debug view for ACP logs.](https://zed.dev/img/acp/acp-logs.webp) +Use {#action dev::OpenAcpLogs} from the Command Palette to inspect messages between Zed and an External Agent. -It's helpful to attach data from this view if you're opening issues about problems with external agents like Claude Agent, Codex, OpenCode, etc. - -## Configuration Boundaries {#configuration-boundaries} - -External agents run as separate processes that communicate with Zed via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). This creates important boundaries between Zed's configuration and the agent's native configuration. - -### What Zed Forwards to External Agents - -When you start an external agent thread, Zed sends: - -| Setting | How to Configure | -| --------------------- | --------------------------------------------------------------------- | -| Model selection | `agent_servers..default_model` in settings | -| Mode selection | `agent_servers..default_mode` in settings | -| Environment variables | `agent_servers..env` in settings | -| MCP servers | `context_servers` in settings (see [limitations](#mcp-server-access)) | -| Working directory | Automatically set to project root | - -**Not forwarded:** - -- [Profiles](./agent-panel.md#profiles) — profiles only apply to Zed's first-party agent -- [Tool permissions](./tool-permissions.md) settings — external agents request permissions at runtime via UI prompts -- Rules files — Zed's [rules system](./rules.md) only applies to Zed's first-party agent (external agents read their own rules files directly) - -### What External Agents Read Directly {#native-config} - -External agents run as CLI tools with full filesystem access. They read their own configuration files directly — Zed doesn't forward or block these. - -#### Claude Agent - -Claude Agent runs Claude Code under the hood, which reads its standard configuration: - -| Config | Read by Claude Agent? | -| ----------------------------------- | ----------------------------------------------------------------- | -| `~/.claude/` directory | Yes — Claude Code reads its own settings and memory | -| CLAUDE.md files | Yes — Claude Code reads these directly from the project | -| Skills | Yes — exposed via the Claude Agent SDK | -| MCP servers from Claude Code config | Yes — but Zed also forwards its own MCP servers via ACP | -| Hooks | No — [not supported](https://code.claude.com/docs/en/hooks-guide) | -| Authentication | Separate — you must authenticate via `/login` in Zed | - -> **Why separate authentication?** Zed isolates Claude Agent authentication to give you control over which account and billing method you use. - -#### Codex - -Codex runs the Codex CLI under the hood, which reads its standard configuration: - -| Config | Read by Codex? | -| ----------------------------- | ----------------------------------------------- | -| `~/.codex/config.toml` | Yes — Codex CLI reads its own config | -| MCP servers from Codex config | Yes — but Zed also forwards its own MCP servers | -| `CODEX_API_KEY` env var | Yes — inherited from your shell environment | -| `OPENAI_API_KEY` env var | Yes — inherited from your shell environment | -| ChatGPT OAuth login | Separate — you must re-authenticate in Zed | - -You can also pass environment variables through Zed settings: - -```json [settings] -{ - "agent_servers": { - "codex-acp": { - "type": "registry", - "env": { - "CODEX_API_KEY": "your-key", - "CUSTOM_PROVIDER_URL": "https://..." - } - } - } -} -``` - -### MCP Server Access {#mcp-server-access} - -MCP servers configured in Zed's `context_servers` are forwarded to Claude Agent and Codex via the ACP protocol. - -- **Local stdio-based MCP servers:** Work reliably -- **Remote MCP servers with OAuth:** May have issues ([#54410](https://github.com/zed-industries/zed/issues/54410)) - -External agents can access MCP servers from two sources: Zed's `context_servers` (forwarded via ACP) and their own native configuration files (`~/.claude/`, `~/.codex/config.toml`). - -For more on configuring MCP servers, see [Model Context Protocol](./mcp.md). - -### Troubleshooting {#troubleshooting} - -**"I enabled MCP tools in Zed but the agent can't see them"** - -1. Verify the MCP server is enabled in `context_servers` settings -2. For remote MCP servers with OAuth, this is a [known issue](https://github.com/zed-industries/zed/issues/54410) — try local stdio-based servers instead -3. Open {#action dev::OpenAcpLogs} from the Command Palette to debug - -**"My existing Claude Code / Codex setup isn't working in Zed"** - -External agents read their own config files, but authentication is handled separately: - -1. Re-authenticate via `/login` (Claude Agent) or the authentication prompt (Codex) -2. Your existing MCP servers and settings from `~/.claude/` or `~/.codex/config.toml` should work -3. You can also configure additional settings via `agent_servers..env` in Zed - -**"Profiles don't affect my external agent"** - -Correct — [profiles](./agent-panel.md#profiles) only apply to Zed's first-party agent. External agents have their own tool sets and don't use Zed's profile system. +Include ACP logs when reporting issues with External Agents. diff --git a/docs/src/ai/inline-assistant.md b/docs/src/ai/inline-assistant.md index f560451dbb..4d1d7c3985 100644 --- a/docs/src/ai/inline-assistant.md +++ b/docs/src/ai/inline-assistant.md @@ -7,28 +7,27 @@ description: Transform code inline with AI in Zed. Send selections to any LLM fo ## Usage Overview -Use {#kb assistant::InlineAssist} to open the Inline Assistant in editors, the rules library, channel notes, and the terminal panel. +Use {#kb assistant::InlineAssist} to open the Inline Assistant in editors, channel notes, and the terminal panel. The Inline Assistant sends your current selection (or line) to a language model and replaces it with the response. ## Getting Started -If you're using the Inline Assistant for the first time, you need to have at least one LLM provider or external agent configured. +If you're using the Inline Assistant for the first time, you need to have at least one [LLM provider](./llm-providers.md) configured. You can do that by: -1. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models -2. [using your own API keys](./llm-providers.md#use-your-own-keys), either from model providers like Anthropic or model gateways like OpenRouter. +1. [using Zed-hosted models](../account/zed-hosted-models.md), so you have access to models billed through Zed +2. [using API access](./use-api-access.md), either from model providers like Anthropic or model gateways like OpenRouter. If you have already set up an LLM provider to interact with [the Agent Panel](./agent-panel.md#getting-started), then that will also work for the Inline Assistant. -> Unlike the Agent Panel, though, the only exception at the moment is [external agents](./external-agents.md). -> They currently can't be used for generating changes with the Inline Assistant. +[External Agents](./external-agents.md) run in agent threads, but they are not available for Inline Assistant generations. The Inline Assistant uses Zed-configured [LLM providers](./llm-providers.md), including Zed-hosted models, provider API keys, gateways, local models, and supported subscriptions. ## Adding Context You can add context in the Inline Assistant the same way you can in [the Agent Panel](./agent-panel.md#adding-context): -- @-mention files, directories, past threads, rules, and symbols +- @-mention files, directories, past threads, instruction files, and symbols - paste images that are copied on your clipboard You can also create a thread in the Agent Panel, then reference it with `@thread` in the Inline Assistant. This lets you refine a specific change from a larger thread without re-explaining context. diff --git a/docs/src/ai/instructions.md b/docs/src/ai/instructions.md new file mode 100644 index 0000000000..0f25bcae7b --- /dev/null +++ b/docs/src/ai/instructions.md @@ -0,0 +1,66 @@ +--- +title: Agent Instructions - Zed +description: Configure always-on personal and project instructions for Zed Agent with AGENTS.md and compatible project instruction files. +--- + +# Instructions + +Instructions are always-on context for the Zed Agent. Use instructions for persistent guidance that should apply to every relevant agent interaction. + +Use [Skills](./skills.md) instead when you want reusable task instructions that can be invoked by name. + +Zed supports [`AGENTS.md`](https://agents.md/) as the primary instruction file for personal and project-level agent guidance. + +## Personal Instructions {#personal-instructions} + +Personal instructions apply to every project you open with the Zed Agent. + +Create or edit: + +```text +~/.config/zed/AGENTS.md +``` + +On Windows, the equivalent file is under `%APPDATA%\Zed\AGENTS.md`. + +## Project Instructions {#project-instructions} + +Project instruction files apply to the current project. Zed uses the first matching file in this list: + +- `.rules` +- `.cursorrules` +- `.windsurfrules` +- `.clinerules` +- `.github/copilot-instructions.md` +- `AGENT.md` +- [`AGENTS.md`](https://agents.md/) +- `CLAUDE.md` +- `GEMINI.md` + +Project instructions override personal `AGENTS.md` when they conflict. + +## Instruction File Support {#support} + +| File | Zed Agent | External Agents | Terminal Threads | +| --------------------------------- | ------------------------------------------------------ | --------------------- | -------------------------------- | +| `~/.config/zed/AGENTS.md` | Loaded as personal instructions | Not generally used | Not used unless the CLI reads it | +| Project `AGENTS.md` | Loaded as project instructions | Depends on the agent | Depends on the CLI | +| `CLAUDE.md` | Loaded as compatible project instructions by Zed Agent | Claude reads natively | Claude Code CLI reads natively | +| `.github/copilot-instructions.md` | Loaded as compatible project instructions by Zed Agent | Depends on the agent | Depends on the CLI | + +External Agents and Terminal Threads may read their own native instruction files directly. Do not assume Zed's instruction loader controls those agents. + +## Instructions vs. Skills {#instructions-vs-skills} + +| Use | Best for | Example | +| ------------ | ----------------------- | ----------------------------------------------------------- | +| Instructions | Always-on guidance | Repository conventions, preferred tone, project constraints | +| Skills | Reusable task workflows | Code review checklist, release workflow, migration helper | + +## Migrating from Rules {#migrating-from-rules} + +Rules have been replaced by Skills and Instructions: + +- reusable, on-demand Rules become [Skills](./skills.md) +- default, always-on Rules become personal `AGENTS.md` +- project `.rules` files remain supported as compatibility project instruction files diff --git a/docs/src/ai/llm-providers.md b/docs/src/ai/llm-providers.md index 2185e5113b..d623581ca1 100644 --- a/docs/src/ai/llm-providers.md +++ b/docs/src/ai/llm-providers.md @@ -1,924 +1,35 @@ --- -title: LLM Providers - Use Your Own API Keys in Zed -description: Bring your own API keys to Zed. Set up Anthropic, OpenAI, Google AI, Ollama, DeepSeek, Mistral, OpenRouter, Vercel AI Gateway, and more. +title: LLM Providers - Zed +description: Choose how Zed gets language models: Zed-hosted models, API access, subscriptions, gateways, or local models. --- # LLM Providers -To use AI in Zed, you need to have at least one large language model provider set up. Once configured, providers are available in the [Agent Panel](./agent-panel.md) and [Inline Assistant](./inline-assistant.md). +Use this page to choose which models power [the Zed Agent](./zed-agent.md) and +other Zed-owned AI features, including [Inline Assistant](./inline-assistant.md), +Git commit generation, thread summaries, and similar model-backed features. -You can do that by either subscribing to [one of Zed's plans](./plans-and-usage.md), or by using API keys you already have for the supported providers. For general AI setup, see [Configuration](./configuration.md). +Model access paths do not configure [External Agents](./external-agents.md) or +[Terminal Threads](./terminal-threads.md). External Agents and Terminal Threads +usually own their own model access, auth, and configuration. -## Use Your Own Keys {#use-your-own-keys} +## Choose a Model Access Path {#choose-a-model-access-path} -If you already have an API key for a provider like Anthropic or OpenAI, you can add it to Zed. No Zed subscription required. +| Model access path | Best when | Source of truth | +| ----------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------- | +| [Use Zed-Hosted Models](../account/zed-hosted-models.md) | You want models billed through Zed | Account & Billing > Zed-Hosted Models | +| [Use API Access](./use-api-access.md) | You have provider API access, credits, or usage billing | Use API Access | +| [Use an Existing Subscription](./use-an-existing-subscription.md) | You already pay for ChatGPT, Claude, Copilot, or another subscription | Use an Existing Subscription | +| [Use a Gateway](./use-a-gateway.md) | You route through OpenRouter, Bedrock, Vercel, or a similar platform | Use a Gateway | +| [Use a Local Model](./use-a-local-model.md) | You run models locally or self-hosted | Use a Local Model | -To add an existing API key to a given provider, go to the Agent Panel settings ({#action agent::OpenSettings}), look for the desired provider, paste the key into the input, and hit enter. +Use the setup pages for provider-specific details. See [Agents](./agents.md) for +the difference between the Zed Agent, External Agents, and Terminal Threads. -> Note: API keys are _not_ stored as plain text in your settings file, but rather in your OS's secure credential storage. +## Edit Prediction {#edit-prediction} -## Supported Providers +[Edit Prediction](./edit-prediction.md) has its own provider setup under `edit_predictions`. LLM providers on this page apply to model-backed Zed AI features such as Zed Agent, Inline Assistant, Git commit generation, and thread summaries. -Zed supports these providers with your own API keys: +## OpenAI-Compatible Providers {#openai-api-compatible} -- [Amazon Bedrock](#amazon-bedrock) -- [Anthropic](#anthropic) -- [ChatGPT Subscription](#chatgpt-subscription) -- [DeepSeek](#deepseek) -- [GitHub Copilot Chat](#github-copilot-chat) -- [Google AI](#google-ai) -- [LM Studio](#lmstudio) -- [Mistral](#mistral) -- [Ollama](#ollama) -- [OpenAI](#openai) -- [OpenAI API Compatible](#openai-api-compatible) -- [OpenCode](#opencode) -- [OpenRouter](#openrouter) -- [Vercel AI Gateway](#vercel-ai-gateway) -- [xAI](#xai) - -### Custom Headers {#custom-headers} - -You can attach extra HTTP headers to every request Zed makes to supported HTTP-based providers. This is useful in corporate environments, or for observability tooling. - -Configure them via the `language_models..custom_headers` settings key: - -```json [settings] -{ - "language_models": { - "openai": { - "custom_headers": { - "Fancy-Auth": "Bearer ", - "X-My-Tag": "zed" - } - } - } -} -``` - -`custom_headers` is supported by Amazon Bedrock, Anthropic, DeepSeek, Google AI, LM Studio, Mistral, Ollama, OpenAI, OpenAI API Compatible providers, OpenCode, OpenRouter, Vercel AI Gateway, and xAI. Headers managed by Zed for each provider, such as `Authorization`, `Content-Type`, `Accept`, and provider-specific authentication headers, are ignored with a warning if you try to override them. - -### Amazon Bedrock {#amazon-bedrock} - -> Supports tool use with models that support streaming tool use. -> More details can be found in the [Amazon Bedrock's Tool Use documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html). - -To use Amazon Bedrock's models, an AWS authentication is required. -Ensure your credentials have the following permissions set up: - -- `bedrock:InvokeModelWithResponseStream` -- `bedrock:InvokeModel` - -Your IAM policy should look similar to: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "bedrock:InvokeModel", - "bedrock:InvokeModelWithResponseStream" - ], - "Resource": "*" - } - ] -} -``` - -With that done, choose one of the three authentication methods: - -#### Authentication via Named Profile (Recommended) - -1. Ensure you have the AWS CLI installed and configured with a named profile -2. Open your settings file ({#action zed::OpenSettingsFile}) and include the `bedrock` key under `language_models` with the following settings: - ```json [settings] - { - "language_models": { - "bedrock": { - "authentication_method": "named_profile", - "region": "your-aws-region", - "profile": "your-profile-name" - } - } - } - ``` - -#### Authentication via Static Credentials - -While it's possible to configure through the Agent Panel settings UI by entering your AWS access key and secret directly, we recommend using named profiles instead for better security practices. -To do this: - -1. Create an IAM User in the [IAM Console](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/users). -2. Create security credentials for that User, save them and keep them secure. -3. Open the Agent Configuration with ({#action agent::OpenSettings}) and go to the Amazon Bedrock section -4. Copy the credentials from Step 2 into the respective **Access Key ID**, **Secret Access Key**, and **Region** fields. - -#### Authentication via Bedrock API Key - -Amazon Bedrock also supports [API Keys](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-use.html), which authenticate directly without requiring IAM users or named profiles. - -1. Create an API Key in the [Amazon Bedrock Console](https://console.aws.amazon.com/bedrock/) -2. Open the Agent Configuration with ({#action agent::OpenSettings}) and go to the Amazon Bedrock section -3. Enter your Bedrock API key in the **API Key** field and select your **Region** - -```json [settings] -{ - "language_models": { - "bedrock": { - "authentication_method": "api_key", - "region": "your-aws-region" - } - } -} -``` - -The API key itself is stored securely in your OS keychain, not in your settings file. - -#### Cross-Region Inference - -The Zed implementation of Amazon Bedrock uses [Cross-Region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) to improve availability and throughput. -With Cross-Region inference, you can distribute traffic across multiple AWS Regions, enabling higher throughput. - -##### Regional vs Global Inference Profiles - -Bedrock supports two types of cross-region inference profiles: - -- **Regional profiles** (default): Route requests within a specific geography (US, EU, APAC). For example, `us-east-1` uses the `us.*` profile which routes across `us-east-1`, `us-east-2`, and `us-west-2`. -- **Global profiles**: Route requests across all commercial AWS Regions for maximum availability and performance. - -By default, Zed uses **regional profiles** which keep your data within the same geography. You can opt into global profiles by adding `"allow_global": true` to your Bedrock configuration: - -```json [settings] -{ - "language_models": { - "bedrock": { - "authentication_method": "named_profile", - "region": "your-aws-region", - "profile": "your-profile-name", - "allow_global": true - } - } -} -``` - -**Note:** Only select newer models support global inference profiles. See the [AWS Bedrock supported models documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html#inference-profiles-support-system) for the current list of models that support global inference. If you encounter availability issues with a model in your region, enabling `allow_global` may resolve them. - -Although the data remains stored only in the source Region, your input prompts and output results might move outside of your source Region during cross-Region inference. -All data will be transmitted encrypted across Amazon's secure network. - -We will support Cross-Region inference for each of the models on a best-effort basis, please refer to the [Cross-Region Inference method Code](https://github.com/zed-industries/zed/blob/main/crates/bedrock/src/models.rs#L297). - -For the most up-to-date supported regions and models, refer to the [Supported Models and Regions for Cross Region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html). - -#### Image Support {#bedrock-image-support} - -Bedrock models that support vision (Claude 3 and later, Amazon Nova Pro and Lite, Meta Llama 3.2 Vision models, Mistral Pixtral) can receive images in conversations and tool results. - -#### Guardrails {#bedrock-guardrails} - -Some AWS environments enforce IAM policies that require a guardrail to be specified on every Bedrock API call. To apply a guardrail to all Bedrock requests, add `guardrail_identifier` to your Bedrock configuration: - -```json [settings] -{ - "language_models": { - "bedrock": { - "guardrail_identifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123", - "guardrail_version": "DRAFT" - } - } -} -``` - -- `guardrail_identifier`: The ARN or ID of the guardrail to apply to every request. -- `guardrail_version`: The version of the guardrail to use. Defaults to `"DRAFT"` if omitted. - -> **Note**: For more information, refer to the [AWS Bedrock Guardrails documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html). - -### Anthropic {#anthropic} - -You can use Anthropic models by choosing them via the model dropdown in the Agent Panel. - -1. Sign up for Anthropic and [create an API key](https://console.anthropic.com/settings/keys) -2. Make sure that your Anthropic account has credits -3. Open the settings view ({#action agent::OpenSettings}) and go to the Anthropic section -4. Enter your Anthropic API key - -Even if you pay for Claude Pro, you will still have to [pay for additional credits](https://console.anthropic.com/settings/plans) to use it via the API. - -Zed will also use the `ANTHROPIC_API_KEY` environment variable if it's defined. - -#### Custom Models {#anthropic-custom-models} - -You can add custom models to the Anthropic provider by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "anthropic": { - "available_models": [ - { - "name": "claude-3-5-sonnet-20240620", - "display_name": "Sonnet 2024-June", - "max_tokens": 128000, - "max_output_tokens": 2560, - "tool_override": "some-model-that-supports-toolcalling" - } - ] - } - } -} -``` - -Custom models will be listed in the model dropdown in the Agent Panel. - -You can configure a model to use [extended thinking](https://docs.anthropic.com/en/docs/about-claude/models/extended-thinking-models) (if it supports it) by changing the mode in your model's configuration to `thinking`, for example: - -```json -{ - "name": "claude-sonnet-4-latest", - "display_name": "claude-sonnet-4-thinking", - "max_tokens": 200000, - "mode": { - "type": "thinking", - "budget_tokens": 4096 - } -} -``` - -### ChatGPT Subscription {#chatgpt-subscription} - -Use your existing ChatGPT Plus or Pro subscription to access OpenAI models directly in Zed — no separate API key required. - -1. Open the settings view ({#action agent::OpenSettings}) and go to the ChatGPT Subscription section -2. Click **Sign in** and complete the OpenAI authentication in your browser -3. Once signed in, models appear in the model dropdown, including GPT-5.5 and GPT-5.3 Codex - -To sign out, click **Sign Out** in the ChatGPT Subscription settings. - -> **Note:** Model availability depends on your ChatGPT subscription tier. Some models may require ChatGPT Pro. - -### DeepSeek {#deepseek} - -1. Visit the DeepSeek platform and [create an API key](https://platform.deepseek.com/api_keys) -2. Open the settings view ({#action agent::OpenSettings}) and go to the DeepSeek section -3. Enter your DeepSeek API key - -The DeepSeek API key will be saved in your keychain. - -Zed will also use the `DEEPSEEK_API_KEY` environment variable if it's defined. - -#### Custom Models {#deepseek-custom-models} - -The Zed agent comes pre-configured to use DeepSeek V4 Flash and DeepSeek V4 Pro. -If you wish to use alternate models or customize the API endpoint, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "deepseek": { - "api_url": "https://api.deepseek.com", - "available_models": [ - { - "name": "deepseek-v4-flash", - "display_name": "DeepSeek V4 Flash", - "max_tokens": 1000000, - "max_output_tokens": 384000 - }, - { - "name": "deepseek-v4-pro", - "display_name": "DeepSeek V4 Pro", - "max_tokens": 1000000, - "max_output_tokens": 384000 - } - ] - } - } -} -``` - -Custom models will be listed in the model dropdown in the Agent Panel. -You can also modify the `api_url` to use a custom endpoint if needed. - -### GitHub Copilot Chat {#github-copilot-chat} - -You can use GitHub Copilot Chat with the Zed agent by choosing it via the model dropdown in the Agent Panel. - -1. Open the settings view ({#action agent::OpenSettings}) and go to the GitHub Copilot Chat section -2. Click on `Sign in to use GitHub Copilot`, follow the steps shown in the modal. - -Alternatively, you can provide an OAuth token via the `GH_COPILOT_TOKEN` environment variable. - -> **Note**: If you don't see specific models in the dropdown, you may need to enable them in your [GitHub Copilot settings](https://github.com/settings/copilot/features). - -To use Copilot Enterprise with Zed (for both agent and completions), you must configure your enterprise endpoint as described in [Configuring GitHub Copilot Enterprise](./edit-prediction.md#using-github-copilot-enterprise). - -### Google AI {#google-ai} - -You can use Gemini models with the Zed agent by choosing it via the model dropdown in the Agent Panel. - -1. Go to the Google AI Studio site and [create an API key](https://aistudio.google.com/app/apikey). -2. Open the settings view ({#action agent::OpenSettings}) and go to the Google AI section -3. Enter your Google AI API key and press enter. - -The Google AI API key will be saved in your keychain. - -Zed will also use the `GEMINI_API_KEY` environment variable if it's defined. See [Using Gemini API keys](https://ai.google.dev/gemini-api/docs/api-key) in the Gemini docs for more. - -#### Custom Models {#google-ai-custom-models} - -By default, Zed will use `stable` versions of models, but you can use specific versions of models, including [experimental models](https://ai.google.dev/gemini-api/docs/models/experimental-models). You can configure a model to use [thinking mode](https://ai.google.dev/gemini-api/docs/thinking) (if it supports it) by adding a `mode` configuration to your model. This is useful for controlling reasoning token usage and response speed. If not specified, Gemini will automatically choose the thinking budget. - -Here is an example of a custom Google AI model you could add to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "google": { - "available_models": [ - { - "name": "gemini-3.1-pro-preview", - "display_name": "Gemini 3.1 Pro", - "max_tokens": 1000000, - "mode": { - "type": "thinking", - "budget_tokens": 24000 - } - }, - { - "name": "gemini-3-flash-preview", - "display_name": "Gemini 3 Flash (Thinking)", - "max_tokens": 1000000, - "mode": { - "type": "thinking", - "budget_tokens": 24000 - } - } - ] - } - } -} -``` - -Custom models will be listed in the model dropdown in the Agent Panel. - -### LM Studio {#lmstudio} - -1. Download and install [the latest version of LM Studio](https://lmstudio.ai/download) -2. In the app press `cmd/ctrl-shift-m` and download at least one model (e.g., qwen2.5-coder-7b). Alternatively, you can get models via the LM Studio CLI: - - ```sh - lms get qwen2.5-coder-7b - ``` - -3. Make sure the LM Studio API server is running by executing: - - ```sh - lms server start - ``` - -Tip: Set [LM Studio as a login item](https://lmstudio.ai/docs/advanced/headless#run-the-llm-service-on-machine-login) to automate running the LM Studio server. - -### Mistral {#mistral} - -1. Visit the Mistral platform and [create an API key](https://console.mistral.ai/api-keys/) -2. Open the configuration view ({#action agent::OpenSettings}) and navigate to the Mistral section -3. Enter your Mistral API key - -The Mistral API key will be saved in your keychain. - -Zed will also use the `MISTRAL_API_KEY` environment variable if it's defined. - -#### Custom Models {#mistral-custom-models} - -The Zed agent comes pre-configured to use the latest version for common Mistral models (Large, Medium, Small, Codestral, Devstral, and others). -All the default models support tool use. -If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "mistral": { - "api_url": "https://api.mistral.ai/v1", - "available_models": [ - { - "name": "mistral-tiny-latest", - "display_name": "Mistral Tiny", - "max_tokens": 32000, - "max_output_tokens": 4096, - "max_completion_tokens": 1024, - "supports_tools": true, - "supports_images": false - } - ] - } - } -} -``` - -Custom models will be listed in the model dropdown in the Agent Panel. - -### Ollama {#ollama} - -Download and install Ollama from [ollama.com/download](https://ollama.com/download) (Linux or macOS) and ensure it's running with `ollama --version`. - -1. Download one of the [available models](https://ollama.com/models), for example, for `mistral`: - - ```sh - ollama pull mistral - ``` - -2. Make sure that the Ollama server is running. You can start it either via running Ollama.app (macOS) or launching: - - ```sh - ollama serve - ``` - -3. In the Agent Panel, select one of the Ollama models using the model dropdown. - -#### Ollama Autodiscovery - -Zed will automatically discover models that Ollama has pulled. You can turn this off by setting -the `auto_discover` field in the Ollama settings. If you do this, you should manually specify which -models are available. - -```json [settings] -{ - "language_models": { - "ollama": { - "api_url": "http://localhost:11434", - "auto_discover": false, - "available_models": [ - { - "name": "qwen2.5-coder", - "display_name": "qwen 2.5 coder", - "max_tokens": 32768, - "supports_tools": true, - "supports_thinking": true, - "supports_images": true - } - ] - } - } -} -``` - -#### Ollama Context Length {#ollama-context} - -Zed API requests to Ollama include the context length as the `num_ctx` parameter. By default, Zed uses a context length of `4096` tokens for all Ollama models. - -> **Note**: Token counts displayed in the Agent Panel are only estimates and will differ from the model's native tokenizer. - -You can set a context length for all Ollama models using the `context_window` setting. This can also be configured in the Ollama provider settings UI: - -```json [settings] -{ - "language_models": { - "ollama": { - "context_window": 8192 - } - } -} -``` - -Alternatively, you can configure the context length per-model using the `max_tokens` field in `available_models`: - -```json [settings] -{ - "language_models": { - "ollama": { - "api_url": "http://localhost:11434", - "available_models": [ - { - "name": "qwen2.5-coder", - "display_name": "qwen 2.5 coder 32K", - "max_tokens": 32768, - "supports_tools": true, - "supports_thinking": true, - "supports_images": true - } - ] - } - } -} -``` - -> **Note**: If `context_window` is set, it overrides any per-model `max_tokens` values. - -If you specify a context length that is too large for your hardware, Ollama will log an error. -You can watch these logs by running: `tail -f ~/.ollama/logs/ollama.log` (macOS) or `journalctl -u ollama -f` (Linux). -Depending on the memory available on your machine, you may need to adjust the context length to a smaller value. - -You may also optionally specify a value for `keep_alive` for each available model. -This can be an integer (seconds) or alternatively a string duration like "5m", "10m", "1h", "1d", etc. -For example, `"keep_alive": "120s"` will allow the remote server to unload the model (freeing up GPU VRAM) after 120 seconds. - -The `supports_tools` option controls whether the model will use additional tools. -If the model is tagged with `tools` in the Ollama catalog, this option should be supplied, and the built-in profiles `Ask` and `Write` can be used. -If the model is not tagged with `tools` in the Ollama catalog, this option can still be supplied with the value `true`; however, be aware that only the `Minimal` built-in profile will work. - -The `supports_thinking` option controls whether the model will perform an explicit "thinking" (reasoning) pass before producing its final answer. -If the model is tagged with `thinking` in the Ollama catalog, set this option and you can use it in Zed. - -The `supports_images` option enables the model's vision capabilities, allowing it to process images included in the conversation context. -If the model is tagged with `vision` in the Ollama catalog, set this option and you can use it in Zed. - -#### Ollama Authentication - -In addition to running Ollama on your own hardware, which generally does not require authentication, Zed also supports connecting to remote Ollama instances. API keys are required for authentication. - -One such service is [Ollama Turbo](https://ollama.com/turbo). To configure Zed to use Ollama Turbo: - -1. Sign in to your Ollama account and subscribe to Ollama Turbo -2. Visit [ollama.com/settings/keys](https://ollama.com/settings/keys) and create an API key -3. Open the settings view ({#action agent::OpenSettings}) and go to the Ollama section -4. Paste your API key and press enter. -5. For the API URL enter `https://ollama.com` - -Zed will also use the `OLLAMA_API_KEY` environment variable if defined. - -### OpenAI {#openai} - -1. Visit the OpenAI platform and [create an API key](https://platform.openai.com/account/api-keys) -2. Make sure that your OpenAI account has credits -3. Open the settings view ({#action agent::OpenSettings}) and go to the OpenAI section -4. Enter your OpenAI API key - -The OpenAI API key will be saved in your keychain. - -Zed will also use the `OPENAI_API_KEY` environment variable if it's defined. - -#### Custom Models {#openai-custom-models} - -The Zed agent comes pre-configured to use the latest version for common OpenAI models (GPT-5.2, GPT-5 mini, GPT-5.2 Codex, and others). -To use alternate models, perhaps a preview release, or if you wish to control the request parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "openai": { - "available_models": [ - { - "name": "gpt-5.2", - "display_name": "gpt-5.2 high", - "reasoning_effort": "high", - "max_tokens": 272000, - "max_completion_tokens": 20000 - }, - { - "name": "gpt-5-nano", - "display_name": "GPT-5 Nano", - "max_tokens": 400000 - }, - { - "name": "gpt-5.2-codex", - "display_name": "GPT-5.2 Codex", - "max_tokens": 128000, - "capabilities": { - "chat_completions": false - } - } - ] - } - } -} -``` - -You must provide the model's context window in the `max_tokens` parameter; this can be found in the [OpenAI model documentation](https://platform.openai.com/docs/models). - -For reasoning-focused models, set `max_completion_tokens` as well to avoid incurring high reasoning token costs. - -If a model does not support the `/chat/completions` endpoint (for example `gpt-5.2-codex`), disable it by setting `capabilities.chat_completions` to `false`. Zed will use the Responses endpoint instead. - -Custom models will be listed in the model dropdown in the Agent Panel. - -### OpenAI API Compatible {#openai-api-compatible} - -Zed supports using [OpenAI compatible APIs](https://platform.openai.com/docs/api-reference/chat) by specifying a custom `api_url` and `available_models` for the OpenAI provider. -This is useful for connecting to other hosted services (like Together AI, Anyscale, etc.) or local models. - -You can add a custom, OpenAI-compatible model either via the UI or by editing your settings file. - -To do it via the UI, go to the Agent Panel settings ({#action agent::OpenSettings}) and look for the "Add Provider" button to the right of the "LLM Providers" section title. -Then, fill up the input fields available in the modal. - -To do it via your settings file ([how to edit](../configuring-zed.md#settings-files)), add the following snippet under `language_models`: - -```json [settings] -{ - "language_models": { - "openai_compatible": { - // Using Together AI as an example - "Together AI": { - "api_url": "https://api.together.xyz/v1", - "available_models": [ - { - "name": "mistralai/Mixtral-8x7B-Instruct-v0.1", - "display_name": "Together Mixtral 8x7B", - "max_tokens": 32768, - "capabilities": { - "tools": true, - "images": false, - "parallel_tool_calls": false, - "prompt_cache_key": false - } - } - ] - } - } - } -} -``` - -By default, OpenAI-compatible models inherit the following capabilities: - -- `tools`: true (supports tool/function calling) -- `images`: false (does not support image inputs) -- `parallel_tool_calls`: false (does not support `parallel_tool_calls` parameter) -- `prompt_cache_key`: false (does not support `prompt_cache_key` parameter) -- `chat_completions`: true (calls the `/chat/completions` endpoint) -- `interleaved_reasoning`: false (thinking tokens are sent inline in message text; set to true to send them as a dedicated `reasoning_content` field for models that expect it) - -If a provider exposes models that only work with the Responses API, set `chat_completions` to `false` for those entries. Zed uses the Responses endpoint for these models. - -Note that LLM API keys aren't stored in your settings file. -So, ensure you have it set in your environment variables (`_API_KEY=`) so your settings can pick it up. In the example above, it would be `TOGETHER_AI_API_KEY=`. - -### OpenCode {#opencode} - -OpenCode offers multiple ways to access AI models: - -- [OpenCode Zen](https://opencode.ai/zen/): a pay-as-you-go subscription with access to a large number of tested and verified models -- [OpenCode Zen Free](https://opencode.ai/docs/zen/#pricing): free access to a limited set of models, with data and feedback collected to improve the models -- [OpenCode Go](https://opencode.ai/go): a low-cost monthly subscription with access to a validated set of open coding models - -1. Visit [OpenCode Console](https://opencode.ai/auth) and create an account -2. Free models are available without payment. To use Zen or Go models, make sure you have enough credits or an active subscription -3. Generate an API key from the "API Keys" section in the OpenCode Console -4. Open the settings view ({#action agent::OpenSettings}) and go to the OpenCode section -5. Enter your OpenCode API key - -The OpenCode API key will be saved in your keychain. - -Zed will also use the `OPENCODE_API_KEY` environment variable if it's defined. - -By default, models from all subscription types are shown. Optionally, you can hide subscriptions that are not relevant to you by clicking the toggles or by adding the following to your settings: - -```json [settings] -{ - "language_models": { - "opencode": { - "show_zen_models": true, - "show_go_models": false, - "show_free_models": false - } - } -} -``` - -**Note:** Zed only bundles configuration for long-term OpenCode Free models! Free models that are only available for a limited time are not included in Zed. To use such models, create a Custom Model using the configuration settings published on [the OpenCode website](https://opencode.ai/docs/zen#pricing) and on [models.dev](https://github.com/anomalyco/models.dev/tree/dev/providers/opencode/models). - -#### Custom Models {#opencode-custom-models} - -The Zed agent comes pre-configured with OpenCode models. If you wish to use newer models or models with custom endpoints, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "opencode": { - "available_models": [ - { - "name": "my-custom-model", - "display_name": "My Custom Model", - "max_tokens": 123456, - "max_output_tokens": 98765, - "protocol": "openai_chat", - "reasoning_effort_levels": ["low", "medium", "high"], - "interleaved_reasoning": false, - "subscription": "go", - "custom_model_api_url": "https://example.com/zen" - } - ] - } - } -} -``` - -The available configuration options for custom models are: - -- `name` (required): model id used by OpenCode, for example `glm-9000` -- `display_name` (optional): human-readable model name shown in the UI, for example `Custom GLM 9000` -- `max_tokens` (required): maximum model context window size, for example `1000000` -- `max_output_tokens` (optional): maximum tokens the model can generate, for example `64000` -- `protocol` (required): model API protocol, one of `"anthropic"`, `"openai_responses"`, `"openai_chat"`, or `"google"` -- `reasoning_effort_levels` (optional): list of supported reasoning effort levels, for example `["low", "medium", "high"]`. The latest value in the list is used as the default -- `interleaved_reasoning` (optional, default `false`): if thinking tokens are sent as a dedicated `reasoning_content` field (`true`) or inline in message text (`false`). Applies only when using the `openai_chat` protocol -- `subscription` (optional): `"zen"`, `"go"`, or `"free"` (defaults to `"zen"`) -- `custom_model_api_url` (optional): custom API base URL to use instead of the default OpenCode API - -Custom models will be listed in the model dropdown in the Agent Panel. - -### OpenRouter {#openrouter} - -OpenRouter provides access to multiple AI models through a single API. It supports tool use for compatible models. - -1. Visit [OpenRouter](https://openrouter.ai) and create an account -2. Generate an API key from your [OpenRouter keys page](https://openrouter.ai/keys) -3. Open the settings view ({#action agent::OpenSettings}) and go to the OpenRouter section -4. Enter your OpenRouter API key - -The OpenRouter API key will be saved in your keychain. - -Zed will also use the `OPENROUTER_API_KEY` environment variable if it's defined. - -When using OpenRouter as your assistant provider, you must explicitly select a model in your settings. OpenRouter no longer provides a default model selection. - -Configure your preferred OpenRouter model in `settings.json`: - -```json [settings] -{ - "agent": { - "default_model": { - "provider": "openrouter", - "model": "openrouter/auto" - } - } -} -``` - -The `openrouter/auto` model automatically routes your requests to the most appropriate available model. You can also specify any model available through OpenRouter's API. - -#### Custom Models {#openrouter-custom-models} - -You can add custom models to the OpenRouter provider by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "open_router": { - "api_url": "https://openrouter.ai/api/v1", - "available_models": [ - { - "name": "google/gemini-2.0-flash-thinking-exp", - "display_name": "Gemini 2.0 Flash (Thinking)", - "max_tokens": 200000, - "max_output_tokens": 8192, - "supports_tools": true, - "supports_images": true, - "mode": { - "type": "thinking", - "budget_tokens": 8000 - } - } - ] - } - } -} -``` - -The available configuration options for each model are: - -- `name` (required): The model identifier used by OpenRouter -- `display_name` (optional): A human-readable name shown in the UI -- `max_tokens` (required): The model's context window size -- `max_output_tokens` (optional): Maximum tokens the model can generate -- `max_completion_tokens` (optional): Maximum completion tokens -- `supports_tools` (optional): Whether the model supports tool/function calling -- `supports_images` (optional): Whether the model supports image inputs -- `mode` (optional): Special mode configuration for thinking models - -You can find available models and their specifications on the [OpenRouter models page](https://openrouter.ai/models). - -Custom models will be listed in the model dropdown in the Agent Panel. - -#### Provider Routing - -You can optionally control how OpenRouter routes a given custom model request among underlying upstream providers via the `provider` object on each model entry. - -Supported fields (all optional): - -- `order`: Array of provider slugs to try first, in order (e.g. `["anthropic", "openai"]`) -- `allow_fallbacks` (default: `true`): Whether fallback providers may be used if preferred ones are unavailable -- `require_parameters` (default: `false`): Only use providers that support every parameter you supplied -- `data_collection` (default: `allow`): `"allow"` or `"disallow"` (controls use of providers that may store data) -- `only`: Whitelist of provider slugs allowed for this request -- `ignore`: Provider slugs to skip -- `quantizations`: Restrict to specific quantization variants (e.g. `["int4","int8"]`) -- `sort`: Sort strategy for candidate providers (e.g. `"price"` or `"throughput"`) - -Example adding routing preferences to a model: - -```json [settings] -{ - "language_models": { - "open_router": { - "api_url": "https://openrouter.ai/api/v1", - "available_models": [ - { - "name": "openrouter/auto", - "display_name": "Auto Router (Tools Preferred)", - "max_tokens": 2000000, - "supports_tools": true, - "provider": { - "order": ["anthropic", "openai"], - "allow_fallbacks": true, - "require_parameters": true, - "only": ["anthropic", "openai", "google"], - "ignore": ["cohere"], - "quantizations": ["int8"], - "sort": "price", - "data_collection": "allow" - } - } - ] - } - } -} -``` - -These routing controls let you fine‑tune cost, capability, and reliability trade‑offs without changing the model name you select in the UI. - -### Vercel AI Gateway {#vercel-ai-gateway} - -[Vercel AI Gateway](https://vercel.com/ai-gateway) provides access to many models through a single OpenAI-compatible endpoint. - -1. Create an API key from your [Vercel AI Gateway keys page](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys&title=Go+to+AI+Gateway) -2. Open the settings view ({#action agent::OpenSettings}) and go to the **Vercel AI Gateway** section -3. Enter your Vercel AI Gateway API key - -The Vercel AI Gateway API key will be saved in your keychain. - -Zed will also use the `VERCEL_AI_GATEWAY_API_KEY` environment variable if it's defined. - -You can also set a custom endpoint for Vercel AI Gateway in your settings file: - -```json [settings] -{ - "language_models": { - "vercel_ai_gateway": { - "api_url": "https://ai-gateway.vercel.sh/v1" - } - } -} -``` - -### xAI {#xai} - -Zed includes a dedicated [xAI](https://x.ai/) provider. You can use your own API key to access Grok models. - -1. [Create an API key in the xAI Console](https://console.x.ai/team/default/api-keys) -2. Open the settings view ({#action agent::OpenSettings}) and go to the **xAI** section -3. Enter your xAI API key - -The xAI API key will be saved in your keychain. Zed will also use the `XAI_API_KEY` environment variable if it's defined. - -> **Note:** The xAI API is OpenAI-compatible, and Zed also includes a dedicated xAI provider. We recommend using the dedicated `x_ai` provider configuration instead of the [OpenAI API Compatible](#openai-api-compatible) method. - -#### Custom Models {#xai-custom-models} - -The Zed agent comes pre-configured with common Grok models. If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json [settings] -{ - "language_models": { - "x_ai": { - "api_url": "https://api.x.ai/v1", - "available_models": [ - { - "name": "grok-1.5", - "display_name": "Grok 1.5", - "max_tokens": 131072, - "max_output_tokens": 8192 - }, - { - "name": "grok-1.5v", - "display_name": "Grok 1.5V (Vision)", - "max_tokens": 131072, - "max_output_tokens": 8192, - "supports_images": true - } - ] - } - } -} -``` - -## Custom Provider Endpoints {#custom-provider-endpoint} - -You can use a custom API endpoint for different providers, as long as it's compatible with the provider's API structure. -To do so, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)): - -```json -{ - "language_models": { - "some-provider": { - "api_url": "http://localhost:11434" - } - } -} -``` - -Currently, `some-provider` can be any of the following values: `anthropic`, `google`, `ollama`, `openai`. - -This is the same infrastructure that powers models that are, for example, [OpenAI-compatible](#openai-api-compatible). +OpenAI-compatible provider setup has moved to [Use API Access](./use-api-access.md#openai-compatible). diff --git a/docs/src/ai/mcp.md b/docs/src/ai/mcp.md index c3fedb9440..c833155490 100644 --- a/docs/src/ai/mcp.md +++ b/docs/src/ai/mcp.md @@ -16,6 +16,14 @@ We welcome contributions that help advance Zed's MCP feature coverage (Discovery Zed also handles the `notifications/tools/list_changed` notification from MCP servers. When a server adds, removes, or modifies its available tools at runtime, Zed automatically reloads the tool list without requiring a server restart. +## Agent Path Support {#agent-path-support} + +| Agent path | MCP behavior | +| ----------------------------------------- | --------------------------------------------------------------------------------------- | +| [Zed Agent](./zed-agent.md) | Uses Zed-configured MCP servers directly | +| [External Agents](./external-agents.md) | Zed can forward configured MCP servers over ACP; agents may also read native MCP config | +| [Terminal Threads](./terminal-threads.md) | Native CLIs/TUIs read their own MCP configuration | + ## Installing MCP Servers ### As Extensions @@ -91,7 +99,7 @@ Once installation is complete, you can return to the Agent Panel and start promp How reliably MCP tools get called can vary from model to model. Mentioning the MCP server by name can help the model pick tools from that server. -However, if you want to _ensure_ a given MCP server will be used, you can create [a custom profile](./agent-panel.md#custom-profiles) where all built-in tools (or the ones that could cause conflicts with the server's tools) are turned off and only the tools coming from the MCP server are turned on. +However, if you want to _ensure_ a given MCP server will be used, you can create [a custom profile](./agent-profiles.md) where all built-in tools (or the ones that could cause conflicts with the server's tools) are turned off and only the tools coming from the MCP server are turned on. As an example, [the Dagger team suggests](https://container-use.com/agent-integrations#zed) doing that with their [Container Use MCP server](https://zed.dev/extensions/mcp-server-container-use): @@ -156,9 +164,9 @@ Learn more about [how tool permissions work](./tool-permissions.md), how to furt ### External Agents -MCP servers configured in Zed are forwarded to [external agents](./external-agents.md) via the [Agent Client Protocol](https://agentclientprotocol.com/). External agents can also access MCP servers from their own native configuration files. +MCP servers configured in Zed are forwarded to [External Agents](./external-agents.md) via the [Agent Client Protocol](https://agentclientprotocol.com/). External Agents can also access MCP servers from their own native configuration files. -For details on what configuration is shared between Zed and external agents, see [Configuration Boundaries](./external-agents.md#configuration-boundaries). +For details on what configuration is shared between Zed and External Agents, see [Configuration Boundaries](./external-agents.md#configuration-boundaries). ### Error Handling diff --git a/docs/src/ai/models.md b/docs/src/ai/models.md deleted file mode 100644 index 72ef43239f..0000000000 --- a/docs/src/ai/models.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: AI Models and Pricing - Zed -description: AI models available via Zed Pro including Claude, GPT-5.5, Gemini 3.1 Pro, and Grok. Pricing, context windows, and tool call support. ---- - -# Models - -Zed's plans offer hosted versions of major LLMs with higher rate limits than direct API access. Model availability is updated regularly. To use your own API keys instead, see [LLM Providers](./llm-providers.md). For general setup, see [Configuration](./configuration.md). - -> **Note:** Claude Opus models, GPT-5.5 pro, and GPT-5.4 pro are not available on the [Student plan](./plans-and-usage.md#student). - -| Model | Provider | Token Type | Provider Price per 1M tokens | Zed Price per 1M tokens | -| ---------------------- | --------- | ------------------- | ---------------------------- | ----------------------- | -| Claude Opus 4.5 | Anthropic | Input | $5.00 | $5.50 | -| | Anthropic | Output | $25.00 | $27.50 | -| | Anthropic | Input - Cache Write | $6.25 | $6.875 | -| | Anthropic | Input - Cache Read | $0.50 | $0.55 | -| Claude Opus 4.6 | Anthropic | Input | $5.00 | $5.50 | -| | Anthropic | Output | $25.00 | $27.50 | -| | Anthropic | Input - Cache Write | $6.25 | $6.875 | -| | Anthropic | Input - Cache Read | $0.50 | $0.55 | -| Claude Opus 4.7 | Anthropic | Input | $5.00 | $5.50 | -| | Anthropic | Output | $25.00 | $27.50 | -| | Anthropic | Input - Cache Write | $6.25 | $6.875 | -| | Anthropic | Input - Cache Read | $0.50 | $0.55 | -| Claude Opus 4.8 | Anthropic | Input | $5.00 | $5.50 | -| | Anthropic | Output | $25.00 | $27.50 | -| | Anthropic | Input - Cache Write | $6.25 | $6.875 | -| | Anthropic | Input - Cache Read | $0.50 | $0.55 | -| Claude Sonnet 4.5 | Anthropic | Input | $3.00 | $3.30 | -| | Anthropic | Output | $15.00 | $16.50 | -| | Anthropic | Input - Cache Write | $3.75 | $4.125 | -| | Anthropic | Input - Cache Read | $0.30 | $0.33 | -| Claude Sonnet 4.6 | Anthropic | Input | $3.00 | $3.30 | -| | Anthropic | Output | $15.00 | $16.50 | -| | Anthropic | Input - Cache Write | $3.75 | $4.125 | -| | Anthropic | Input - Cache Read | $0.30 | $0.33 | -| Claude Haiku 4.5 | Anthropic | Input | $1.00 | $1.10 | -| | Anthropic | Output | $5.00 | $5.50 | -| | Anthropic | Input - Cache Write | $1.25 | $1.375 | -| | Anthropic | Input - Cache Read | $0.10 | $0.11 | -| GPT-5.5 pro | OpenAI | Input | $30.00 | $33.00 | -| | OpenAI | Output | $180.00 | $198.00 | -| GPT-5.5 | OpenAI | Input | $5.00 | $5.50 | -| | OpenAI | Output | $30.00 | $33.00 | -| | OpenAI | Cached Input | $0.50 | $0.55 | -| GPT-5.4 pro | OpenAI | Input | $30.00 | $33.00 | -| | OpenAI | Output | $180.00 | $198.00 | -| GPT-5.4 | OpenAI | Input | $2.50 | $2.75 | -| | OpenAI | Output | $15.00 | $16.50 | -| | OpenAI | Cached Input | $0.025 | $0.0275 | -| GPT-5.3-Codex | OpenAI | Input | $1.75 | $1.925 | -| | OpenAI | Output | $14.00 | $15.40 | -| | OpenAI | Cached Input | $0.175 | $0.1925 | -| GPT-5.2 | OpenAI | Input | $1.75 | $1.925 | -| | OpenAI | Output | $14.00 | $15.40 | -| | OpenAI | Cached Input | $0.175 | $0.1925 | -| GPT-5.2-Codex | OpenAI | Input | $1.75 | $1.925 | -| | OpenAI | Output | $14.00 | $15.40 | -| | OpenAI | Cached Input | $0.175 | $0.1925 | -| GPT-5 mini | OpenAI | Input | $0.25 | $0.275 | -| | OpenAI | Output | $2.00 | $2.20 | -| | OpenAI | Cached Input | $0.025 | $0.0275 | -| GPT-5 nano | OpenAI | Input | $0.05 | $0.055 | -| | OpenAI | Output | $0.40 | $0.44 | -| | OpenAI | Cached Input | $0.005 | $0.0055 | -| Gemini 3.1 Pro | Google | Input | $2.00 | $2.20 | -| | Google | Output | $12.00 | $13.20 | -| Gemini 3 Flash | Google | Input | $0.50 | $0.55 | -| | Google | Output | $3.00 | $3.30 | -| Grok 4 | X.ai | Input | $3.00 | $3.30 | -| | X.ai | Output | $15.00 | $16.5 | -| | X.ai | Cached Input | $0.75 | $0.825 | -| Grok 4 Fast | X.ai | Input | $0.20 | $0.22 | -| | X.ai | Output | $0.50 | $0.55 | -| | X.ai | Cached Input | $0.05 | $0.055 | -| Grok 4 (Non-Reasoning) | X.ai | Input | $0.20 | $0.22 | -| | X.ai | Output | $0.50 | $0.55 | -| | X.ai | Cached Input | $0.05 | $0.055 | -| Grok Code Fast 1 | X.ai | Input | $0.20 | $0.22 | -| | X.ai | Output | $1.50 | $1.65 | -| | X.ai | Cached Input | $0.02 | $0.022 | - -## Recent Model Retirements - -As of February 19, 2026, Zed Pro serves newer model versions in place of the retired models below: - -- Claude Opus 4.1 → Claude Opus 4.5, Claude Opus 4.6, Claude Opus 4.7, or Claude Opus 4.8 -- Claude Sonnet 4 → Claude Sonnet 4.5 or Claude Sonnet 4.6 -- Claude Sonnet 3.7 (retired Feb 19) → Claude Sonnet 4.5 or Claude Sonnet 4.6 -- GPT-5.1 and GPT-5 → GPT-5.2 or GPT-5.2-Codex -- Gemini 2.5 Pro → Gemini 3.1 Pro -- Gemini 3 Pro → Gemini 3.1 Pro -- Gemini 2.5 Flash → Gemini 3 Flash - -## Usage {#usage} - -Because Zed-hosted Gemini models do not use Google context caching, Gemini usage is billed only as input and output tokens; there is no separate cached-input price for these models. This preserves zero-data-retention behavior for hosted Gemini requests. For background, see Google's Vertex AI documentation on [context caching](https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview) and [zero data retention](https://cloud.google.com/vertex-ai/generative-ai/docs/vertex-ai-zero-data-retention). - -Any usage of a Zed-hosted model will be billed at the Zed Price (rightmost column above). See [Plans and Usage](./plans-and-usage.md) for details on Zed's plans and limits for use of hosted models. - -> LLMs can enter unproductive loops that require user intervention. Monitor longer-running tasks and interrupt if needed. - -## Context Windows {#context-windows} - -A context window is the maximum span of text and code an LLM can consider at once, including both the input prompt and output generated by the model. - -| Model | Provider | Zed-Hosted Context Window | -| --------------------------- | --------- | ------------------------- | -| Claude Opus 4.5 | Anthropic | 200k | -| Claude Opus 4.6 | Anthropic | 1M | -| Claude Opus 4.7 | Anthropic | 1M | -| Claude Opus 4.8 | Anthropic | 1M | -| Claude Sonnet 4.5 | Anthropic | 200k | -| Claude Sonnet 4.6 | Anthropic | 1M | -| Claude Haiku 4.5 | Anthropic | 200k | -| GPT-5.5 pro | OpenAI | 272k input / 400k total | -| GPT-5.5 | OpenAI | 272k input / 400k total | -| GPT-5.4 pro | OpenAI | 272k input / 400k total | -| GPT-5.4 | OpenAI | 272k input / 400k total | -| GPT-5.3-Codex | OpenAI | 272k input / 400k total | -| GPT-5.2 | OpenAI | 272k input / 400k total | -| GPT-5.2-Codex | OpenAI | 272k input / 400k total | -| GPT-5 mini | OpenAI | 272k input / 400k total | -| GPT-5 nano | OpenAI | 272k input / 400k total | -| Gemini 3.1 Pro | Google | 200k | -| Gemini 3 Flash | Google | 200k | -| Grok 4 | X.ai | 128k | -| Grok 4 Fast | X.ai | 128k | -| Grok 4 Fast (Non-Reasoning) | X.ai | 128k | -| Grok Code Fast 1 | X.ai | 256k | - -> Context window limits for hosted Gemini 3.1 Pro/3 Flash may increase in future releases. - -Each Agent thread in Zed maintains its own context window. -The more prompts, attached files, and responses included in a session, the larger the context window grows. - -Start a new thread for each distinct task to keep context focused. - -## Tool Calls {#tool-calls} - -Models can use [tools](./tools.md) to interface with your code, search the web, and perform other useful functions. diff --git a/docs/src/ai/overview.md b/docs/src/ai/overview.md index 413b67ba59..87ecba9277 100644 --- a/docs/src/ai/overview.md +++ b/docs/src/ai/overview.md @@ -1,43 +1,50 @@ --- -title: AI Code Editor Documentation - Zed -description: Docs for AI in Zed, the open-source AI code editor. Agentic coding, inline edits, AI code completion, and multi-model support. +title: AI in Zed +description: Understand Zed's AI features, agent paths, model providers, and setup routes. --- # AI -Zed is an open-source AI code editor. AI runs throughout the editing experience: agents that read and write your code, inline transformations, code completions on every keystroke, and conversations with models in any buffer. +Zed's AI docs are organized around three areas: -## How Zed approaches AI +| Area | Use it to choose | Examples | +| ------------ | ----------------------------------- | -------------------------------------------------------------------- | +| Agents | How agentic work runs in Zed | Zed Agent, External Agents, Terminal Threads | +| Model access | How Zed connects to language models | Zed-hosted models, API access, subscriptions, gateways, local models | +| Features | Which AI workflow you want to use | Agentic editing, inline edits, edit prediction, Git assistance | -Zed's AI features run inside a native, GPU-accelerated application built in Rust. There is no Electron layer between you and the model output. +Start with [AI Quick Start](./quick-start.md) if you know what you want to do. Use [AI by Company](./by-company.md) if you know the company, subscription, model provider, agent, or CLI you want to use. -- **Open source.** The editor and all AI features are [open source](https://github.com/zed-industries/zed). You can read how AI is implemented, how data flows to providers, and how tool calls execute. -- **Multi-model.** Use Zed's hosted models or [bring your own API keys](./llm-providers.md) from Anthropic, OpenAI, Google, Ollama, and 8+ other providers. Run local models, connect to cloud APIs, or mix both. Switch models per task. -- **External agents.** Run Claude Agent, Gemini CLI, Codex, and other CLI-based agents directly in Zed through the [Agent Client Protocol](https://zed.dev/acp). See [External Agents](./external-agents.md). -- **Privacy by default.** AI data sharing is opt-in. When you use your own API keys, Zed maintains zero-data retention agreements with providers. See [Privacy and Security](./privacy-and-security.md). +## Agent Paths {#agent-paths} -## Agentic editing +Agent paths decide how agentic work runs in Zed. -The [Threads Sidebar](./parallel-agents.md#threads-sidebar) is where you organize agent work. Start a thread, give it a task, and the agent reads, edits, and runs code in your project. You can also open terminal threads directly in the sidebar alongside your agent threads. Run multiple agent threads and terminal threads at once, each using a different agent and working against different projects. See [Tools](./tools.md) for the capabilities available to Zed's built-in agent. +- [Zed Agent](./zed-agent.md): Zed's native agent. It can use models configured through [LLM Providers](./llm-providers.md), including Zed-hosted models, provider API keys, supported subscriptions, gateways, and local models. It also uses built-in tools, profiles, skills, instructions, and MCP servers. +- [External Agents](./external-agents.md): ACP-integrated agents that run through their own process and configuration. +- [Terminal Threads](./terminal-threads.md): terminal-backed threads for running an agent CLI or TUI directly in Zed. -The [Agent Panel](./agent-panel.md) is the conversation view for the active thread. Use it to send prompts, review changes, add context, and interact with the agent as it works. +The [Threads Sidebar](./parallel-agents.md#threads-sidebar) is where you organize agent work. You can run multiple agent threads and Terminal Threads at once, each using a different agent and working against different projects. -You can extend agents with additional tools through [MCP servers](./mcp.md), control what they can access with [tool permissions](./tool-permissions.md), and shape their behavior with [rules](./rules.md). +See [Agents](./agents.md) for a comparison. -The [Inline Assistant](./inline-assistant.md) works differently: select code or a terminal command, describe what you want, and the model rewrites the selection in place. It works with multiple cursors. +## Model Access {#model-access} -## Code completions +Model access controls which models power the Zed Agent and other model-backed Zed AI features. Zed can use hosted models, provider API access, subscription sign-in, gateways, and local models. -[Edit Prediction](./edit-prediction.md) provides AI code completions on every keystroke. Each keypress sends a request to the prediction provider, which returns single or multi-line suggestions you accept with `tab`. +See [LLM Providers](./llm-providers.md) to choose a model access path. -The default provider is Zeta, Zed's open-source model trained on open data. You can also use GitHub Copilot, or Codestral. +## AI Features {#ai-features} -## Getting started +Zed has several AI-powered workflows: -- [Configuration](./configuration.md): Connect to Anthropic, OpenAI, Ollama, Google AI, or other LLM providers. -- [Parallel Agents](./parallel-agents.md): Run multiple threads at once with the Threads Sidebar. -- [External Agents](./external-agents.md): Run Claude Agent, Codex, Aider, or other external agents inside Zed. -- [Subscription](./subscription.md): Zed's hosted models and billing. -- [Privacy and Security](./privacy-and-security.md): How Zed handles data when using AI features. +- [Agent Panel](./agent-panel.md): prompt agents, add context, review changes, and manage active threads. +- [Parallel Agents](./parallel-agents.md): run multiple threads across projects and worktrees. +- [Inline Assistant](./inline-assistant.md): transform a selection in place. +- [Edit Prediction](./edit-prediction.md): accept AI completions while you type. +- [Git commit generation](../git.md#ai-support-in-git): generate commit messages from the Git panel. -New to Zed? Start with [Getting Started](../getting-started.md), then come back here to set up AI. For a higher-level overview, see [zed.dev/ai](https://zed.dev/ai). +## Configure AI {#configure-ai} + +Use [AI Quick Start](./quick-start.md) to choose the right setup path, configure model access, add agents or MCP servers, control tools, and turn AI off. + +For privacy, provider data boundaries, and opt-in data sharing, see [AI Privacy](./privacy-and-security.md) and [Feedback and Training Data](./ai-improvement.md). diff --git a/docs/src/ai/parallel-agents.md b/docs/src/ai/parallel-agents.md index 6c8fccea8d..15d7c1850c 100644 --- a/docs/src/ai/parallel-agents.md +++ b/docs/src/ai/parallel-agents.md @@ -1,21 +1,21 @@ --- title: Parallel Agents - Zed -description: Run multiple agent threads and terminal threads concurrently using the Threads Sidebar, manage them across projects, and isolate work using Git worktrees. +description: Run multiple agent threads and Terminal Threads concurrently using the Threads Sidebar, manage them across projects, and isolate work using Git worktrees. --- # Parallel Agents -Parallel Agents lets you run multiple agent threads and terminal threads at once from the Threads Sidebar. Each thread works independently with its own agent, context window, and conversation history. Terminal threads appear alongside agent threads in the same sidebar, so you can switch between them without leaving the Agent Panel. +Parallel Agents lets you run multiple agent threads and Terminal Threads at once from the Threads Sidebar. Each thread works independently with its own agent, context window, and conversation history. Terminal Threads appear alongside agent threads in the same sidebar, so you can switch between them without leaving the Agent Panel. Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar}. -> **Note:** From version 0.233.0 onward, the Agent Panel and Threads Sidebar are on the left by default. The Project Panel, Git Panel, and other panels move to the right, keeping the thread list and conversation next to each other. To rearrange panels, right-click any panel icon. +Use **Zed > Panel Layout > Agentic** to place the Agent Panel and Threads Sidebar on the left, with the Project Panel, Git Panel, and other panels on the right. Use **Zed > Panel Layout > Classic** to restore the editor-oriented layout. You can still rearrange individual panels by right-clicking any panel icon. ## Threads Sidebar {#threads-sidebar} The sidebar shows your threads grouped by project. Each project gets its own section with a header. Threads appear below with their title, status indicator, and which agent is running them. Threads running in linked Git worktrees appear under the same project as their main worktree. See [Worktree Isolation](#worktree-isolation). -Terminal threads also appear as entries in the sidebar alongside agent threads, identified by a terminal icon. Click one to switch to it. See [terminal threads](./agent-panel.md#terminal-threads) for details. +Terminal Threads also appear as entries in the sidebar alongside agent threads, identified by a terminal icon. Click one to switch to it. To focus the sidebar without toggling it, use {#kb multi_workspace::FocusWorkspaceSidebar}. To search your threads, press {#kb agents_sidebar::FocusSidebarFilter} while the sidebar is focused. @@ -39,7 +39,7 @@ You can search your threads in history; search will fuzzy match on thread titles ### Importing External Agent Threads {#importing-threads} -If you have external agents installed, Zed will detect whether you have existing threads and invite you to import them into Zed. Once you open Thread History, you'll find an import icon button in the Thread History toolbar that lets you import threads at any time. Clicking on it opens a modal where you can select the agents whose threads you want to import. +If you have External Agents installed, Zed will detect whether you have existing threads and invite you to import them into Zed. Once you open Thread History, you'll find an import icon button in the Thread History toolbar that lets you import threads at any time. Clicking on it opens a modal where you can select the agents whose threads you want to import. > **Note:** Thread import is subject to agent support. Some agents (such as Cursor and Gemini CLI) are not currently supported. @@ -47,7 +47,17 @@ If you have external agents installed, Zed will detect whether you have existing Each thread runs independently, so you can send a prompt, open a second thread, and give it a different task while the first continues working. To scope a new thread to a specific project, hover over that project's header in the Threads Sidebar and click the `+` button, or use {#action agents_sidebar::NewThreadInGroup} from the keyboard. See [Creating New Threads](./agent-panel.md#new-thread) for the other entry points. -Each thread can use a different agent, so you can run Zed's built-in agent in one thread and an [external agent](./external-agents.md) like Claude Code or Codex in another. +Each thread can use a different agent, so you can run Zed's built-in agent in one thread and an [External Agent](./external-agents.md) like Claude Code or Codex in another. + +### Thread Types {#thread-types} + +The Threads Sidebar can hold different thread types: + +| Thread type | Configuration | +| --------------------------------------------- | ------------------------------------------------------------------------------- | +| [Zed Agent thread](./zed-agent.md) | Uses Zed Agent settings, profiles, tools, Skills, Instructions, and MCP | +| [External Agent thread](./external-agents.md) | Uses the ACP integration and the agent's native configuration | +| [Terminal Thread](./terminal-threads.md) | Runs a CLI/TUI in a terminal-backed thread; the CLI owns auth and configuration | ## Multiple Projects {#multiple-projects} @@ -78,5 +88,6 @@ After the agent finishes, review the diff and merge the changes through your nor ## See Also {#see-also} - [Agent Panel](./agent-panel.md): Manage individual threads and configure the agent -- [External Agents](./external-agents.md): Use Claude Code, Gemini CLI, and other agents +- [External Agents](./external-agents.md): Use ACP-integrated External Agents +- [Terminal Threads](./terminal-threads.md): Run agent CLIs and TUIs directly in Zed - [Tools](./tools.md): Built-in tools available in each thread diff --git a/docs/src/ai/privacy-and-security.md b/docs/src/ai/privacy-and-security.md index 47c92d482e..639471370c 100644 --- a/docs/src/ai/privacy-and-security.md +++ b/docs/src/ai/privacy-and-security.md @@ -1,33 +1,72 @@ --- -title: Privacy Overview - Zed -description: "Zed's approach to privacy: opt-in data sharing, zero-data retention with AI providers, and an open-source codebase you can inspect." +title: AI Privacy - Zed +description: Understand how Zed handles AI prompts, code context, hosted model requests, provider data boundaries, feedback, training data, and privacy controls. --- -# Privacy Overview +# AI Privacy -Zed collects minimal data necessary to serve and improve the product. Features that could share data are either opt-in or can be disabled. +This page explains the privacy and trust boundaries for AI features in Zed, +including [Zed Agent](./zed-agent.md), [Edit Prediction](./edit-prediction.md), +[Inline Assistant](./inline-assistant.md), and +[Git commit generation](../git.md#ai-support-in-git). -- **Telemetry:** Zed collects only the data necessary to understand usage and fix issues. Client-side telemetry can be disabled in settings. See [Telemetry](../telemetry.md). +Zed does not retain your prompts or code context by default. For +[Zed-hosted models](../account/zed-hosted-models.md), Zed has zero-data-retention +and no-training commitments from model providers for inference requests. Zed only +retains AI data when you explicitly share feedback or opt in to training data +collection. -- **AI:** Zed doesn't store your prompts or code context. Data sharing for AI improvement is opt-in, and each share is a one-time action; it doesn't grant permission for future collection. You can use Zed's AI features without sharing any data with Zed. See [AI Improvement](./ai-improvement.md). +## AI Request Paths {#ai-request-paths} -- **Open source:** Zed's codebase is public. You can inspect exactly what data is collected and how it's handled. If you find issues, [report them](https://github.com/zed-industries/zed/issues). +| Path | Who handles model requests | What to know | Details | +| ------------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| [Zed-hosted models](../account/zed-hosted-models.md) | Zed routes requests to hosted model providers | Provider agreements require zero data retention and prohibit training on your prompts or code context for inference requests. | [Zed-hosted model commitments](#data-retention-and-training) | +| [Provider API keys](./use-api-access.md) | The configured provider | The provider handles requests under its own terms. Provider keys saved through Zed are stored in the system keychain, not in `settings.json`. | [Use API Access](./use-api-access.md) | +| [Existing subscriptions](./use-an-existing-subscription.md) | The subscription provider | The provider handles requests under the subscription terms. | [Use an Existing Subscription](./use-an-existing-subscription.md) | +| [Gateways](./use-a-gateway.md) | The configured gateway and upstream providers | The gateway and upstream providers handle requests under their own terms. | [Use a Gateway](./use-a-gateway.md) | +| [Local models](./use-a-local-model.md) | The local server or self-hosted endpoint | The local server handles requests according to how you configured that server. | [Use a Local Model](./use-a-local-model.md) | +| [External Agents](./external-agents.md) | The External Agent and its configured providers | The External Agent handles model requests under its own terms. Tool and MCP behavior depends on agent and ACP configuration. | [External Agents](./external-agents.md) | +| [Terminal Threads](./terminal-threads.md) | The CLI or TUI running in the terminal | The CLI or TUI owns its auth, model routing, tools, instructions, MCP configuration, and data handling. | [Terminal Threads](./terminal-threads.md) | +| [Edit Prediction](./edit-prediction.md) | The selected edit prediction provider | Each keystroke can send local editing context to the selected provider. Zeta requests are processed transiently unless training data collection is enabled; third-party providers follow their own terms. | [Edit Prediction](./edit-prediction.md), [Feedback and Training Data](./ai-improvement.md) | +| [Agent tools](./tools.md), [MCP](./mcp.md), and integrations | Zed, configured MCP servers, and external systems | Tools can read, edit, search, run commands, fetch URLs, or call external systems depending on profile, MCP server, and tool permission settings. | [Agent Profiles](./agent-profiles.md), [Tool Permissions](./tool-permissions.md), [MCP](./mcp.md) | +| Project trust and instructions | Zed and the trusted worktree | Project-local instructions and skills are loaded from trusted worktrees. External Agents and Terminal Threads may read their own instruction files. | [Worktree Trust](../worktree-trust.md), [Skills](./skills.md), [Instructions](./instructions.md) | -On Zed Business, administrators can enforce these settings org-wide so members can't opt in to data sharing individually. See [Privacy for Business](../business/privacy.md). +## Zed-Hosted Model Commitments {#data-retention-and-training} -## Related documentation +For Zed-hosted models, Zed has commitments from model providers that prohibit +training on your prompts or code context and require zero data retention for +inference requests. The public provider documents linked below describe provider +programs or default API terms; Zed-hosted model requests are governed by Zed's +provider agreements. -- [Tool Permissions](./tool-permissions.md): Configure which agent actions are auto-approved, blocked, or require confirmation. -- [Worktree Trust](../worktree-trust.md): How Zed opens files and directories in restricted mode. -- [Telemetry](../telemetry.md): What telemetry Zed collects and how to control it. -- [AI Improvement](./ai-improvement.md): How data sharing for AI improvement works and how to opt in. -- [Privacy for Business](../business/privacy.md): How Zed Business enforces privacy settings across an organization. -- [Authentication](../authentication.md): When and why authentication is needed. -- [SOC2](../soc2.md): Zed's security certification status. +| Provider | No training reference | Zero-data-retention reference | +| --------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| Anthropic | [Yes](https://www.anthropic.com/legal/commercial-terms) | [Yes](https://privacy.anthropic.com/en/articles/8956058-i-have-a-zero-data-retention-agreement-with-anthropic-what-products-does-it-apply-to) | +| Google | [Yes](https://cloud.google.com/terms/service-terms) | [Yes](https://cloud.google.com/terms/service-terms), see Service Terms sections 18 and 20(h) | +| OpenAI | [Yes](https://openai.com/enterprise-privacy/) | [Yes](https://platform.openai.com/docs/guides/your-data) | -## Legal +## AI Data Retained by Zed {#ai-data-retained-by-zed} -- [Terms of Service](https://zed.dev/terms) -- [Privacy Policy](https://zed.dev/privacy-policy) -- [Contributor License and Feedback Agreement](https://zed.dev/cla) -- [Subprocessors](https://zed.dev/subprocessors) +Zed may retain AI data only when you explicitly share it or opt in: + +- [Response ratings and feedback](./ai-improvement.md#ai-feedback-with-ratings) + can send a conversation thread to Zed for review and improvement. +- [Edit Prediction training data](./ai-improvement.md#edit-predictions) is + collected only when you opt in, the project is open source, and the file is not + excluded. + +See [Feedback and Training Data](./ai-improvement.md) for the full list of what +can be stored in each opt-in case. + +## Controls and Related Privacy Docs {#controls-and-related-privacy-docs} + +- [Telemetry](../telemetry.md): What telemetry Zed collects and how to control + it. +- [Privacy for Business](../business/privacy.md): How Zed Business enforces + privacy settings across an organization. +- [Admin Controls](../business/admin-controls.md): How owners and admins control + Zed-hosted models, Edit Prediction, and feedback sharing. +- [AI Quick Start](./quick-start.md#turn-ai-off): How to turn AI off. +- [Privacy Policy](https://zed.dev/privacy-policy): Zed's privacy policy. +- [Subprocessors](https://zed.dev/subprocessors): Zed's subprocessors. +- [Terms of Service](https://zed.dev/terms): Zed's terms. diff --git a/docs/src/ai/quick-start.md b/docs/src/ai/quick-start.md new file mode 100644 index 0000000000..765c5cfeec --- /dev/null +++ b/docs/src/ai/quick-start.md @@ -0,0 +1,92 @@ +--- +title: AI Quick Start - Zed +description: Choose the right Zed AI setup path for agents, models, subscriptions, local models, edit prediction, and privacy. +--- + +# AI Quick Start + +Use this page to choose the right AI setup path in Zed. If you already know the company, subscription, model provider, agent, or CLI you want to use, start with [AI by Company](./by-company.md). + +## Use the Zed Agent {#zed-agent} + +Use [Zed Agent](./zed-agent.md) when you want Zed's native agent to read, edit, search, and run code in your project. + +Zed Agent uses Zed-configured models from [LLM Providers](./llm-providers.md). It also uses Zed's built-in tools, [Agent Profiles](./agent-profiles.md), [Skills](./skills.md), [Instructions](./instructions.md), and [MCP servers](./mcp.md). + +Start in the [Agent Panel](./agent-panel.md) to prompt the agent, add context, review changes, and manage threads. + +### Configure the Zed Agent {#configure-zed-agent} + +| If you want to... | Use | +| ----------------------------------------- | ----------------------------------------- | +| Control tools and permissions | [Agent Profiles](./agent-profiles.md) | +| Approve or deny individual tools | [Tool Permissions](./tool-permissions.md) | +| Add reusable task instructions | [Skills](./skills.md) | +| Add always-on personal or project context | [Instructions](./instructions.md) | +| Connect external tools and context | [Model Context Protocol](./mcp.md) | + +## Use Another Coding Agent in Zed {#agent-cli} + +Use this path for Claude, Codex, OpenCode, Copilot, Cursor, Pi Coding Agent, Gemini CLI, or another coding agent. + +| If the agent... | Use | +| ------------------------------- | ----------------------------------------- | +| Integrates with Zed through ACP | [External Agents](./external-agents.md) | +| Runs as a CLI or TUI | [Terminal Threads](./terminal-threads.md) | + +External Agents and Terminal Threads usually own their own auth, model configuration, subscriptions, tools, instructions, and MCP configuration. + +## Choose Which Models the Zed Agent Uses {#model-access} + +The Zed Agent and other model-backed Zed AI features use models configured through [LLM Providers](./llm-providers.md). + +| If you want to... | Use | +| ----------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Use models billed through Zed | [Zed-Hosted Models](../account/zed-hosted-models.md) | +| Bring your own provider API key, credits, top-ups, or usage billing | [Use API Access](./use-api-access.md) | +| Use a subscription you already pay for | [Use an Existing Subscription](./use-an-existing-subscription.md) | +| Use OpenRouter, Vercel AI Gateway, Amazon Bedrock, or another gateway | [Use a Gateway](./use-a-gateway.md) | +| Use Ollama, LM Studio, local OpenAI-compatible servers, or self-hosted models | [Use a Local Model](./use-a-local-model.md) | + +Provider keys saved through Zed are stored in the system keychain, not in `settings.json`. + +## Change AI Settings {#ai-settings} + +| If you want to... | Go to | +| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| Configure LLM providers, External Agents, or MCP servers | [Agent Settings](./agent-settings.md) with {#action agent::OpenSettings} | +| Disable AI, configure tool permissions, or set up edit prediction providers | Settings Editor with {#action zed::OpenSettings} | +| Edit advanced JSON-only settings | Settings file with {#action zed::OpenSettingsFile} | + +For general settings mechanics, see [Configuring Zed](../configuring-zed.md). + +## Use a Specific AI Feature {#features} + +| If you want to... | Use | +| ---------------------------------------------- | ---------------------------------------------------- | +| Prompt agents, add context, and review changes | [Agent Panel](./agent-panel.md) | +| Accept AI completions while typing | [Edit Prediction](./edit-prediction.md) | +| Rewrite selected code or terminal text | [Inline Assistant](./inline-assistant.md) | +| Run multiple AI tasks at once | [Parallel Agents](./parallel-agents.md) | +| Generate commit messages | [Git commit generation](../git.md#ai-support-in-git) | + +## Learn More {#learn-more} + +| If you want to... | Use | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Understand privacy and data controls | [AI Privacy](./privacy-and-security.md) and [Feedback and Training Data](./ai-improvement.md) | +| Understand plans, usage, and billing | [Plans & Pricing](../account/plans-and-pricing.md), [Zed-Hosted Models](../account/zed-hosted-models.md), and [Billing](../account/billing.md) | + +## Turn AI Off {#turn-ai-off} + +Open the Settings Editor with {#action zed::OpenSettings}, search for `Disable AI`, and enable it. + +You can also add this to your settings file: + +```json [settings] +{ + "disable_ai": true +} +``` + +When AI is turned off, all AI features are disabled. This includes the Threads Sidebar, Agent Panel, Edit Prediction, and Inline Assistant. diff --git a/docs/src/ai/rules.md b/docs/src/ai/rules.md index 87f6008ce6..d2ab7da817 100644 --- a/docs/src/ai/rules.md +++ b/docs/src/ai/rules.md @@ -1,19 +1,21 @@ --- -title: AI Rules in Zed - .rules, .cursorrules, CLAUDE.md -description: Configure AI behavior in Zed with .rules files, .cursorrules, CLAUDE.md, AGENTS.md, and the Rules Library for project-level instructions. +title: Rules (Replaced by Skills) +description: Rules have been replaced by Skills and Instructions in Zed. --- # Rules {#rules} -Rules are prompts that can be inserted either automatically at the beginning of each [Agent Panel](./agent-panel.md) interaction, through `.rules` files available in your project's file tree, or on-demand, through @-mentioning, via the Rules Library. +Rules have been replaced by [Skills](./skills.md) and [Instructions](./instructions.md). -> **Note:** Starting in Zed v1.4.0, on-demand rules (and the rules library) have been replaced by [Skills](./skills.md). Skills are the recommended way to package reusable agent instructions. Learn more about [the rules -> skills migration](#migrating-to-skills). +> **Note:** Starting in Zed v1.4.0, on-demand Rules and the Rules Library have been replaced by [Skills](./skills.md). Skills are the recommended way to package reusable agent instructions. -## `.rules` files +Use [Skills](./skills.md) for reusable task instructions that can be invoked by name or selected by the model. Use [Instructions](./instructions.md) for always-on personal and project context. -Zed supports including `.rules` files at the root of a project's file tree, and they act as project-level instructions that are auto-included in all of your interactions with the Agent Panel. +## `.rules` Files {#rules-files} -Other names for this file are also supported for compatibility with other agents, but note that the first file which matches in this list will be used: +Project `.rules` files remain supported as compatibility project instruction files. See [Instructions](./instructions.md#project-instructions). + +Other instruction filenames are also supported for compatibility with other agents. The first matching file is used: - `.rules` - `.cursorrules` @@ -25,57 +27,12 @@ Other names for this file are also supported for compatibility with other agents - `CLAUDE.md` - `GEMINI.md` -## Rules Library {#rules-library} - -The Rules Library is an interface for writing and managing rules. -It's a full editor with syntax highlighting and all standard keybindings. - -You can also use the inline assistant right in the rules editor, allowing you to get quick LLM support for writing rules. - -> **Note:** Starting in Zed v1.4.0, the rules library has been replaced by [Skills](./skills.md). Skills are the recommended way to package reusable agent instructions. Learn more about [the rules -> skills migration](#migrating-to-skills). - -### Opening the Rules Library - -1. Open the Agent Panel. -2. Click on the Agent menu (`...`) in the top right corner. -3. Select `Rules...` from the dropdown. - -You can also open it by running the {#action agent::OpenRulesLibrary} action or through the {#kb agent::OpenRulesLibrary} keybinding. - -### Managing Rules - -Once a rules file is selected, you can edit it directly in the built-in editor. -Its title can be changed from the editor title bar as well. - -Rules can be duplicated, deleted, or added to the default rules using the buttons in the rules editor. - -### Creating Rules {#creating-rules} - -To create a rule file, simply open the `Rules Library` and click the `+` button. -Rules files are stored locally and can be accessed from the library at any time. - -For guidance on writing effective rules: - -- [Anthropic: Prompt Engineering](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) -- [OpenAI: Prompt Engineering](https://platform.openai.com/docs/guides/prompt-engineering) - -### Using Rules - -You can @-mention every rule created through the Rules Library. -This allows you to quickly reach for reusable prompts, saving the time to type them out every time you need to use them. - -#### Default Rules {#default-rules} - -All rules in the Rules Library can be set as a default rule, which means they’re automatically inserted into context for every new Agent Panel interaction. - -You can set any rule as the default by clicking the paper clip icon button in the top-right of the rule editor in the Rules Library. - ## Migrating to Skills {#migrating-to-skills} -As of Zed v1.4.0, your existing Rules are migrated to Skills automatically: +Existing Rules migrate automatically: -- **Non-default Rules** become global skills in `~/.agents/skills/`, each with `disable-model-invocation: true`. They remain user-invocable via `/skill-name` or `@`-mention. -- **Default Rules** are appended to your global `AGENTS.md` file (`~/.config/zed/AGENTS.md` on macOS and Linux, `%APPDATA%\Zed\AGENTS.md` on Windows), preserving their behavior of being included in every conversation. -- **Git Commit** prompt customizations are also appended to the global `AGENTS.md` file. +- Non-default Rules become global Skills in `~/.agents/skills/`, each with `disable-model-invocation: true`. They remain user-invocable by slash command or `@`-mention. +- Default Rules are appended to your global `AGENTS.md` file (`~/.config/zed/AGENTS.md` on macOS and Linux, `%APPDATA%\Zed\AGENTS.md` on Windows). +- Git commit prompt customizations are also appended to the global `AGENTS.md` file. -Lastly, note that all of the content you had available in the Rules Library hasn't been deleted, so downgrading to an earlier version of Zed leaves your Rules intact. +Rules Library content is not deleted, so downgrading to an earlier version of Zed leaves your Rules intact. diff --git a/docs/src/ai/skills.md b/docs/src/ai/skills.md index 39ee6844d2..8e25a113df 100644 --- a/docs/src/ai/skills.md +++ b/docs/src/ai/skills.md @@ -51,19 +51,6 @@ You can hand a skill to a teammate without hosting it anywhere. In the Skills se When someone opens that link (for example by pasting it into their browser or clicking it in a chat), Zed launches the Skill Creator pre-filled with the shared skill. The recipient can review the name, description, and full body, choose a scope (global or project-local), and click **Save** to install it. Nothing is written to disk until they explicitly save, so a shared link can never silently install instructions into someone's agent. -## Managing Skills {#managing-skills} - -Open the Settings Editor (`Cmd+,` on macOS, `Ctrl+,` on Linux/Windows) and navigate to **AI > Skills**, or go directly to [agent.skills](zed://settings/agent.skills). - -The **User** tab shows your global skills. The **Project** tab shows skills for the current project. - -For each skill you can: - -- **Open** — opens the skill's `SKILL.md` file in the editor -- **Delete** — removes the skill folder from disk - -If no skills are installed, the page shows a **Create a Skill** button that opens the Skill Creator. - ## Using Skills {#using-skills} By default, the agent picks up skills autonomously. It sees a catalog of every installed skill (name and description) in its system prompt, and calls the `skill` tool when a task matches a skill's description. @@ -198,6 +185,10 @@ If a global and a project-local skill share the same name, the project-local ski The agent cannot edit `SKILL.md` files or their bundled resources without your explicit authorization, even in a trusted project. This prevents a compromised conversation from modifying the skills that govern future conversations. +## Agent Path Boundaries {#agent-path-boundaries} + +Zed Skills apply to the Zed Agent. External Agents and Terminal Threads may have their own native skills, prompts, or instruction systems. Configure those in the External Agent or CLI. + ## Limitations {#limitations} - **Flat layout only.** Skills must be direct children of the skills root. Nested folders like `~/.agents/skills/group/my-skill/` are not discovered. diff --git a/docs/src/ai/subscription.md b/docs/src/ai/subscription.md deleted file mode 100644 index 0c4896fdbc..0000000000 --- a/docs/src/ai/subscription.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Zed AI Subscription -description: Learn about Zed Pro and Business plans for hosted AI models with higher rate limits and premium features. ---- - -# Subscription - -Zed's hosted models are offered via subscription to Zed Pro or Zed Business. - -> You can use [your own API keys](./llm-providers.md) or [external agents](./external-agents.md) without a Zed subscription. - -See the following pages for specific aspects of our subscription offering: - -- [Models](./models.md): Overview of the models offered by Zed's subscriptions. - -- [Plans and Usage](./plans-and-usage.md): Outlines Zed's plans and how usage is measured. - -- [Billing](./billing.md): Billing policies and procedures, and how to update or view various billing settings. diff --git a/docs/src/ai/terminal-threads.md b/docs/src/ai/terminal-threads.md new file mode 100644 index 0000000000..36b2d8128f --- /dev/null +++ b/docs/src/ai/terminal-threads.md @@ -0,0 +1,155 @@ +--- +title: Terminal Threads - Zed +description: Run agent CLIs and TUIs directly in terminal-backed threads in Zed. +--- + +# Terminal Threads + +Terminal Threads are terminal-backed threads in the [Threads Sidebar](./parallel-agents.md#threads-sidebar). Use them when you want to run an agent CLI or TUI directly in Zed. + +Terminal Threads are different from [External Agents](./external-agents.md). External Agents integrate with Zed through ACP and render as agent threads. Terminal Threads run the native command-line tool in a terminal that Zed organizes as a thread. + +## What Zed Owns {#what-zed-owns} + +Zed owns the thread surface: + +- the terminal-backed thread in the Threads Sidebar +- thread grouping by project +- switching and organizing the terminal session alongside other threads + +## What the CLI Owns {#what-the-cli-owns} + +The CLI or TUI running inside the terminal owns its own: + +- authentication +- model/provider configuration +- subscriptions or API keys +- tool configuration +- skills and instruction files +- MCP configuration + +Zed Agent profiles, Zed Agent tool permissions, Zed Skills, and Zed Agent MCP settings do not automatically apply to Terminal Threads. + +## Opening a Terminal Thread {#opening-a-terminal-thread} + +Open the new-thread menu from the [Agent Panel](./agent-panel.md) using the agent selector button on the left or the `+` icon in the top-right of the panel toolbar, then choose **Terminal**. The Terminal Thread opens in the panel body, just like switching to an agent thread. + +You can open as many Terminal Threads as you like. Each gets its own entry in the Threads Sidebar. + +## Terminal Thread Titles {#terminal-thread-titles} + +The terminal title in the toolbar updates automatically to reflect the running shell or process. You can also set a custom name by clicking the title or the pencil icon that appears on hover. + +## Notifications {#terminal-thread-notifications} + +When a terminal produces a bell character while not in focus, Zed notifies you the same way it does when an agent finishes: with a visual pop-up and an optional sound. Clicking the notification brings the terminal into focus and clears the indicator. + +The same `agent.notify_when_agent_waiting` and `agent.play_sound_when_agent_done` settings apply. + +## Closing Terminal Threads {#closing-terminal-threads} + +Unlike agent threads, Terminal Threads are closed rather than archived. They do not go to Thread History. To close one, hover over it in the Threads Sidebar and click the **×** button, or select it and press {#kb agent::ArchiveSelectedThread}. + +## CLI/TUI Setup Notes {#cli-setup} + +Some agent CLIs and TUIs can send terminal signals, such as bell notifications or title updates, that Zed uses to show useful context in the sidebar. + +### Claude Code Notifications {#claude-code-notifications} + +Claude Code can notify you when it finishes a task or pauses for permission. To enable this, set `preferredNotifChannel` to `"terminal_bell"` in your Claude Code user settings: + +```json +{ + "preferredNotifChannel": "terminal_bell" +} +``` + +You can also set this from within Claude Code by running `/config`, selecting `Local Notifications`, and choosing `Terminal Bell`. + +> If you run Claude Code inside tmux, bell notifications may not reach the outer terminal unless passthrough is enabled. Add this to `~/.tmux.conf`: +> +> ``` +> set -g allow-passthrough on +> ``` + +For more, see the [Claude Code documentation](https://code.claude.com/docs/en/terminal-config). + +### Amp Notifications {#amp-notifications} + +Amp updates terminal titles automatically and can also notify you when it needs your attention. To enable notifications in Zed Terminal Threads, add `AMP_FORCE_BEL=1` to your terminal environment settings: + +```json [settings] +{ + "terminal": { + "env": { + "AMP_FORCE_BEL": "1" + } + } +} +``` + +Restart Amp after adding the environment variable. + +### OpenCode Notifications {#opencode-notifications} + +OpenCode can update terminal titles automatically. For Zed notifications, add an OpenCode plugin that emits a terminal bell when OpenCode needs your attention. + +Create `.opencode/plugins/zed-bell.js` in your project, or `~/.config/opencode/plugins/zed-bell.js` to use it globally: + +```js +export const ZedBell = async () => { + return { + event: async ({ event }) => { + if (event.type === "session.idle" || event.type === "permission.asked") { + process.stdout.write("\x07"); + } + }, + }; +}; +``` + +Restart OpenCode after adding the plugin. + +### Pi Notifications {#pi-notifications} + +Pi can use an extension to emit a notification when it finishes a turn. Create `.pi/extensions/zed-bell.ts` in your project, or `~/.pi/agent/extensions/zed-bell.ts` to use it globally: + +```ts +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; + +export default function (pi: ExtensionAPI) { + pi.on("agent_end", async () => { + process.stdout.write("\x07"); + }); +} +``` + +Restart Pi after adding the extension, or run `/reload` if the extension is in one of Pi's auto-discovered extension locations. + +### Codex Terminal Titles {#codex-terminal-titles} + +Codex can update the terminal title as it works, which Zed uses to show useful context for Codex Terminal Threads in the sidebar, such as the project, current status, branch, model, or task progress. + +To configure this from within Codex, run `/title` and use the picker to choose which fields appear and in what order. Codex saves the selection to `tui.terminal_title` in `~/.codex/config.toml`. You can also edit it directly: + +```toml +[tui] +terminal_title = ["spinner", "project-name", "run-state", "thread-title"] +``` + +## Credentials and Remote Projects {#credentials-and-remote-projects} + +Credentials come from the terminal session and the CLI/TUI running inside it. + +In remote projects, the CLI may read the remote shell environment and remote config files. In local Terminal Threads, it reads the local shell environment and local config files. Zed does not copy API keys from LLM provider settings into Terminal Threads. + +## When to Use Terminal Threads {#when-to-use-terminal-threads} + +Use Terminal Threads when: + +- you want the tool's native CLI/TUI experience +- no ACP integration exists +- you want subscription behavior owned by the CLI +- you want the CLI to use its own native config files + +For ACP-integrated agents, see [External Agents](./external-agents.md). diff --git a/docs/src/ai/text-threads.md b/docs/src/ai/text-threads.md index 2315666460..6dce29008d 100644 --- a/docs/src/ai/text-threads.md +++ b/docs/src/ai/text-threads.md @@ -8,6 +8,6 @@ redirect_to: ./agent-panel.md Text threads have been removed from Zed. -All AI conversations now happen through the [Agent Panel](./agent-panel.md), which supports agentic workflows including tool calls, file editing, terminal access, and [external agents](./external-agents.md). +All AI conversations now happen through the [Agent Panel](./agent-panel.md), which supports agentic workflows including tool calls, file editing, terminal access, and [External Agents](./external-agents.md). See the [Agent Panel documentation](./agent-panel.md) to get started. diff --git a/docs/src/ai/tool-permissions.md b/docs/src/ai/tool-permissions.md index 040ece8041..d2026d0b75 100644 --- a/docs/src/ai/tool-permissions.md +++ b/docs/src/ai/tool-permissions.md @@ -54,10 +54,13 @@ The `tool_permissions` setting lets you customize tool permissions by specifying | `create_directory` | The directory path | | `fetch` | The URL | | `search_web` | The search query | +| `skill` | The skill name | For MCP tools, use the format `mcp::`. For example, a tool called `create_issue` on a server called `github` would be `mcp:github:create_issue`. +For model-invoked [Skills](./skills.md), use the `skill` tool. A user-invoked `/skill-name` slash command does not prompt again because you explicitly invoked the skill. + ## Configuration ```json [settings] @@ -305,3 +308,22 @@ MCP tools only support the tool-level option. } } ``` + +### Skills + +```json [settings] +{ + "agent": { + "tool_permissions": { + "tools": { + "skill": { + "default": "confirm", + "always_allow": [{ "pattern": "^code-review$" }] + } + } + } + } +} +``` + +To prevent the model from invoking a skill at all, set `disable-model-invocation: true` in that skill's `SKILL.md`. See [Skills](./skills.md#disable-model-invocation). diff --git a/docs/src/ai/tools.md b/docs/src/ai/tools.md index 9a85468f67..10913fe978 100644 --- a/docs/src/ai/tools.md +++ b/docs/src/ai/tools.md @@ -1,16 +1,20 @@ --- title: AI Agent Tools - Zed -description: Built-in tools for Zed's AI agent including file editing, code search, terminal commands, web search, and diagnostics. +description: Built-in tools for Zed's AI agent including file editing, code search, terminal commands, web search, skills, and diagnostics. --- # Tools Zed's built-in agent has access to these tools for reading, searching, and editing your codebase. These tools are used in the [Agent Panel](./agent-panel.md) during conversations with AI agents. +The exact tool list can vary by [Agent Profile](./agent-profiles.md), selected model provider, and Zed version. + You can configure permissions for tool actions, including situations where they are automatically approved, automatically denied, or require your confirmation on a case-by-case basis. See [Tool Permissions](./tool-permissions.md) for the list of permission-gated tools and details. To add custom tools beyond these built-in ones, see [MCP servers](./mcp.md). +To choose which built-in tools and MCP tools are available in a Zed Agent thread, use [Agent Profiles](./agent-profiles.md). Profiles control tool availability; tool permissions control allow, deny, and confirm behavior. + ## Read & Search Tools ### `diagnostics` @@ -45,6 +49,8 @@ Lists files and directories in a given path, providing an overview of filesystem Reads the content of a specified file in the project, allowing access to file contents. +## Web Tools + ### `search_web` Searches the web for information, providing results with snippets and links from relevant web pages, useful for accessing real-time information. @@ -89,6 +95,12 @@ Executes shell commands and returns the combined output, creating a new shell pr ## Other Tools +### `skill` + +Loads instructions from an available [Skill](./skills.md) so the agent can follow project-specific or workflow-specific guidance. Skills can also be invoked by you directly with slash commands. + +**Example:** When a repository has a skill for release-note writing, the agent can load that skill before drafting release notes so it follows the local format. + ### `spawn_agent` Spawns a subagent with its own context window to perform a delegated task. Useful for running parallel investigations, completing self-contained tasks, or performing research where only the outcome matters. Each subagent has access to the same tools as the parent agent. diff --git a/docs/src/ai/use-a-gateway.md b/docs/src/ai/use-a-gateway.md new file mode 100644 index 0000000000..400b1a2576 --- /dev/null +++ b/docs/src/ai/use-a-gateway.md @@ -0,0 +1,218 @@ +--- +title: Use a Gateway - Zed +description: Configure OpenRouter, Vercel AI Gateway, Amazon Bedrock, and other gateway or cloud model platforms in Zed. +--- + +# Use a Gateway + +Use a gateway when you route model requests through a platform such as OpenRouter, Vercel AI Gateway, Amazon Bedrock, or another OpenAI-compatible service. + +| Gateway | Zed AI features | External Agents | Terminal Threads | Notes | +| ------------------------- | --------------- | --------------- | ---------------- | -------------------------------------------- | +| OpenRouter | Yes | Separate config | Separate config | Uses OpenRouter API access | +| Vercel AI Gateway | Yes | Separate config | Separate config | Uses Vercel AI Gateway API access | +| Amazon Bedrock | Yes | Separate config | Separate config | Uses AWS credentials or Bedrock bearer token | +| OpenAI-compatible gateway | Yes | Separate config | Separate config | Configure base URL, model, and key | + +## OpenRouter {#openrouter} + +Use OpenRouter when you want to route Zed AI features through OpenRouter. + +1. Visit [OpenRouter](https://openrouter.ai) and create an account. +2. Generate an API key from your [OpenRouter keys page](https://openrouter.ai/keys). +3. Open Agent Settings with {#action agent::OpenSettings} and go to the OpenRouter section. +4. Enter your OpenRouter API key. + +Zed also reads `OPENROUTER_API_KEY` from the local Zed process environment. + +When using OpenRouter as your assistant provider, explicitly select a model in your settings: + +```json [settings] +{ + "agent": { + "default_model": { + "provider": "openrouter", + "model": "openrouter/auto" + } + } +} +``` + +The `openrouter/auto` model routes requests to an available model selected by OpenRouter. You can also specify any model available through OpenRouter's API. + +### OpenRouter Custom Models {#openrouter-custom-models} + +You can add custom models to the OpenRouter provider in settings: + +```json [settings] +{ + "language_models": { + "open_router": { + "api_url": "https://openrouter.ai/api/v1", + "available_models": [ + { + "name": "google/gemini-2.0-flash-thinking-exp", + "display_name": "Gemini 2.0 Flash (Thinking)", + "max_tokens": 200000, + "max_output_tokens": 8192, + "supports_tools": true, + "supports_images": true, + "mode": { + "type": "thinking", + "budget_tokens": 8000 + } + } + ] + } + } +} +``` + +Custom model entries support fields such as `name`, `display_name`, `max_tokens`, `max_output_tokens`, `max_completion_tokens`, `supports_tools`, `supports_images`, and `mode`. + +### OpenRouter Provider Routing {#openrouter-provider-routing} + +You can control how OpenRouter routes a custom model request among upstream providers with the `provider` object on each model entry. + +Supported fields include `order`, `allow_fallbacks`, `require_parameters`, `data_collection`, `only`, `ignore`, `quantizations`, and `sort`. + +```json [settings] +{ + "language_models": { + "open_router": { + "available_models": [ + { + "name": "openrouter/auto", + "display_name": "Auto Router", + "max_tokens": 2000000, + "supports_tools": true, + "provider": { + "order": ["anthropic", "openai"], + "allow_fallbacks": true, + "require_parameters": true, + "data_collection": "allow" + } + } + ] + } + } +} +``` + +## Vercel AI Gateway {#vercel-ai-gateway} + +Use Vercel AI Gateway when you want to route Zed AI features through Vercel. + +1. Create an API key from your Vercel AI Gateway keys page. +2. Open Agent Settings with {#action agent::OpenSettings} and go to the Vercel AI Gateway section. +3. Enter your Vercel AI Gateway API key. + +Zed also reads `VERCEL_AI_GATEWAY_API_KEY` from the local Zed process environment. + +You can set a custom endpoint for Vercel AI Gateway in settings: + +```json [settings] +{ + "language_models": { + "vercel_ai_gateway": { + "api_url": "https://ai-gateway.vercel.sh/v1" + } + } +} +``` + +## Amazon Bedrock {#amazon-bedrock} + +Use Amazon Bedrock when you want model access through AWS. + +Bedrock supports models that support streaming tool use. See [Amazon Bedrock's Tool Use documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html). + +Your AWS credentials need these permissions: + +- `bedrock:InvokeModelWithResponseStream` +- `bedrock:InvokeModel` + +Bedrock supports Zed-prefixed AWS environment variables so Zed does not override or consume your normal AWS credentials: + +- `ZED_ACCESS_KEY_ID` +- `ZED_SECRET_ACCESS_KEY` +- `ZED_SESSION_TOKEN` +- `ZED_AWS_PROFILE` +- `ZED_AWS_REGION` +- `ZED_AWS_ENDPOINT` +- `ZED_BEDROCK_BEARER_TOKEN` + +### Bedrock Authentication {#bedrock-authentication} + +You can authenticate with a named profile, static credentials, or a Bedrock API key. + +For a named profile, configure Bedrock in settings: + +```json [settings] +{ + "language_models": { + "bedrock": { + "authentication_method": "named_profile", + "region": "your-aws-region", + "profile": "your-profile-name" + } + } +} +``` + +For static credentials, open Agent Settings with {#action agent::OpenSettings}, go to the Amazon Bedrock section, and enter the access key ID, secret access key, and region. + +For a Bedrock API key, choose API key authentication: + +```json [settings] +{ + "language_models": { + "bedrock": { + "authentication_method": "api_key", + "region": "your-aws-region" + } + } +} +``` + +The API key itself is stored in the system keychain, not in `settings.json`. + +### Bedrock Cross-Region Inference {#bedrock-cross-region-inference} + +Zed uses [Cross-Region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for Bedrock on a best-effort basis. + +By default, Zed uses regional inference profiles. To opt into global profiles, add `allow_global`: + +```json [settings] +{ + "language_models": { + "bedrock": { + "authentication_method": "named_profile", + "region": "your-aws-region", + "profile": "your-profile-name", + "allow_global": true + } + } +} +``` + +Only some models support global inference profiles. See the AWS Bedrock supported models documentation for the current list. + +### Bedrock Guardrails {#bedrock-guardrails} + +Some AWS environments require a guardrail on every Bedrock API call. Add `guardrail_identifier` to apply a guardrail to all Bedrock requests: + +```json [settings] +{ + "language_models": { + "bedrock": { + "guardrail_identifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123", + "guardrail_version": "DRAFT" + } + } +} +``` + +## OpenAI-Compatible Gateways {#openai-compatible} + +If your gateway exposes an OpenAI-compatible API, configure it with [Use API Access](./use-api-access.md#openai-compatible). diff --git a/docs/src/ai/use-a-local-model.md b/docs/src/ai/use-a-local-model.md new file mode 100644 index 0000000000..7cd7836b69 --- /dev/null +++ b/docs/src/ai/use-a-local-model.md @@ -0,0 +1,110 @@ +--- +title: Use a Local Model - Zed +description: Configure Ollama, LM Studio, local OpenAI-compatible servers, and local edit prediction in Zed. +--- + +# Use a Local Model + +Use local models when you run the model on your machine or on infrastructure you control. + +| Local path | Zed AI features | External Agents | Terminal Threads | Notes | +| --------------------------------- | -------------------- | --------------- | ---------------- | -------------------------------------------------- | +| Ollama | Yes | Separate config | Separate config | Configure Ollama for Zed AI features | +| LM Studio | Yes | Separate config | Separate config | Configure LM Studio for Zed AI features | +| Local OpenAI-compatible server | Yes | Separate config | Separate config | Configure base URL, model, and key if needed | +| Local/self-hosted edit prediction | Edit Prediction only | No | No | Uses [Edit Prediction](./edit-prediction.md) setup | + +## Ollama {#ollama} + +Use Ollama for local models with Zed Agent, Inline Assistant, and similar model-backed Zed AI features. + +1. Download and install Ollama from [ollama.com/download](https://ollama.com/download). +2. Pull a model: + + ```sh + ollama pull mistral + ``` + +3. Make sure the Ollama server is running. On macOS, open Ollama.app. On Linux or from a shell, run: + + ```sh + ollama serve + ``` + +4. In Zed, select an Ollama model from the model dropdown. + +Zed automatically discovers models that Ollama has pulled. To disable autodiscovery and list models yourself, configure `auto_discover`: + +```json [settings] +{ + "language_models": { + "ollama": { + "api_url": "http://localhost:11434", + "auto_discover": false, + "available_models": [ + { + "name": "qwen2.5-coder", + "display_name": "qwen 2.5 coder", + "max_tokens": 32768, + "supports_tools": true, + "supports_thinking": true, + "supports_images": true + } + ] + } + } +} +``` + +### Ollama Context Length {#ollama-context} + +Zed requests to Ollama include context length as the `num_ctx` parameter. By default, Zed uses `4096` tokens. + +Set a context length for all Ollama models: + +```json [settings] +{ + "language_models": { + "ollama": { + "context_window": 8192 + } + } +} +``` + +You can also configure context length per model with `max_tokens` in `available_models`. + +If your Ollama server requires a key, enter the key in the provider UI or set `OLLAMA_API_KEY`. For remote Ollama services such as Ollama Turbo, set the API URL to the remote endpoint and provide an API key. + +## LM Studio {#lm-studio} + +Use LM Studio for local models with Zed Agent, Inline Assistant, and similar model-backed Zed AI features. + +1. Download and install [LM Studio](https://lmstudio.ai/download). +2. Download at least one model in LM Studio, or use the LM Studio CLI: + + ```sh + lms get qwen2.5-coder-7b + ``` + +3. Start the LM Studio API server: + + ```sh + lms server start + ``` + +4. In Zed, select an LM Studio model from the model dropdown. + +If your LM Studio server requires a key, enter the key in the provider UI or set `LMSTUDIO_API_KEY`. + +## Local OpenAI-Compatible Servers {#openai-compatible} + +Use [OpenAI-compatible endpoints](./use-api-access.md#openai-compatible) for local or self-hosted servers that expose an OpenAI-compatible API. + +## Local Edit Prediction {#edit-prediction} + +Edit Prediction has its own provider setup. See [Edit Prediction](./edit-prediction.md) for local and self-hosted edit prediction options. + +## Agent Path Boundaries {#agent-path-boundaries} + +This page covers local models configured in Zed. External Agents and terminal CLIs may have their own local-model setup; configure those in the agent or CLI. diff --git a/docs/src/ai/use-an-existing-subscription.md b/docs/src/ai/use-an-existing-subscription.md new file mode 100644 index 0000000000..4e00f0a004 --- /dev/null +++ b/docs/src/ai/use-an-existing-subscription.md @@ -0,0 +1,57 @@ +--- +title: Use an Existing Subscription - Zed +description: Use ChatGPT, Claude, Copilot, OpenCode, Cursor, and other existing AI subscriptions in Zed. +--- + +# Use an Existing Subscription + +Use this page when you already pay for an AI product and want to know how it fits into Zed. + +Some subscriptions work as Zed model providers. Others are used through an External Agent or terminal CLI. + +| Subscription | Zed AI features | External Agent via ACP | Terminal Thread | Notes | +| ----------------------------- | ---------------------------------------------------- | ------------------------------------- | ------------------------------ | ---------------------------------------------------------------- | +| Zed Pro, Business, or Student | [Zed-hosted models](../account/zed-hosted-models.md) | No | No | Billed through Zed | +| ChatGPT Plus / Pro | ChatGPT Subscription | Codex where supported | Codex CLI | Sign in with OpenAI in Zed; separate from OpenAI API keys | +| Claude Pro / Max | No direct Zed LLM provider path | Claude Agent | Claude Code | Separate from Anthropic API keys | +| GitHub Copilot | GitHub Copilot Chat; Copilot edit prediction | Copilot agent where available | CLI where available | Requires Copilot/Copilot Chat auth | +| OpenCode Zen / Go | OpenCode provider | OpenCode agent where available | `opencode` CLI | Requires OpenCode API key; subscription affects available models | +| Cursor subscription | No Zed LLM provider path | Cursor External Agent where available | Cursor CLI/TUI where available | Use agent/CLI paths instead of Zed LLM provider settings | + +## ChatGPT Plus / Pro {#chatgpt} + +ChatGPT Plus and Pro can be used through Zed's ChatGPT Subscription provider. Sign in with OpenAI in Zed; no separate OpenAI API key is required. + +OpenAI API access is separate. If you have OpenAI API credits or API billing, use [Use API Access](./use-api-access.md#openai). + +## Claude Pro / Max {#claude} + +Claude Pro and Max subscriptions are separate from Anthropic API credits. Use Claude Agent or Claude Code where supported if you want subscription-backed Claude behavior. + +For Anthropic API access, use [Use API Access](./use-api-access.md#anthropic). + +See [What Anthropic's New Claude Billing Means for Zed Users](https://zed.dev/blog/anthropic-subscription-changes) for more context. + +## GitHub Copilot {#github-copilot} + +GitHub Copilot can be used as a Copilot Chat model provider for Zed AI features where supported. Copilot can also be used for [Edit Prediction](./edit-prediction.md). + +If you use a Copilot agent or CLI, that setup is owned by Copilot. See [External Agents](./external-agents.md) and [Terminal Threads](./terminal-threads.md). + +## OpenCode Zen / Go {#opencode} + +OpenCode is a first-class language model provider in Zed. If you think of Zen or Go as your OpenCode subscription, the Zed setup path is still [Use API Access](./use-api-access.md#opencode): enter an OpenCode API key, then choose which OpenCode models to show. Zed does not sign in to OpenCode with OAuth or detect your subscription directly. + +## Cursor {#cursor} + +Cursor subscriptions do not configure Zed's LLM provider settings. Use a Cursor External Agent or Cursor CLI/TUI where available. + +## Subscriptions Used Through Agent Harnesses {#agent-harnesses} + +Some harnesses, CLIs, and External Agents can authenticate to ChatGPT, Claude, Copilot, or other subscriptions through their own flows. In those cases, Zed hosts the External Agent or Terminal Thread, but the harness owns auth and model behavior. + +Pi Coding Agent is an example: Pi is a harness, not the subscription. Configure provider auth in Pi. + +## DeepSeek {#deepseek} + +DeepSeek paid usage, top-ups, and API billing are API access in Zed, not subscription sign-in. Use [Use API Access](./use-api-access.md#deepseek). diff --git a/docs/src/ai/use-api-access.md b/docs/src/ai/use-api-access.md new file mode 100644 index 0000000000..0696bdcb59 --- /dev/null +++ b/docs/src/ai/use-api-access.md @@ -0,0 +1,454 @@ +--- +title: Use API Access - Zed +description: Configure provider API access, API keys, API credits, usage billing, and OpenAI-compatible endpoints for Zed AI features. +--- + +# Use API Access + +Use API access when a provider gives you an API key, API credits, top-ups, or usage billing. + +Paid API credits, usage billing, and top-ups are API access, even when you pay the provider directly. Use this path when the provider gives you an API key. + +## Supported API Providers {#providers} + +Zed supports these first-class API providers for model-backed Zed AI features: + +- [Anthropic](#anthropic) + - [Custom Anthropic Models](#anthropic-custom-models) +- [OpenAI API](#openai) + - [Custom OpenAI Models](#openai-custom-models) +- [Google AI](#google-ai) + - [Custom Google AI Models](#google-ai-custom-models) +- [Mistral](#mistral) + - [Custom Mistral Models](#mistral-custom-models) +- [DeepSeek](#deepseek) + - [Custom DeepSeek Models](#deepseek-custom-models) +- [xAI](#xai) + - [Custom xAI Models](#xai-custom-models) +- [OpenCode API](#opencode) + - [Custom OpenCode Models](#opencode-custom-models) +- [OpenAI-compatible endpoints](#openai-compatible) + +## What API Access Applies To {#support} + +Use API access for the Zed Agent, Inline Assistant, Git commit generation, +thread summaries, and similar Zed-owned AI features. + +External Agents and Terminal Threads usually configure model access in the +agent or CLI itself. See [Agents](./agents.md) for the difference between +agent paths and model access paths. + +## API Keys and Environment Variables {#api-keys} + +Most API-access providers can be configured in Zed's Agent Settings panel with {#action agent::OpenSettings}. Keys saved through Zed are stored in the system keychain, not in `settings.json`. + +Zed also reads provider-specific environment variables. Non-empty environment variables take precedence over keychain values. If a key comes from an environment variable, unset the variable and restart Zed to stop using it. + +| Provider | Environment variable | +| ----------------- | ----------------------------------------------------- | +| Anthropic | `ANTHROPIC_API_KEY` | +| OpenAI | `OPENAI_API_KEY` | +| Google AI | `GEMINI_API_KEY`, falling back to `GOOGLE_AI_API_KEY` | +| Mistral | `MISTRAL_API_KEY` | +| DeepSeek | `DEEPSEEK_API_KEY` | +| xAI | `XAI_API_KEY` | +| OpenCode | `OPENCODE_API_KEY` | +| OpenRouter | `OPENROUTER_API_KEY` | +| Vercel AI Gateway | `VERCEL_AI_GATEWAY_API_KEY` | +| Ollama | `OLLAMA_API_KEY` | +| LM Studio | `LMSTUDIO_API_KEY` | + +OpenAI-compatible provider environment variables are generated from the configured provider ID as upper snake case plus `_API_KEY`. For example, provider ID `my-gateway` uses `MY_GATEWAY_API_KEY`. + +## Custom Headers {#custom-headers} + +You can attach extra HTTP headers to every request Zed makes to supported HTTP-based providers. This is useful in corporate environments or for observability tooling. + +Configure them with `language_models..custom_headers`: + +```json [settings] +{ + "language_models": { + "openai": { + "custom_headers": { + "Fancy-Auth": "Bearer ", + "X-My-Tag": "zed" + } + } + } +} +``` + +`custom_headers` is supported by Amazon Bedrock, Anthropic, DeepSeek, Google AI, LM Studio, Mistral, Ollama, OpenAI, OpenAI-compatible providers, OpenCode, OpenRouter, Vercel AI Gateway, and xAI. + +Headers managed by Zed for each provider, such as `Authorization`, `Content-Type`, `Accept`, and provider-specific authentication headers, are ignored with a warning if you try to override them. + +## Remote Projects {#remote-projects} + +Zed LLM providers for Zed AI features are initialized in the local Zed app. In SSH, dev container, and other remote projects, API keys saved in Zed are read from the local system keychain, and provider environment variables are read from the local Zed process environment. + +External Agents and Terminal Threads may run their own processes and use their own remote or local environment. See [External Agents](./external-agents.md) and [Terminal Threads](./terminal-threads.md). + +## Provider Notes {#provider-notes} + +### Anthropic {#anthropic} + +Use Anthropic API access when you have an Anthropic API key or API credits. Claude Pro and Max subscriptions are separate; see [Use an Existing Subscription](./use-an-existing-subscription.md#claude). + +1. Sign up for Anthropic and [create an API key](https://console.anthropic.com/settings/keys). +2. Make sure your Anthropic account has API credits. +3. Open Agent Settings with {#action agent::OpenSettings} and go to the Anthropic section. +4. Enter your Anthropic API key. + +Zed also reads `ANTHROPIC_API_KEY` from the local Zed process environment. + +#### Custom Anthropic Models {#anthropic-custom-models} + +Add custom Anthropic models in settings when you need an alternate model ID, +display name, context window, output limit, tool override, or thinking mode. + +```json [settings] +{ + "language_models": { + "anthropic": { + "available_models": [ + { + "name": "claude-3-5-sonnet-20240620", + "display_name": "Sonnet 2024-June", + "max_tokens": 128000, + "max_output_tokens": 2560, + "tool_override": "some-model-that-supports-toolcalling" + } + ] + } + } +} +``` + +For Anthropic models that support extended thinking, add a `mode` configuration: + +```json [settings] +{ + "language_models": { + "anthropic": { + "available_models": [ + { + "name": "claude-sonnet-4-latest", + "display_name": "claude-sonnet-4-thinking", + "max_tokens": 200000, + "mode": { + "type": "thinking", + "budget_tokens": 4096 + } + } + ] + } + } +} +``` + +### OpenAI API {#openai} + +Use OpenAI API access when you have an OpenAI API key or API billing. ChatGPT Plus and Pro subscriptions use a different setup path; see [Use an Existing Subscription](./use-an-existing-subscription.md#chatgpt). + +1. Visit the OpenAI platform and [create an API key](https://platform.openai.com/account/api-keys). +2. Make sure your OpenAI account has credits or billing enabled. +3. Open Agent Settings with {#action agent::OpenSettings} and go to the OpenAI section. +4. Enter your OpenAI API key. + +Zed also reads `OPENAI_API_KEY` from the local Zed process environment. + +#### Custom OpenAI Models {#openai-custom-models} + +Add custom OpenAI models in your settings file when you need alternate model IDs, preview releases, or custom request parameters. + +```json [settings] +{ + "language_models": { + "openai": { + "available_models": [ + { + "name": "gpt-5.2", + "display_name": "gpt-5.2 high", + "reasoning_effort": "high", + "max_tokens": 272000, + "max_completion_tokens": 20000 + } + ] + } + } +} +``` + +You must provide the model's context window in `max_tokens`. For reasoning-focused models, set `max_completion_tokens` to avoid high reasoning-token costs. + +### Google AI {#google-ai} + +Use Google AI API access when you have a Gemini API key. + +1. Go to Google AI Studio and [create an API key](https://aistudio.google.com/app/apikey). +2. Open Agent Settings with {#action agent::OpenSettings} and go to the Google AI section. +3. Enter your Google AI API key. + +Zed reads `GEMINI_API_KEY`, falling back to `GOOGLE_AI_API_KEY`, from the local Zed process environment. + +#### Custom Google AI Models {#google-ai-custom-models} + +Add custom Google AI models when you need a specific Gemini model version, +including experimental models, or a thinking-mode configuration. + +```json [settings] +{ + "language_models": { + "google": { + "available_models": [ + { + "name": "gemini-3.1-pro-preview", + "display_name": "Gemini 3.1 Pro", + "max_tokens": 1000000, + "mode": { + "type": "thinking", + "budget_tokens": 24000 + } + }, + { + "name": "gemini-3-flash-preview", + "display_name": "Gemini 3 Flash (Thinking)", + "max_tokens": 1000000, + "mode": { + "type": "thinking", + "budget_tokens": 24000 + } + } + ] + } + } +} +``` + +### Mistral {#mistral} + +Use Mistral API access when you have a Mistral API key. + +1. Visit the Mistral platform and [create an API key](https://console.mistral.ai/api-keys/). +2. Open Agent Settings with {#action agent::OpenSettings} and go to the Mistral section. +3. Enter your Mistral API key. + +Zed also reads `MISTRAL_API_KEY` from the local Zed process environment. + +#### Custom Mistral Models {#mistral-custom-models} + +Add custom Mistral models when you need alternate model IDs, custom limits, tool +support, image support, or a custom endpoint. + +```json [settings] +{ + "language_models": { + "mistral": { + "api_url": "https://api.mistral.ai/v1", + "available_models": [ + { + "name": "mistral-tiny-latest", + "display_name": "Mistral Tiny", + "max_tokens": 32000, + "max_output_tokens": 4096, + "max_completion_tokens": 1024, + "supports_tools": true, + "supports_images": false + } + ] + } + } +} +``` + +### DeepSeek {#deepseek} + +Use DeepSeek API access when you have paid API usage, top-ups, or an API key. In Zed, DeepSeek is API access, not subscription sign-in. + +1. Visit the DeepSeek platform and [create an API key](https://platform.deepseek.com/api_keys). +2. Open Agent Settings with {#action agent::OpenSettings} and go to the DeepSeek section. +3. Enter your DeepSeek API key. + +Zed also reads `DEEPSEEK_API_KEY` from the local Zed process environment. + +#### Custom DeepSeek Models {#deepseek-custom-models} + +Add custom DeepSeek models when you need alternate model IDs, custom token +limits, or a custom endpoint. + +```json [settings] +{ + "language_models": { + "deepseek": { + "api_url": "https://api.deepseek.com", + "available_models": [ + { + "name": "deepseek-v4-flash", + "display_name": "DeepSeek V4 Flash", + "max_tokens": 1000000, + "max_output_tokens": 384000 + }, + { + "name": "deepseek-v4-pro", + "display_name": "DeepSeek V4 Pro", + "max_tokens": 1000000, + "max_output_tokens": 384000 + } + ] + } + } +} +``` + +### xAI {#xai} + +Use xAI API access when you have an xAI API key. + +1. [Create an API key in the xAI Console](https://console.x.ai/team/default/api-keys). +2. Open Agent Settings with {#action agent::OpenSettings} and go to the xAI section. +3. Enter your xAI API key. + +Zed also reads `XAI_API_KEY` from the local Zed process environment. + +#### Custom xAI Models {#xai-custom-models} + +Add custom xAI models when you need alternate Grok model IDs, custom limits, +image support, or a custom endpoint. + +```json [settings] +{ + "language_models": { + "x_ai": { + "api_url": "https://api.x.ai/v1", + "available_models": [ + { + "name": "grok-1.5", + "display_name": "Grok 1.5", + "max_tokens": 131072, + "max_output_tokens": 8192 + }, + { + "name": "grok-1.5v", + "display_name": "Grok 1.5V (Vision)", + "max_tokens": 131072, + "max_output_tokens": 8192, + "supports_images": true + } + ] + } + } +} +``` + +### OpenCode API {#opencode} + +Use OpenCode API access when you have an OpenCode API key. OpenCode Zen and Go affect which OpenCode models are available. + +Zed does not sign in to OpenCode with OAuth or detect your OpenCode subscription; it uses an OpenCode API key saved in the system keychain or `OPENCODE_API_KEY`. + +1. Visit [OpenCode Console](https://opencode.ai/auth) and create an account. +2. Free models are available without payment. To use Zen or Go models, make sure you have enough credits or an active subscription. +3. Generate an API key from the API Keys section in the OpenCode Console. +4. Open Agent Settings with {#action agent::OpenSettings} and go to the OpenCode section. +5. Enter your OpenCode API key. + +Zed also reads `OPENCODE_API_KEY` from the local Zed process environment. + +By default, models from all OpenCode subscription types are shown. You can hide subscriptions that are not relevant to you in the provider UI or in settings: + +```json [settings] +{ + "language_models": { + "opencode": { + "show_zen_models": true, + "show_go_models": false, + "show_free_models": false + } + } +} +``` + +**Note:** Zed only bundles configuration for long-term OpenCode Free models. Free models that are available for a limited time are not included in Zed. To use those models, add a custom OpenCode model with configuration from [the OpenCode website](https://opencode.ai/docs/zen#pricing) and [models.dev](https://github.com/anomalyco/models.dev/tree/dev/providers/opencode/models). + +#### Custom OpenCode Models {#opencode-custom-models} + +The Zed Agent comes preconfigured with OpenCode models. Add custom OpenCode models when you need newer models, limited-time Free models, or models with custom endpoints. + +Add custom models in your settings file: + +```json [settings] +{ + "language_models": { + "opencode": { + "available_models": [ + { + "name": "my-custom-model", + "display_name": "My Custom Model", + "max_tokens": 123456, + "max_output_tokens": 98765, + "protocol": "openai_chat", + "reasoning_effort_levels": ["low", "medium", "high"], + "interleaved_reasoning": false, + "subscription": "go", + "custom_model_api_url": "https://example.com/zen" + } + ] + } + } +} +``` + +The available configuration options for custom OpenCode models are: + +- `name` (required): model ID used by OpenCode, such as `glm-9000` +- `display_name` (optional): human-readable model name shown in the UI, such as `Custom GLM 9000` +- `max_tokens` (required): maximum model context window size, such as `1000000` +- `max_output_tokens` (optional): maximum tokens the model can generate, such as `64000` +- `protocol` (required): model API protocol, one of `"anthropic"`, `"openai_responses"`, `"openai_chat"`, or `"google"` +- `reasoning_effort_levels` (optional): list of supported reasoning effort levels, such as `["low", "medium", "high"]`. The last value in the list is used as the default +- `interleaved_reasoning` (optional, default `false`): whether thinking tokens are sent as a dedicated `reasoning_content` field. Applies only when using the `openai_chat` protocol +- `subscription` (optional): `"zen"`, `"go"`, or `"free"`; defaults to `"zen"` +- `custom_model_api_url` (optional): custom API base URL to use instead of the default OpenCode API + +Custom OpenCode models are listed in the model dropdown in the Agent Panel. + +### OpenAI-Compatible Endpoints {#openai-compatible} + +Use an OpenAI-compatible endpoint when you have a custom base URL, model ID, and API key. + +You can add a custom OpenAI-compatible provider from Agent Settings with {#action agent::OpenSettings}. Look for `Add Provider` in the LLM Providers section and fill in the provider name, API URL, model ID, and context window. + +You can also configure the provider in your settings file: + +```json [settings] +{ + "language_models": { + "openai_compatible": { + "my-provider": { + "api_url": "https://example.com/v1", + "available_models": [ + { + "name": "my-model", + "display_name": "My Model", + "max_tokens": 128000 + } + ] + } + } + } +} +``` + +By default, OpenAI-compatible models inherit these capabilities: + +- `tools`: `true` +- `images`: `false` +- `parallel_tool_calls`: `false` +- `prompt_cache_key`: `false` +- `chat_completions`: `true` +- `interleaved_reasoning`: `false` + +If a model only works with the Responses API, set `capabilities.chat_completions` to `false`. Zed will use the Responses endpoint for that model. + +Enter the API key in the provider settings UI or set the generated environment variable. Do not put API keys in `settings.json`. diff --git a/docs/src/ai/zed-agent.md b/docs/src/ai/zed-agent.md new file mode 100644 index 0000000000..877d4d93eb --- /dev/null +++ b/docs/src/ai/zed-agent.md @@ -0,0 +1,41 @@ +--- +title: Zed Agent +description: Use Zed's native AI agent with Zed-configured models, tools, profiles, skills, instructions, and MCP servers. +--- + +# Zed Agent + +Zed Agent is Zed's native agent path. It runs in the [Agent Panel](./agent-panel.md) and [Threads Sidebar](./parallel-agents.md#threads-sidebar), uses models configured through [LLM Providers](./llm-providers.md), and integrates with Zed's project, editor, terminal, and review surfaces. + +Use Zed Agent when you want the agent to: + +- read and search your project +- edit files +- run terminal commands +- use Zed-managed MCP tools +- follow [Agent Profiles](./agent-profiles.md) +- use Zed [Skills](./skills.md) and [Instructions](./instructions.md) +- show changes in Zed's review UI + +## What Zed Agent Uses {#what-zed-agent-uses} + +| Capability | Source of truth | +| -------------------------- | ----------------------------------------- | +| Model access | [LLM Providers](./llm-providers.md) | +| Panel workflow | [Agent Panel](./agent-panel.md) | +| Tool availability | [Agent Profiles](./agent-profiles.md) | +| Tool approval behavior | [Tool Permissions](./tool-permissions.md) | +| Built-in tools | [Tools](./tools.md) | +| External tools | [MCP](./mcp.md) | +| Reusable task instructions | [Skills](./skills.md) | +| Always-on instructions | [Instructions](./instructions.md) | + +## How It Differs from Other Agent Paths {#other-agent-paths} + +| Agent path | Main difference | +| ----------------------------------------- | -------------------------------------------------------------------------------------------- | +| [Zed Agent](./zed-agent.md) | Uses Zed's model, tool, profile, skill, instruction, and MCP configuration | +| [External Agents](./external-agents.md) | Use an ACP integration and often own auth, model, tool, and native instruction configuration | +| [Terminal Threads](./terminal-threads.md) | Run a CLI/TUI in a terminal-backed thread; the CLI owns auth and configuration | + +See [Agents](./agents.md) for the full comparison. diff --git a/docs/src/authentication.md b/docs/src/authentication.md index 59809ba410..8d0b0b7c0d 100644 --- a/docs/src/authentication.md +++ b/docs/src/authentication.md @@ -10,7 +10,7 @@ Signing in to Zed is not required. You can use most features you'd expect in a c ## What Features Require Signing In? 1. All real-time [collaboration features](./collaboration/overview.md). -2. [LLM-powered features](./ai/overview.md), if you are using Zed as the provider of your LLM models. To use AI without signing in, you can [bring and configure your own API keys](./ai/llm-providers.md#use-your-own-keys). +2. [LLM-powered features](./ai/overview.md), if you are using Zed as the provider of your LLM models. To use AI without signing in, you can [bring and configure your own API keys](./ai/use-api-access.md). ## Signing In @@ -34,7 +34,7 @@ To sign out of Zed, you can use either of these methods: Your Zed account's email address is the address provided by GitHub OAuth. If you have a public email address then it will be used, otherwise your primary GitHub email address will be used. Changes to your email address on GitHub can be synced to your Zed account by [signing in to zed.dev](https://zed.dev/sign_in). -Stripe is used for billing, and will use your Zed account's email address when starting a subscription. Changes to your Zed account email address do not currently update the email address used in Stripe. See [Updating Billing Information](./ai/billing.md#updating-billing-info) for how to change this email address. +Stripe is used for billing, and will use your Zed account's email address when starting a subscription. Changes to your Zed account email address do not currently update the email address used in Stripe. See [Updating Billing Information](./account/billing.md#updating-billing-info) for how to change this email address. ## Hiding Sign In button from the interface diff --git a/docs/src/business/admin-controls.md b/docs/src/business/admin-controls.md index 9fdc84d99f..9c28b3f09b 100644 --- a/docs/src/business/admin-controls.md +++ b/docs/src/business/admin-controls.md @@ -7,7 +7,7 @@ description: Configure AI, collaboration, and data sharing settings for your ent Owners and admins can configure settings that apply to every member of the organization. -Most controls apply server-side to anything that routes through Zed's infrastructure. Some, like the Collaboration toggle, are enforced client-side and require members to be on a minimum Zed version. These controls don't cover [bring-your-own-key (BYOK) configurations](../ai/llm-providers.md), [external agents](../ai/external-agents.md), or [third-party extensions](../extensions.md), since those work independently of Zed's servers. +Most controls apply server-side to anything that routes through Zed's infrastructure. Some, like the Collaboration toggle, are enforced client-side and require members to be on a minimum Zed version. These controls don't cover [bring-your-own-key (BYOK) configurations](../ai/llm-providers.md), [gateways](../ai/use-a-gateway.md), [local or self-hosted models](../ai/use-a-local-model.md), [External Agents](../ai/external-agents.md), [Terminal Threads](../ai/terminal-threads.md), or [third-party extensions](../extensions.md), since those work independently of Zed's servers. ## Accessing admin controls @@ -23,10 +23,10 @@ This control is configured from the Data & Privacy page in the organization dash ## Hosted AI models -The **Zed Model Provider** toggle controls whether members can use Zed's [hosted AI models](../ai/models.md): +The **Zed Model Provider** toggle controls whether members can use Zed's [hosted AI models](../account/zed-hosted-models.md): - **On:** Members can use Zed's hosted models for AI features. -- **Off:** Members must bring their own API keys via [Providers](../ai/llm-providers.md) or use [external agents](../ai/external-agents.md) for AI features. +- **Off:** Members must bring their own model access via [LLM Providers](../ai/llm-providers.md) or use [External Agents](../ai/external-agents.md) for AI features. ## Edit Predictions @@ -40,4 +40,4 @@ The **Agent Thread Feedback** toggle controls whether members can submit feedbac ## Data sharing -On Free and Pro, [data sharing with Zed for AI improvement](../ai/ai-improvement.md) is opt-in per member. On Business, it's off by default and controlled by the Agent Thread Feedback and Edit Prediction Feedback toggles above. +On Free and Pro, [AI feedback and training data sharing](../ai/ai-improvement.md) is opt-in per member. On Business, it's off by default and controlled by the Agent Thread Feedback and Edit Prediction Feedback toggles above. diff --git a/docs/src/business/overview.md b/docs/src/business/overview.md index 8c473469be..bef5468323 100644 --- a/docs/src/business/overview.md +++ b/docs/src/business/overview.md @@ -11,7 +11,7 @@ It's for teams that want modern AI tooling without security trade-offs, and for ## What's included -Members with a paid Business seat get access to all [hosted AI models](../ai/models.md) and [Edit Predictions](../ai/edit-prediction.md). +Every member gets access to all [hosted AI models](../account/zed-hosted-models.md) and [Edit Predictions](../ai/edit-prediction.md). For the organization: @@ -33,10 +33,10 @@ For the organization: without counting toward paid Business seats or receiving Business subscription AI access. - **Consolidated billing:** Your team's licenses and AI usage appear on - [one invoice](../ai/billing.md#organization), with no separate bills per member. + [one invoice](../account/billing.md#organization), with no separate bills per member. ## Getting started To set up Zed Business for your team, see [Organizations](./organizations.md). -For pricing, see [Plans & Pricing](../ai/plans-and-usage.md). +For pricing, see [Plans & Pricing](../account/plans-and-pricing.md). diff --git a/docs/src/business/privacy.md b/docs/src/business/privacy.md index ea74afac9a..eb33074beb 100644 --- a/docs/src/business/privacy.md +++ b/docs/src/business/privacy.md @@ -36,9 +36,9 @@ Neither option is available to Zed Business members. ## What data still leaves the organization -These controls cover what Zed stores and trains on. They don't change how AI inference works: when members use Zed's hosted models, prompts and code context are still sent to the relevant provider (Anthropic, OpenAI, Google, etc.) to generate responses. Zed maintains zero-data retention agreements with these providers. See [AI Improvement](../ai/ai-improvement.md#data-retention-and-training) for details. +These controls cover what Zed stores and trains on. They don't change how AI inference works: when members use Zed's hosted models, prompts and code context are still sent to the relevant provider (Anthropic, OpenAI, Google, etc.) to generate responses. Zed maintains zero-data-retention and no-training commitments with these providers. See [AI Privacy](../ai/privacy-and-security.md#data-retention-and-training) for details. -[Bring-your-own-key](../ai/llm-providers.md) and [external agents](../ai/external-agents.md) are subject to each provider's own terms; Zed has no visibility into how they handle data. +[Bring-your-own-key](../ai/llm-providers.md), [gateways](../ai/use-a-gateway.md), [local or self-hosted models](../ai/use-a-local-model.md), [External Agents](../ai/external-agents.md), and [Terminal Threads](../ai/terminal-threads.md) are subject to each provider, gateway, server, agent, or CLI's own terms. ## Additional admin controls diff --git a/docs/src/configuring-zed.md b/docs/src/configuring-zed.md index 2ca5c215ec..1ac30b9f33 100644 --- a/docs/src/configuring-zed.md +++ b/docs/src/configuring-zed.md @@ -142,5 +142,5 @@ These are useful for sharing configuration tips or linking from documentation. - [Appearance](./appearance.md) — Themes, fonts, and visual customization - [Key bindings](./key-bindings.md) — Customize keyboard shortcuts -- [AI Configuration](./ai/configuration.md) — Set up AI providers, models, and agent settings +- [AI Quick Start](./ai/quick-start.md) — Set up AI providers, models, and agent settings - [All Settings](./reference/all-settings.md) — Complete settings reference diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index 57c56528ad..a90354e1b6 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -42,6 +42,10 @@ By default, new projects open in your current window's threads sidebar. To open The command palette (`Cmd+Shift+P`) is your gateway to every action in Zed. If you forget a shortcut, search for it there. +### Panel Layout + +Use **Zed > Panel Layout > Agentic** when you want the Agent Panel and Threads Sidebar next to each other on the left. Use **Zed > Panel Layout > Classic** to restore the editor-oriented layout. + ### 3. Configure Your Editor Open the Settings Editor with `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows). Search for any setting and change it directly. diff --git a/docs/src/git.md b/docs/src/git.md index 53c7227dbb..39bfb42cb8 100644 --- a/docs/src/git.md +++ b/docs/src/git.md @@ -275,7 +275,7 @@ Zed currently supports LLM-powered commit message generation. You can ask AI to generate a commit message by focusing on the message editor within the Git Panel and either clicking on the pencil icon in the bottom left, or reaching for the {#action git::GenerateCommitMessage}, or through the {#kb git::GenerateCommitMessage} keybinding. > Note that you need to have an LLM provider configured either via your own API keys or through Zed's hosted AI models. -> Visit [the AI configuration page](./ai/configuration.md) to learn how to do so. +> Visit [AI Quick Start](./ai/quick-start.md) to learn how to configure AI. You can specify your preferred model for this task by adding a `commit_message_model` field to your agent settings. See [Feature-specific models](./ai/agent-settings.md#feature-specific-models) for more information. @@ -303,10 +303,10 @@ To add custom instructions that apply only to commit message generation, use the } ``` -These instructions are sent to the model in addition to any project rules files (such as `.rules` or `AGENTS.md`). To add instructions that apply to both commit messages and the agent more broadly, use the global `AGENTS.md` file located `~/.config/zed/AGENTS.md` on macOS and Linux, `%APPDATA%\Zed\AGENTS.md` on Windows. +These instructions are sent to the model in addition to any instruction files, such as `.rules` or `AGENTS.md`. To add instructions that apply to both commit messages and the agent more broadly, use the global `AGENTS.md` file located `~/.config/zed/AGENTS.md` on macOS and Linux, `%APPDATA%\Zed\AGENTS.md` on Windows. > Before Zed v1.4.0, this was done through the Rules Library, which has been removed. -> See [the "Migrating to Skills" docs](./ai/rules.md#migrating-to-skills) in the Rules page for more information. +> See [Migrating from Rules](./ai/instructions.md#migrating-from-rules) for more information. ## Git Integrations @@ -346,7 +346,7 @@ You can configure multiple custom providers if you work with several self-hosted Zed also has a Copy Permalink feature to create a permanent link to a code snippet on your Git hosting service. These links are useful for sharing a specific line or range of lines in a file at a specific commit. Trigger this action via the [Command Palette](./getting-started.md#command-palette) (search for `permalink`), -by creating [custom key bindings](key-bindings.md#custom-key-bindings) for the +by creating [custom key bindings](./key-bindings.md#custom-key-bindings) for the `editor::CopyPermalinkToLine` or `editor::OpenPermalinkToLine` actions or by simply right clicking and selecting `Copy Permalink` with line(s) selected in your editor. diff --git a/docs/src/migrate/intellij.md b/docs/src/migrate/intellij.md index a6a3773aff..f09b94d010 100644 --- a/docs/src/migrate/intellij.md +++ b/docs/src/migrate/intellij.md @@ -300,9 +300,9 @@ Once signed in, just start typing. Zed will offer suggestions inline for you to To use other AI models in Zed, you have several options: -- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and subscription to [Zed Pro](https://zed.dev/docs/ai/subscription.html). -- Bring your own [API keys](https://zed.dev/docs/ai/llm-providers.html), no authentication needed -- Use [external agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) +- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and access through [Zed Pro](https://zed.dev/docs/account/zed-hosted-models.html). +- Bring your own [API keys](https://zed.dev/docs/ai/use-api-access.html), no authentication needed +- Use [External Agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) ## Advanced Config and Productivity Tweaks diff --git a/docs/src/migrate/pycharm.md b/docs/src/migrate/pycharm.md index 95c37dcc9a..2e745cf7d6 100644 --- a/docs/src/migrate/pycharm.md +++ b/docs/src/migrate/pycharm.md @@ -368,9 +368,9 @@ Once signed in, just start typing. Zed will offer suggestions inline for you to To use other AI models in Zed, you have several options: -- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and subscription to [Zed Pro](https://zed.dev/docs/ai/subscription.html). -- Bring your own [API keys](https://zed.dev/docs/ai/llm-providers.html), no authentication needed -- Use [external agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) +- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and access through [Zed Pro](https://zed.dev/docs/account/zed-hosted-models.html). +- Bring your own [API keys](https://zed.dev/docs/ai/use-api-access.html), no authentication needed +- Use [External Agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) ## Advanced Config and Productivity Tweaks diff --git a/docs/src/migrate/rustrover.md b/docs/src/migrate/rustrover.md index 883b3915d2..93b54efa1b 100644 --- a/docs/src/migrate/rustrover.md +++ b/docs/src/migrate/rustrover.md @@ -369,9 +369,9 @@ Once signed in, just start typing. Zed will offer suggestions inline for you to To use other AI models in Zed, you have several options: -- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and subscription to [Zed Pro](https://zed.dev/docs/ai/subscription.html). -- Bring your own [API keys](https://zed.dev/docs/ai/llm-providers.html), no authentication needed -- Use [external agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) +- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and access through [Zed Pro](https://zed.dev/docs/account/zed-hosted-models.html). +- Bring your own [API keys](https://zed.dev/docs/ai/use-api-access.html), no authentication needed +- Use [External Agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) ## Advanced Config and Productivity Tweaks diff --git a/docs/src/migrate/vs-code.md b/docs/src/migrate/vs-code.md index d8bffb1ecb..5bc8db48a2 100644 --- a/docs/src/migrate/vs-code.md +++ b/docs/src/migrate/vs-code.md @@ -329,9 +329,9 @@ Once signed in, just start typing. Zed will offer suggestions inline for you to To use other AI models in Zed, you have several options: -- Use Zed’s hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and subscription to [Zed Pro](https://zed.dev/docs/ai/subscription.html). -- Bring your own [API keys](https://zed.dev/docs/ai/llm-providers.html), no authentication needed -- Use [external agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html). +- Use Zed’s hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and access through [Zed Pro](https://zed.dev/docs/account/zed-hosted-models.html). +- Bring your own [API keys](https://zed.dev/docs/ai/use-api-access.html), no authentication needed +- Use [External Agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html). ### Advanced Config and Productivity Tweaks diff --git a/docs/src/migrate/webstorm.md b/docs/src/migrate/webstorm.md index 0aa9c43f16..023f8e2a59 100644 --- a/docs/src/migrate/webstorm.md +++ b/docs/src/migrate/webstorm.md @@ -362,9 +362,9 @@ Once signed in, just start typing. Zed will offer suggestions inline for you to To use other AI models in Zed, you have several options: -- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and subscription to [Zed Pro](https://zed.dev/docs/ai/subscription.html). -- Bring your own [API keys](https://zed.dev/docs/ai/llm-providers.html), no authentication needed -- Use [external agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) +- Use Zed's hosted models, with higher rate limits. Requires [authentication](https://zed.dev/docs/authentication) and access through [Zed Pro](https://zed.dev/docs/account/zed-hosted-models.html). +- Bring your own [API keys](https://zed.dev/docs/ai/use-api-access.html), no authentication needed +- Use [External Agents like Claude Agent](https://zed.dev/docs/ai/external-agents.html) ## Advanced Config and Productivity Tweaks diff --git a/docs/src/reference/all-settings.md b/docs/src/reference/all-settings.md index 9993151954..511b4ffa4e 100644 --- a/docs/src/reference/all-settings.md +++ b/docs/src/reference/all-settings.md @@ -5307,7 +5307,7 @@ Run the {#action theme_selector::Toggle} action in the command palette to see a ## Agent -Visit [the Configuration page](../ai/configuration.md) under the AI section to learn more about all the agent-related settings. +Visit [AI Quick Start](../ai/quick-start.md) under the AI section to learn more about AI setup. ## Collaboration Panel diff --git a/docs/src/telemetry.md b/docs/src/telemetry.md index 89bc18d79c..dd0f75f8cc 100644 --- a/docs/src/telemetry.md +++ b/docs/src/telemetry.md @@ -60,13 +60,13 @@ For the full list of event types, see the `Event` enum in [telemetry_events.rs]( ### Server-Side Metrics -When using Zed's hosted services, we collect metadata for rate limiting and billing (e.g., token usage). Zed does not store your prompts or code unless you explicitly share them via feedback ratings. +When using Zed's hosted services, we collect metadata for rate limiting and billing (e.g., token usage). Zed does not store your prompts or code unless you explicitly share feedback or opt into Edit Prediction training data collection. -For details on AI data handling, see [Zed AI Features and Privacy](./ai/ai-improvement.md). +For details on AI request paths and opt-in data sharing, see [AI Privacy](./ai/privacy-and-security.md) and [Feedback and Training Data](./ai/ai-improvement.md). ## Zed Business -Administrators on Zed Business can enforce a no-sharing policy org-wide; members can't opt into [edit prediction training data sharing](./ai/ai-improvement.md#edit-predictions) or [AI feedback ratings](./ai/ai-improvement.md#ai-feedback-with-ratings). See [Data Sharing](./business/admin-controls.md#data-sharing) in Admin Controls. +Administrators on Zed Business can enforce a no-sharing policy org-wide; members can't opt into [Edit Prediction training data sharing](./ai/ai-improvement.md#edit-predictions) or [AI feedback ratings](./ai/ai-improvement.md#ai-feedback-with-ratings). See [Data Sharing](./business/admin-controls.md#data-sharing) in Admin Controls. diff --git a/docs/src/windows-and-projects.md b/docs/src/windows-and-projects.md index 32f23bea41..ff7aa0fb9c 100644 --- a/docs/src/windows-and-projects.md +++ b/docs/src/windows-and-projects.md @@ -7,6 +7,8 @@ description: "How Zed handles multiple projects in windows, including the thread Zed lets you work on multiple projects in a single window. Projects appear in the threads sidebar on the left, and you can switch between them while keeping your context intact. +Use **Zed > Panel Layout > Agentic** to keep the Threads Sidebar and Agent Panel together on the left. Use **Zed > Panel Layout > Classic** to restore the editor-oriented layout. + ## How Projects Open By default, when you open a folder in Zed, it opens as a new project in your current window's threads sidebar rather than creating a new window. This keeps related work together and preserves your agent threads and layout.