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.
9It's the core of Zed's AI code editing experience — use it for code generation, refactoring, debugging, documentation, and general questions.
10
11Open it with `agent: new thread` from [the Command Palette](../getting-started.md#command-palette) or click the ✨ icon in the status bar.
12
13## Getting Started {#getting-started}
14
15If you're using the Agent Panel for the first time, you need to have at least one LLM provider or external agent configured.
16You can do that by:
17
181. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models
192. [using your own API keys](./llm-providers.md#use-your-own-keys), either from model providers like Anthropic or model gateways like OpenRouter.
203. using an [external agent](./external-agents.md) like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Agent](./external-agents.md#claude-agent)
21
22## Overview {#overview}
23
24With an LLM provider or external agent configured, type in the message editor and press `enter` to submit.
25Expand the editor with {#kb agent::ExpandMessageEditor} if you need more room.
26
27Responses stream in with indicators showing [which tools](./tools.md) the model is using.
28The sections below cover what you can do from here.
29
30> 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.
31> Their availability varies depending on the agent.
32
33### Creating New Threads {#new-thread}
34
35By default, the Agent Panel uses Zed's first-party agent.
36
37Start a new thread with {#kb agent::NewThread}, or open the "New Thread…" menu via the `+` icon in the top-right of the panel toolbar (in the empty state, this menu is exposed as the agent selector button on the left). You can also open that menu with {#kb agent::ToggleNewThreadMenu}.
38
39From the "New Thread…" menu you can:
40
41- Pick **Zed Agent** or any installed [external agent](./external-agents.md) to start a new thread with that agent.
42- 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.
43
44{#action agent::NewExternalAgentThread} creates another thread with the currently selected agent.
45
46You 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).
47
48### Managing Multiple Threads {#multiple-threads}
49
50You can run multiple agent threads at once, each working independently with its own agent, context window, and conversation history. Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar} to see all your threads grouped by project. Click any thread to switch to it, or use the thread switcher ({#kb agents_sidebar::ToggleThreadSwitcher}) to cycle between recent threads without opening the sidebar.
51
52Threads you're no longer working on can be archived by hovering over them in the sidebar and clicking the archive icon, or selecting them and pressing {#kb agent::ArchiveSelectedThread}. The Thread History holds all your threads across all projects, sorted chronologically, and you can restore them at any time.
53
54If two threads might edit the same files, you can isolate one in a new Git worktree. Use the worktree picker in the title bar to pick which worktree the agent runs in, or create a new one. See [Worktree Isolation](./parallel-agents.md#worktree-isolation) for details.
55
56For more details on the Threads Sidebar and managing multiple projects, see [Parallel Agents](./parallel-agents.md).
57
58### Editing Messages {#editing-messages}
59
60Any message that you send to the model is editable.
61You can click on the card that contains your message and re-submit it with an adjusted prompt and/or new pieces of context.
62
63### Queueing Messages
64
65Messages sent while the agent is in the generating state get, by default, queued.
66
67For 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.
68
69You can edit or remove (an individual or all) queued messages.
70You 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.
71
72### Checkpoints {#checkpoints}
73
74Every 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.
75
76The 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.
77
78### Context Menu {#context-menu}
79
80Right-click on any agent response in the thread view to access a context menu with the following actions:
81
82- **Copy Selection**: Copies the currently selected text as Markdown (available when text is selected).
83- **Copy This Agent Response**: Copies the full text of the agent response you right-clicked on.
84- **Scroll to Top / Scroll to Bottom**: Scrolls to the beginning or end of the thread, depending on your current position.
85- **Open Thread as Markdown**: Opens the entire thread as a Markdown file in a new tab.
86
87### Navigating the Thread {#navigating-the-thread}
88
89In 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. You can also scroll the thread using arrow keys, Page Up/Down, Home/End, and Shift+Page Up/Down to jump between messages, when the thread pane is focused.
90
91When focus is in the message editor, you can also use {#kb agent::ScrollOutputPageUp}, {#kb agent::ScrollOutputPageDown}, {#kb agent::ScrollOutputToTop}, {#kb agent::ScrollOutputToBottom}, {#kb agent::ScrollOutputLineUp}, and {#kb agent::ScrollOutputLineDown} to navigate the thread, or {#kb agent::ScrollOutputToPreviousMessage} and {#kb agent::ScrollOutputToNextMessage} to jump between your prompts.
92
93### Thread titles {#thread-titles}
94
95Thread titles are auto-generated based on the content of the conversation.
96But 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.
97
98### Following the Agent {#following-the-agent}
99
100Follow the agent as it reads and edits files by clicking the crosshair icon at the bottom left of the panel.
101Your editor will jump to each file the agent touches.
102
103You can also hold `cmd`/`ctrl` when submitting a message to automatically follow.
104
105### Get Notified {#get-notified}
106
107If 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:
108
109- a visual notification that appears in the top right of your screen
110- a sound notification
111
112These 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.
113
114### Reviewing Changes {#reviewing-changes}
115
116Once 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.
117
118To 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.
119
120You can accept or reject each individual change hunk, or the whole set of changes made by the agent.
121
122Edit diffs also appear in singleton buffers.
123If your active tab had edits made by the AI, you'll see diffs with the same accept/reject controls as in the multi-buffer.
124You can turn this off, though, through the `agent.single_file_review` setting.
125
126## Adding Context {#adding-context}
127
128The agent can search your codebase to find relevant context, but providing it explicitly improves response quality and reduces latency.
129
130Add context by typing `@` in the message editor.
131You can mention files, directories, symbols, previous threads, rules files, and diagnostics.
132
133When you paste multi-line code selections copied from a buffer, Zed automatically formats them as @-mentions with the file context.
134To paste content without this automatic formatting, use {#kb agent::PasteRaw} to paste raw text directly.
135
136### Selection as Context
137
138Additionally, 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.
139
140### Images as Context
141
142It's also possible to attach images in your prompt for providers that support vision models.
143OpenAI 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.
144
145To 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.
146Copying an image and pasting it is also supported.
147
148## Token Usage {#token-usage}
149
150Zed surfaces how many tokens you are consuming for your currently active thread near the profile selector in the panel's message editor.
151
152Once 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.
153You 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..
154
155## Changing Models {#changing-models}
156
157After 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.
158
159> 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.
160> 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.
161
162### Favoriting Models
163
164You 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.
165
166Cycle through your favorites with {#kb agent::CycleFavoriteModels} without opening the model selector.
167
168## Using Tools {#using-tools}
169
170The Agent Panel supports tool calling, which enables agentic editing.
171Zed includes several [built-in tools](./tools.md) for searching your codebase, editing files, running terminal commands, and more.
172
173You can also extend the set of available tools via [MCP Servers](./mcp.md).
174
175### Profiles {#profiles}
176
177Profiles act as a way to group tools.
178Zed offers three built-in profiles and you can create as many custom ones as you want.
179
180#### Built-in Profiles {#built-in-profiles}
181
182- `Write`: A profile with tools to allow the LLM to write to your files and run terminal commands.
183 This one essentially has all built-in tools turned on.
184- `Ask`: A profile with read-only tools.
185 Best for asking questions about your code base without the concern of the agent making changes.
186- `Minimal`: A profile with no tools.
187 Best for general conversations with the LLM where no knowledge of your code base is necessary.
188
189You 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.
190
191Alternatively, 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.
192
193Use {#kb agent::CycleModeSelector} to cycle through available profiles without opening the modal.
194
195#### Custom Profiles {#custom-profiles}
196
197You can also create a custom profile through the Agent Profile modal.
198From there, you can choose to `Add New Profile` or fork an existing one with a custom name and your preferred set of tools.
199
200It's also possible to override built-in profiles.
201In the Agent Profile modal, select a built-in profile, navigate to `Configure Tools`, and rearrange the tools you'd like to keep or remove.
202
203Zed will store this profile in your settings using the same profile name as the default you overrode.
204
205All custom profiles can be edited via the UI or by hand under the `agent.profiles` key in your settings file.
206
207To delete a custom profile, open the Agent Profile modal, select the profile you want to remove, and click the delete button.
208
209### Tool Permissions
210
211> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
212> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`).
213
214Zed's Agent Panel provides the `agent.tool_permissions.default` setting to control tool approval behavior:
215
216- `"confirm"` (default) — Prompts for approval before running any tool action
217- `"allow"` — Auto-approves tool actions without prompting
218- `"deny"` — Blocks all tool actions
219
220When 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.
221When Zed can extract a safe pattern from the input, it also offers pattern-based "Always for ..." choices that add `always_allow`/`always_deny` rules.
222MCP tools only support tool-level defaults.
223
224Even 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.
225
226Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details.
227
228### Model Support {#model-support}
229
230Tool calling needs to be individually supported by each model and model provider.
231Therefore, despite the presence of built-in tools, some models may not have the ability to pick them up.
232You should see a "No tools" label if you select a model that falls into this case.
233
234All [Zed's hosted models](./models.md) support tool calling out-of-the-box.
235
236### MCP Servers {#mcp-servers}
237
238Similarly to the built-in tools, some models may not support all tools included in a given MCP Server.
239Zed's UI will inform you about this via a warning icon that appears close to the model selector.
240
241## Errors and Debugging {#errors-and-debugging}
242
243If you hit an error or unusual LLM behavior, open the thread as Markdown with `agent: open thread as markdown` and attach it to your GitHub issue.
244
245You 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.
246
247## Feedback {#feedback}
248
249You can rate agent responses to help improve Zed's system prompt and tools.
250
251> Note that rating responses will send your data related to that response to Zed's servers.
252> 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.
253> **_If you don't want data persisted on Zed's servers, don't rate_**.
254> We will not collect data for improving our Agentic offering without you explicitly rating responses.
255
256To help improve Zed's system prompt and tools, rate responses with the thumbs up/down controls at the end of each response.
257In case of a thumbs down, a new text area will show up where you can add more specifics about what happened.
258
259You can provide feedback on the thread at any point after the agent responds, and multiple times within the same thread.