Danilo Leal and Zed Zippy created
Updating content with more detailed information, cross-linking pages
when useful (primarily the new docs for tool permissions), rearranging
information architecture a bit (e.g., putting examples last and
guidelines first, putting text threads vs. threads disclaimer above
everything, etc.), removing outdated images, etc.
Release Notes:
- N/A
---------
Co-authored-by: Zed Zippy <234243425+zed-zippy[bot]@users.noreply.github.com>crates/settings_ui/src/pages/tool_permissions_setup.rs | 2
docs/src/ai/agent-panel.md | 57 ++-
docs/src/ai/configuration.md | 8
docs/src/ai/mcp.md | 24 -
docs/src/ai/rules.md | 31 +
docs/src/ai/text-threads.md | 72 ++---
docs/src/ai/tool-permissions.md | 148 ++++++-----
7 files changed, 181 insertions(+), 161 deletions(-)
@@ -1070,7 +1070,7 @@ fn render_global_default_mode_section(current_mode: ToolPermissionMode) -> AnyEl
let mode_label = current_mode.to_string();
h_flex()
- .mt_4()
+ .my_4()
.justify_between()
.child(
v_flex()
@@ -5,7 +5,8 @@ description: Use Zed's AI coding agent to generate, refactor, and debug code wit
# Agent Panel
-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.
+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 `agent: new thread` from [the Command Palette](../getting-started.md#command-palette) or click the ✨ icon in the status bar.
@@ -20,11 +21,14 @@ You can do that by:
## Overview {#overview}
-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.
+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.
+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 Code](./external-agents.md#claude-code), some of the features outlined below may _not_ be supported—for example, _restoring threads from history_, _checkpoints_, _token usage display_, and others. Their availability varies depending on the agent.
+> Note that for external agents, like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Code](./external-agents.md#claude-code), some of the features outlined below may _not_ be supported—for example, _restoring threads from history_, _checkpoints_, _token usage display_, and others.
+> Their availability varies depending on the agent.
### Creating New Threads {#new-thread}
@@ -63,7 +67,7 @@ Right-click on any agent response in the thread view to access a context menu wi
### Navigating the Thread {#navigating-the-thread}
-In long conversations, use the scroll button at the bottom of the panel to jump to your most recent prompt.
+In long conversations, use the scroll arrow buttons at the bottom of the panel to jump to your most recent prompt or to the very beginning of the thread.
### Navigating History {#navigating-history}
@@ -72,11 +76,13 @@ Doing that will open a dropdown that shows you your six most recently updated th
To view all historical conversations, reach for the `View All` option from within the same menu or via the {#kb agent::OpenHistory} binding.
-Thread titles are auto-generated based on the conversation content. To regenerate a title, open the ellipsis menu in the top right of the panel and select "Regenerate Thread Title".
+Thread titles are auto-generated based on the content of the conversation.
+But you can also edit them manually by clicking the title and typing, or regenerate them by clicking the "Regenerate Thread Title" button in the ellipsis menu in the top right of the panel.
### Following the Agent {#following-the-agent}
-Follow the agent as it reads and edits files by clicking the crosshair icon at the bottom left of the panel. Your editor will jump to each file the agent touches.
+Follow the agent as it reads and edits files by clicking the crosshair icon at the bottom left of the panel.
+Your editor will jump to each file the agent touches.
You can also hold `cmd`/`ctrl` when submitting a message to automatically follow.
@@ -105,7 +111,8 @@ You can turn this off, though, through the `agent.single_file_review` setting.
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, rules files, and diagnostics.
+Add context by typing `@` in the message editor.
+You can mention files, directories, symbols, previous threads, rules files, and diagnostics.
Copying images and pasting them in the panel's message editor is also supported.
@@ -114,7 +121,7 @@ To paste content without this automatic formatting, use {#kb agent::PasteRaw} to
### Selection as Context
-Additionally, you can also select text in a buffer and add it as context by using the {#kb agent::AddSelectionToThread} keybinding, running the {#action agent::AddSelectionToThread} action, or choosing the "Selection" item in the `@` menu.
+Additionally, you can also select text in a buffer or terminal and add it as context by using the {#kb agent::AddSelectionToThread} keybinding, running the {#action agent::AddSelectionToThread} action, or choosing the "Selection" item in the `+` menu in the message editor.
## Token Usage {#token-usage}
@@ -139,7 +146,7 @@ Cycle through your favorites with {#kb agent::CycleFavoriteModels} without openi
## Using Tools {#using-tools}
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 fetching web content.
+Zed includes several [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).
@@ -150,9 +157,12 @@ Zed offers three built-in profiles and you can create as many custom ones as you
#### 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.
+- `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.
@@ -174,9 +184,10 @@ All custom profiles can be edited via the UI or by hand under the `agent.profile
To delete a custom profile, open the Agent Profile modal, select the profile you want to remove, and click the delete button.
-### Tool Approval
+### 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:
@@ -184,18 +195,18 @@ Zed's Agent Panel provides the `agent.tool_permissions.default` setting to contr
- `"allow"` — Auto-approves tool actions without prompting
- `"deny"` — Blocks all tool actions
-You can change this in either your `settings.json` or via the Agent Panel's settings view.
+When the agent requests permission for an action, the confirmation menu includes options to allow or deny once, plus "Always for <tool>" 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. For the `copy_path` and `move_path` tools, patterns are matched independently against both the source and destination paths. See [Per-tool Permission Rules](./agent-settings.md#per-tool-permission-rules) for details.
+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.
-When the agent requests permission for an action, the confirmation dialog includes options to allow or deny once, plus "Always for <tool>" 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.
-
-> **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 (including MCP tools).
+Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details.
### Model Support {#model-support}
Tool calling needs to be individually supported by each model and model provider.
-Therefore, despite the presence of tools, some models may not have the ability to pick them up yet in Zed.
+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.
@@ -226,8 +237,10 @@ 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.
-> **_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.
+> **_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.
-The best way you can help influence the next change to Zed's system prompt and tools is by rating the LLM's response via the thumbs up/down buttons at the end of every response. In case of a thumbs down, a new text area will show up where you can add more specifics about what happened.
+The best way you can help influence the next change to Zed's system prompt and tools is by rating the LLM's response via the thumbs up/down buttons at the end of every response.
+In case of a thumbs down, a new text area will show up where you can add more specifics about what happened.
You can provide feedback on the thread at any point after the agent responds, and multiple times within the same thread.
@@ -5,12 +5,12 @@ description: Set up AI in Zed with hosted models, your own API keys, or external
# Configuration
-Zed is an AI code editor with flexible configuration. You can configure multiple dimensions:
+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
- - Using [external agents like Claude Code](./external-agents.md), which do not
+ - [Using your own API keys](./llm-providers.md), which do not require the above
+ - Using [external agents like Claude Code](./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)
@@ -24,4 +24,4 @@ To disable all AI features, add the following to your `settings.json`:
}
```
-See [this blog post](https://zed.dev/blog/disable-ai-features) for background on this option.
+See [this blog post](https://zed.dev/blog/disable-ai-features) for further context on this option.
@@ -29,7 +29,7 @@ Many MCP servers are available as extensions. Find them via:
2. in the app, open the Command Palette and run the `zed: extensions` action
3. in the app, go to the Agent Panel's top-right menu and look for the "View Server Extensions" menu item
-Popular servers:
+Popular servers available as an extension include:
- [Context7](https://zed.dev/extensions/context7-mcp-server)
- [GitHub](https://zed.dev/extensions/github-mcp-server)
@@ -84,9 +84,10 @@ If not, other colors and tooltip messages will indicate what is happening.
Once installation is complete, you can return to the Agent Panel and start prompting.
-Model support for MCP tools varies. Mentioning your server by name in prompts helps the model select the right tools.
+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.
+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.
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):
@@ -133,9 +134,10 @@ As an example, [the Dagger team suggests](https://container-use.com/agent-integr
}
```
-### Tool Approval
+### Tool Permissions
-> **Note:** In Zed v0.224.0 and above, tool approval for the native Zed agent is controlled by `agent.tool_permissions.default`.
+> **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 for the native Zed agent:
@@ -143,15 +145,11 @@ Zed's Agent Panel provides the `agent.tool_permissions.default` setting to contr
- `"allow"` — Auto-approves tool actions without prompting
- `"deny"` — Blocks all tool actions
-You can change this in either your `settings.json` or through the Agent Panel settings.
+For granular control over specific MCP tools, you can configure per-tool permission rules.
+MCP tools use the key format `mcp:<server>:<tool_name>` — for example, `mcp:github:create_issue`.
+The `default` key on a per-tool entry is the primary mechanism for MCP tools, since pattern-based rules match against an empty string for MCP tools and most patterns won't match.
-Even with `"default": "allow"`, per-tool `always_deny` and `always_confirm` patterns are still respected, so you can auto-approve most actions while still blocking or gating sensitive ones.
-
-For granular control over specific MCP tools, you can configure per-tool permission rules. MCP tools use the key format `mcp:<server>:<tool_name>` — for example, `mcp:github:create_issue`. The `default` key on a per-tool entry is the primary mechanism for MCP tools, since pattern-based rules match against an empty string for MCP tools and most patterns won't match.
-
-See [Per-tool Permission Rules](./agent-settings.md#per-tool-permission-rules) and [Tool Permissions](./tool-permissions.md) for 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 MCP tool calls.
+Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details.
### External Agents
@@ -5,11 +5,12 @@ description: Configure AI behavior in Zed with .rules files, .cursorrules, CLAUD
# Using Rules {#using-rules}
-Rules are prompts inserted at the beginning of each [Agent Panel](./agent-panel.md) interaction. Add them via files in your worktree (`.rules`, etc.) or through the Rules Library for reuse across projects and threads.
+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` files
-Zed supports including `.rules` files at the top level of worktrees, and they act as project-level instructions that are included in all of your interactions with the Agent Panel.
+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.
+
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:
- `.rules`
@@ -24,9 +25,10 @@ Other names for this file are also supported for compatibility with other agents
## 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.
+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 use the inline assistant right in the rules editor, allowing you to automate and rewrite rules.
+You can also use the inline assistant right in the rules editor, allowing you to get quick LLM support for writing rules.
### Opening the Rules Library
@@ -34,30 +36,35 @@ You can use the inline assistant right in the rules editor, allowing you to auto
2. Click on the Agent menu (`...`) in the top right corner.
3. Select `Rules...` from the dropdown.
-You can also reach it by running {#action agent::OpenRulesLibrary} in the command palette or through the {#kb agent::OpenRulesLibrary} keybinding.
+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.
+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.
+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)
-### Editing the Default Rules {#default-rules}
+### 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}
-Zed allows you to customize the default rules used when interacting with LLMs.
-Or to be more precise, it uses a series of rules that are combined to form the 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.
-Default rules are included in the context of every new thread automatically.
-You can also manually add other rules (that are not flagged as default) as context using the `@rule` command.
+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 from Prompt Library
@@ -5,44 +5,43 @@ description: Chat with LLMs directly in your editor with Zed's text threads. Ful
# Text Threads
-## Overview {#overview}
+Text threads in the [Agent Panel](./agent-panel.md) work like a regular editor.
+You can use custom keybindings, multiple cursors, and all the standard editing features while chatting.
-Text threads in the [Agent Panel](./agent-panel.md) work like a regular editor. You can use custom keybindings, multiple cursors, and all standard editing features.
-
-Text threads organize content into message blocks with roles:
-
-- `You`
-- `Assistant`
-- `System`
-
-To begin, type a message in a `You` block.
+## Text Threads vs. Threads
-
+Text Threads were Zed's original AI interface.
+In May 2025, Zed introduced the current [Agent Panel](./agent-panel.md), optimized for agentic workflows.
-As you type, the remaining tokens count for the selected model is updated.
+The key difference: text threads don't support tool calls and many other more moden agentic features.
+They can't autonomously read files, write code, or run commands on your behalf.
+Text Threads are for simpler conversational interactions where you send text and receive text responses back.
-Inserting text from an editor is as simple as highlighting the text and running `agent: add selection to thread` ({#kb agent::AddSelectionToThread}); Zed will wrap it in a fenced code block if it is code.
+Therefore, [MCP servers](./mcp.md) and [external agents](./external-agents.md) are also not available in Text Threads.
-
+## Usage Overview
-To submit a message, use {#kb assistant::Assist}(`assistant: assist`).
-In text threads, {#kb editor::Newline} inserts a new line rather than submitting. This preserves standard editor behavior.
+Text threads organize content into message blocks with roles:
-After submitting a message, the response will be streamed below, in an `Assistant` message block.
+- `You`
+- `Assistant`
+- `System`
-
+To begin, type your message in a `You` block.
+As you type, the remaining token count for the selected model updates automatically.
-The stream can be canceled at any point with <kbd>escape</kbd>.
-This is useful if you realize early on that the response is not what you were looking for.
+To add context from an editor, highlight text and run `agent: add selection to thread` ({#kb agent::AddSelectionToThread}).
+If the selection is code, Zed will wrap it in a fenced code block.
-If you want to start a new conversation at any time, you can hit <kbd>cmd-n|ctrl-n</kbd> or use the `New Chat` menu option in the hamburger menu at the top left of the panel.
+To submit a message, use {#kb assistant::Assist} (`assistant: assist`).
+In text threads, {#kb editor::Newline} inserts a new line instead of submitting, which preserves standard editor behavior.
-Text threads support straightforward conversations, but you can also go back and modify earlier messages to change direction.
+After you submit a message, the response is streamed below in an `Assistant` message block.
+You can cancel the stream at any point with <kbd>escape</kbd>, or start a new conversation at any time via <kbd>cmd-n|ctrl-n</kbd>.
-## Editing a Text Thread {#edit-text-thread}
+Text threads support straightforward conversations, but you can also go back and edit earlier messages—including previous LLM responses—to change direction, refine context, or correct mistakes without starting a new thread or spending tokens on follow-up corrections.
+If you want to remove a message block entirely, place your cursor at the beginning of the block and use the `delete` key.
-You can edit any text in a thread, including previous LLM responses.
-If you want to remove a message block entirely, simply place your cursor at the beginning of the block and use the `delete` key.
A typical workflow might involve making edits and adjustments throughout the context to refine your inquiry or provide additional information.
Here's an example:
@@ -54,14 +53,7 @@ Here's an example:
6. Add additional context to your original message.
7. Submit the message with {#kb assistant::Assist}.
-Being able to edit previous messages gives you control over how tokens are used.
-You don't need to start up a new chat to correct a mistake or to add additional information, and you don't have to waste tokens by submitting follow-up corrections.
-
-> **Note**: The act of editing past messages is often referred to as "Rewriting History" in the context of the language models.
-
-Some additional points to keep in mind:
-
-- You can cycle the role of a message block by clicking on the role, which is useful when you receive a response in an `Assistant` block that you want to edit and send back up as a `You` block.
+You can also cycle the role of a message block by clicking on the role, which is useful when you receive a response in an `Assistant` block that you want to edit and send back up as a `You` block.
## Commands Overview {#commands}
@@ -161,7 +153,11 @@ Usage: `/selection`
[Commands](#commands) can be used in rules, in the Rules Library (previously known as Prompt Library), to insert dynamic content or perform actions.
For example, if you want to create a rule where it is important for the model to know the date, you can use the `/now` command to insert the current date.
-> **Warn:** Slash commands in rules **only** work when they are used in text threads. Using them in non-text threads is not supported.
+<div class="warning">
+
+Slash commands in rules **only** work when they are used in text threads. Using them in non-text threads is not supported.
+
+</div>
> **Note:** Slash commands in rules **must** be on their own line.
@@ -219,14 +215,6 @@ Additional slash commands can be provided by extensions.
See [Extension: Slash Commands](../extensions/slash-commands.md) to learn how to create your own.
-## Text Threads vs. Threads
-
-Text threads were Zed's original AI interface. In May 2025, Zed introduced the current [Agent Panel](./agent-panel.md), optimized for readability and agentic workflows.
-
-The key difference: text threads don't support tool calls. They can't read files, write code, or run commands on your behalf. Text threads are for conversational interaction where you only receive text responses.
-
-[MCP servers](./mcp.md) and [external agents](./external-agents.md) are not available in text threads.
-
## Advanced Concepts
### Rule Templates {#rule-templates}
@@ -1,14 +1,14 @@
# Tool Permissions
-Configure which [Agent Panel](./agent-panel.md) actions run automatically and which require your approval. For a list of available tools, see [Tools](./tools.md).
+Configure which [Agent Panel](./agent-panel.md) tools run automatically and which require your approval.
+For a list of available tools, [see the Tools page](./tools.md).
-> **Note:** In Zed v0.224.0 and above, this page documents the granular `agent.tool_permissions` system.
->
-> **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.
+> **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`).
## Quick Start
-You can use Zed's Settings UI to configure tool permissions, or add rules directly to your `settings.json`:
+Use Zed's Settings Editor to [configure tool permissions](zed://settings/agent.tool_permissions), or add rules directly to your `settings.json`:
```json [settings]
{
@@ -30,7 +30,8 @@ You can use Zed's Settings UI to configure tool permissions, or add rules direct
}
```
-This example auto-approves `cargo` and `npm` commands in the terminal tool, while requiring manual confirmation on a case-by-case basis for `sudo` commands. Non-terminal commands follow the global `"default": "allow"` setting, but tool-specific defaults and `always_confirm` rules can still prompt.
+This example auto-approves `cargo` and `npm` commands in the terminal tool, while requiring manual confirmation on a case-by-case basis for `sudo` commands.
+Non-terminal commands follow the global `"default": "allow"` setting, but tool-specific defaults and `always_confirm` rules can still prompt.
## How It Works
@@ -55,7 +56,8 @@ The `tool_permissions` setting lets you customize tool permissions by specifying
| `fetch` | The URL |
| `web_search` | The search query |
-For MCP tools, use the format `mcp:<server>:<tool_name>`. For example, a tool called `create_issue` on a server called `github` would be `mcp:github:create_issue`.
+For MCP tools, use the format `mcp:<server>:<tool_name>`.
+For example, a tool called `create_issue` on a server called `github` would be `mcp:github:create_issue`.
## Configuration
@@ -95,18 +97,83 @@ For MCP tools, use the format `mcp:<server>:<tool_name>`. For example, a tool ca
}
```
-Patterns use Rust regex syntax. Matching is case-insensitive by default.
+Patterns use Rust regex syntax.
+Matching is case-insensitive by default.
## Rule Precedence
From highest to lowest priority:
-1. **Built-in security rules** — Hardcoded protections (e.g., `rm -rf /`). Cannot be overridden.
-2. **`always_deny`** — Blocks matching actions
-3. **`always_confirm`** — Requires confirmation for matching actions
-4. **`always_allow`** — Auto-approves matching actions
-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` when no tool-specific default is set
+1. **Built-in security rules**: Hardcoded protections (e.g., `rm -rf /`). Cannot be overridden.
+2. **`always_deny`**: Blocks matching actions
+3. **`always_confirm`**: Requires confirmation for matching actions
+4. **`always_allow`**: Auto-approves matching actions
+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` when no tool-specific default is set
+
+## Global Auto-Approve
+
+To auto-approve all tool actions:
+
+```json [settings]
+{
+ "agent": {
+ "tool_permissions": {
+ "default": "allow"
+ }
+ }
+}
+```
+
+This bypasses confirmation prompts for most tools, but `always_deny`, `always_confirm`, built-in security rules, and paths inside Zed settings directories still prompt or block.
+
+## Shell Compatibility
+
+For the `terminal` tool, Zed parses chained commands (e.g., `echo hello && rm file`) to check each sub-command against your patterns.
+
+All supported shells work with tool permission patterns, including sh, bash, zsh, dash, fish, PowerShell 7+, pwsh, cmd, xonsh, csh, tcsh, Nushell, Elvish, and rc (Plan 9).
+
+## Writing Patterns
+
+- Use `\b` for word boundaries: `\brm\b` matches "rm" but not "storm"
+- Use `^` and `$` to anchor patterns to start/end of input
+- Escape special characters: `\.` for literal dot, `\\` for backslash
+
+<div class="warning">
+
+Test carefully—a typo in a deny pattern blocks legitimate actions.
+You can use the "Test Your Rules" checker, available in each individual tool page, to confirm whether a pattern is correctly falling in the desired condition.
+
+</div>
+
+## Built-in Security Rules
+
+Zed includes a small set of hardcoded security rules that **cannot be overridden** by any setting.
+These only apply to the **terminal** tool and block recursive deletion of critical directories:
+
+- `rm -rf /` and `rm -rf /*` — filesystem root
+- `rm -rf ~` and `rm -rf ~/*` — home directory
+- `rm -rf $HOME` / `rm -rf ${HOME}` (and `$HOME/*`) — home directory via environment variable
+- `rm -rf .` and `rm -rf ./*` — current directory
+- `rm -rf ..` and `rm -rf ../*` — parent directory
+
+These patterns catch any flag combination (e.g., `-fr`, `-rfv`, `-r -f`, `--recursive --force`) and are case-insensitive.
+They are checked against both the raw command and each parsed sub-command in chained commands (e.g., `ls && rm -rf /`).
+
+There are no other built-in rules.
+The default settings file ({#action zed::OpenDefaultSettings}) includes commented-out examples for protecting `.env` files, secrets directories, and private keys — you can uncomment or adapt these to suit your needs.
+
+## Permission Request in the UI
+
+When the agent requests permission, you'll see in the thread view a tool card with a menu that includes:
+
+- **Allow once** / **Deny once** — One-time decision
+- **Always for <tool>** — Sets a tool-level default to allow or deny
+- **Always for <pattern>** — Adds an `always_allow` or `always_deny` pattern (when a safe pattern can be extracted)
+
+Selecting "Always for <tool>" sets `tools.<tool>.default` to allow or deny.
+When a pattern can be safely extracted, selecting "Always for <pattern>" adds an `always_allow` or `always_deny` rule for that input.
+MCP tools only support the tool-level option.
## Examples
@@ -227,56 +294,3 @@ From highest to lowest priority:
}
}
```
-
-## Global Auto-Approve
-
-To auto-approve all tool actions:
-
-```json [settings]
-{
- "agent": {
- "tool_permissions": {
- "default": "allow"
- }
- }
-}
-```
-
-This bypasses confirmation prompts for most actions, but `always_deny`, `always_confirm`, built-in security rules, and paths inside Zed settings directories still prompt or block.
-
-## Shell Compatibility
-
-For the `terminal` tool, Zed parses chained commands (e.g., `echo hello && rm file`) to check each sub-command against your patterns.
-
-All supported shells work with tool permission patterns, including sh, bash, zsh, dash, fish, PowerShell 7+, pwsh, cmd, xonsh, csh, tcsh, Nushell, Elvish, and rc (Plan 9).
-
-## Writing Patterns
-
-- Use `\b` for word boundaries: `\brm\b` matches "rm" but not "storm"
-- Use `^` and `$` to anchor patterns to start/end of input
-- Escape special characters: `\.` for literal dot, `\\` for backslash
-- Test carefully—a typo in a deny pattern blocks legitimate actions
-
-## Built-in Security Rules
-
-Zed includes a small set of hardcoded security rules that **cannot be overridden** by any setting. These only apply to the **terminal** tool and block recursive deletion of critical directories:
-
-- `rm -rf /` and `rm -rf /*` — filesystem root
-- `rm -rf ~` and `rm -rf ~/*` — home directory
-- `rm -rf $HOME` / `rm -rf ${HOME}` (and `$HOME/*`) — home directory via environment variable
-- `rm -rf .` and `rm -rf ./*` — current directory
-- `rm -rf ..` and `rm -rf ../*` — parent directory
-
-These patterns catch any flag combination (e.g., `-fr`, `-rfv`, `-r -f`, `--recursive --force`) and are case-insensitive. They are checked against both the raw command and each parsed sub-command in chained commands (e.g., `ls && rm -rf /`).
-
-There are no other built-in rules. The default settings file ({#action zed::OpenDefaultSettings}) includes commented-out examples for protecting `.env` files, secrets directories, and private keys — you can uncomment or adapt these to suit your needs.
-
-## UI Options
-
-When the agent requests permission, the dialog includes:
-
-- **Allow once** / **Deny once** — One-time decision
-- **Always for <tool>** — Sets a tool-level default to allow or deny
-- **Always for <pattern>** — Adds an `always_allow` or `always_deny` pattern (when a safe pattern can be extracted)
-
-Selecting "Always for <tool>" sets `tools.<tool>.default` to allow or deny. When a pattern can be safely extracted, selecting "Always for <pattern>" adds an `always_allow` or `always_deny` rule for that input. MCP tools only support the tool-level option.