1---
  2title: AI Coding Agent - Zed Agent Panel
  3description: Use Zed's AI coding agent to generate, refactor, and debug code with tool calling, checkpoints, and multi-model support.
  4---
  5
  6# Agent Panel
  7
  8The Agent Panel is where you interact with AI agents that can read, write, and run code in your project. Use it for code generation, refactoring, debugging, documentation, and general questions.
  9
 10Open it with `agent: new thread` from [the Command Palette](../getting-started.md#command-palette) or click the ✨ icon in the status bar.
 11
 12## Getting Started {#getting-started}
 13
 14If you're using the Agent Panel for the first time, you need to have at least one LLM provider or external agent configured.
 15You can do that by:
 16
 171. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models
 182. [using your own API keys](./llm-providers.md#use-your-own-keys), either from model providers like Anthropic or model gateways like OpenRouter.
 193. using an [external agent](./external-agents.md) like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Code](./external-agents.md#claude-code)
 20
 21## Overview {#overview}
 22
 23With 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.
 24
 25Responses stream in with indicators showing [which tools](./tools.md) the model is using. The sections below cover what you can do from here.
 26
 27> 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.
 28
 29### Creating New Threads {#new-thread}
 30
 31By default, the Agent Panel uses Zed's first-party agent.
 32
 33To choose another agent, go to the plus button in the top-right of the Agent Panel and pick either one of the [external agents](./external-agents.md) installed out of the box or a new [Text Thread](./text-threads.md).
 34
 35### Editing Messages {#editing-messages}
 36
 37Any message that you send to the model is editable.
 38You can click on the card that contains your message and re-submit it with an adjusted prompt and/or new pieces of context.
 39
 40### Queueing Messages
 41
 42Messages sent while the agent is in the generating state get, by default, queued.
 43
 44For 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.
 45
 46You can edit or remove (an individual or all) queued messages.
 47You 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.
 48
 49### Checkpoints {#checkpoints}
 50
 51Every time the model performs an edit, you should see a "Restore Checkpoint" button at the top of your message, allowing you to return your code base to the state it was in prior to that message.
 52
 53The checkpoint button appears even if you interrupt the thread midway through an edit, as this is likely a moment when you've identified that the agent is not heading in the right direction and you want to revert back.
 54
 55### Context Menu {#context-menu}
 56
 57Right-click on any agent response in the thread view to access a context menu with the following actions:
 58
 59- **Copy Selection**: Copies the currently selected text as Markdown (available when text is selected).
 60- **Copy This Agent Response**: Copies the full text of the agent response you right-clicked on.
 61- **Scroll to Top / Scroll to Bottom**: Scrolls to the beginning or end of the thread, depending on your current position.
 62- **Open Thread as Markdown**: Opens the entire thread as a Markdown file in a new tab.
 63
 64### Navigating the Thread {#navigating-the-thread}
 65
 66In long conversations, use the scroll button at the bottom of the panel to jump to your most recent prompt.
 67
 68### Navigating History {#navigating-history}
 69
 70To quickly navigate through recently updated threads, use the {#kb agent::ToggleNavigationMenu} binding when focused on the panel's editor, or click the menu icon button at the top right of the panel.
 71Doing that will open a dropdown that shows you your six most recently updated threads.
 72
 73To view all historical conversations, reach for the `View All` option from within the same menu or via the {#kb agent::OpenHistory} binding.
 74
 75Thread 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".
 76
 77### Following the Agent {#following-the-agent}
 78
 79Follow 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.
 80
 81You can also hold `cmd`/`ctrl` when submitting a message to automatically follow.
 82
 83### Get Notified {#get-notified}
 84
 85If you send a prompt to the Agent and then put Zed in the background, you can choose to be notified when its generation wraps up via:
 86
 87- a visual notification that appears in the top right of your screen
 88- a sound notification
 89
 90These notifications can be used together or individually, and you can use the `agent.notify_when_agent_waiting` and `agent.play_sound_when_agent_done` settings keys to customize that, including turning both off entirely.
 91
 92### Reviewing Changes {#reviewing-changes}
 93
 94Once the agent has made changes to your project, the panel will surface which files, how many of them, and how many lines have been edited.
 95
 96To see which files specifically have been edited, expand the accordion bar that shows up right above the message editor or click the `Review Changes` button ({#kb agent::OpenAgentDiff}), which opens a special multi-buffer tab with all changes.
 97
 98You can accept or reject each individual change hunk, or the whole set of changes made by the agent.
 99
100Edit diffs also appear in singleton buffers.
101If your active tab had edits made by the AI, you'll see diffs with the same accept/reject controls as in the multi-buffer.
102You can turn this off, though, through the `agent.single_file_review` setting.
103
104## Adding Context {#adding-context}
105
106The agent can search your codebase to find relevant context, but providing it explicitly improves response quality and reduces latency.
107
108Add context by typing `@` in the message editor. You can mention files, directories, symbols, previous threads, rules files, and diagnostics.
109
110Copying images and pasting them in the panel's message editor is also supported.
111
112When you paste multi-line code selections copied from a buffer, Zed automatically formats them as @-mentions with the file context.
113To paste content without this automatic formatting, use {#kb agent::PasteRaw} to paste raw text directly.
114
115### Selection as Context
116
117Additionally, 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.
118
119## Token Usage {#token-usage}
120
121Zed surfaces how many tokens you are consuming for your currently active thread near the profile selector in the panel's message editor.
122
123Once you approach the model's context window, a banner appears above the message editor suggesting to start a new thread with the current one summarized and added as context.
124You can also do this at any time with an ongoing thread via the "Agent Options" menu on the top right, where you'll see a "New from Summary" button, as well as simply @-mentioning a past thread in a new one..
125
126## Changing Models {#changing-models}
127
128After 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.
129
130> The same model can be offered via multiple providers - for example, Claude Sonnet 4 is available via Zed Pro, OpenRouter, Anthropic directly, and more.
131> 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.
132
133### Favoriting Models
134
135You can mark specific models as favorites either through the model selector, by clicking on the star icon button that appears as you hover the model, or through your settings via the `agent.favorite_models` settings key.
136
137Cycle through your favorites with {#kb agent::CycleFavoriteModels} without opening the model selector.
138
139## Using Tools {#using-tools}
140
141The Agent Panel supports tool calling, which enables agentic editing.
142Zed includes [built-in tools](./tools.md) for searching your codebase, editing files, running terminal commands, and fetching web content.
143
144You can also extend the set of available tools via [MCP Servers](./mcp.md).
145
146### Profiles {#profiles}
147
148Profiles act as a way to group tools.
149Zed offers three built-in profiles and you can create as many custom ones as you want.
150
151#### Built-in Profiles {#built-in-profiles}
152
153- `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.
154- `Ask`: A profile with read-only tools. Best for asking questions about your code base without the concern of the agent making changes.
155- `Minimal`: A profile with no tools. Best for general conversations with the LLM where no knowledge of your code base is necessary.
156
157You 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.
158
159Alternatively, 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.
160
161Use {#kb agent::CycleModeSelector} to switch between profiles without opening the modal.
162
163#### Custom Profiles {#custom-profiles}
164
165You can also create a custom profile through the Agent Profile modal.
166From there, you can choose to `Add New Profile` or fork an existing one with a custom name and your preferred set of tools.
167
168It's also possible to override built-in profiles.
169In the Agent Profile modal, select a built-in profile, navigate to `Configure Tools`, and rearrange the tools you'd like to keep or remove.
170
171Zed will store this profile in your settings using the same profile name as the default you overrode.
172
173All custom profiles can be edited via the UI or by hand under the `agent.profiles` key in your `settings.json` file.
174
175To delete a custom profile, open the Agent Profile modal, select the profile you want to remove, and click the delete button.
176
177### Tool Approval
178
179> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
180
181Zed's Agent Panel provides the `agent.tool_permissions.default` setting to control tool approval behavior:
182
183- `"confirm"` (default) — Prompts for approval before running any tool action
184- `"allow"` — Auto-approves tool actions without prompting
185- `"deny"` — Blocks all tool actions
186
187You can change this in either your `settings.json` or via the Agent Panel's settings view.
188
189Even 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.
190
191When 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.
192
193> **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).
194
195### Model Support {#model-support}
196
197Tool calling needs to be individually supported by each model and model provider.
198Therefore, despite the presence of tools, some models may not have the ability to pick them up yet in Zed.
199You should see a "No tools" label if you select a model that falls into this case.
200
201All [Zed's hosted models](./models.md) support tool calling out-of-the-box.
202
203### MCP Servers {#mcp-servers}
204
205Similarly to the built-in tools, some models may not support all tools included in a given MCP Server.
206Zed's UI will inform you about this via a warning icon that appears close to the model selector.
207
208## Text Threads {#text-threads}
209
210["Text Threads"](./text-threads.md) present your conversation with the LLM in a different format—as raw text.
211With text threads, you have full control over the conversation data.
212You can remove and edit responses from the LLM, swap roles, and include more context earlier in the conversation.
213
214Text threads are Zed's original assistant panel format, preserved for users who want direct control over conversation data.
215Autonomous code editing (where the agent writes to files) is only available in the default thread format, not text threads.
216
217## Errors and Debugging {#errors-and-debugging}
218
219In case of any error or strange LLM response behavior, the best way to help the Zed team debug is by reaching for the `agent: open thread as markdown` action and attaching that data as part of your issue on GitHub.
220
221You can also open threads as Markdown by clicking on the file icon button, to the right of the thumbs down button, when focused on the panel's editor.
222
223## Feedback {#feedback}
224
225You can rate agent responses to help improve Zed's system prompt and tools.
226
227> Note that rating responses will send your data related to that response to Zed's servers.
228> 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.
229> **_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.
230
231The 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.
232
233You can provide feedback on the thread at any point after the agent responds, and multiple times within the same thread.