diff --git a/docs/src/ai/agent-panel.md b/docs/src/ai/agent-panel.md
index e0d019655d952e..e29ed36a9fbcb8 100644
--- a/docs/src/ai/agent-panel.md
+++ b/docs/src/ai/agent-panel.md
@@ -148,12 +148,15 @@ OpenAI GPT-4o and later, Anthropic Claude 3 and later, Google Gemini 1.5 and 2.0
 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}
+## Token Usage and Compaction {#token-usage}
 
 Zed surfaces how many tokens you are consuming for your currently active thread near the profile selector in the panel's message editor.
 
-Once 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.
-You 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.
+Zed automatically compacts long Zed Agent threads as they approach the configured token threshold. Compaction summarizes earlier messages and replaces them in the model context with that summary, leaving more room for the next turn. The thread shows a **Context Compacted** entry that you can expand to inspect the summary. You can compact manually by typing `/compact` in the message editor.
+
+If the selected model's context window is too small for automatic compaction (less than 80000 tokens), a banner appears above the message editor as you approach the token limit. Use **Start New Thread** from that banner, or choose **New From Summary** from the "Agent Options" menu, to continue in a new thread seeded with a summary. You can also @-mention a past thread in a new one.
+
+Configure automatic compaction with `agent.auto_compact`. See [Agent Settings](./agent-settings.md#automatic-compaction) for options.
 
 ## Changing Models {#changing-models}
 
diff --git a/docs/src/ai/agent-settings.md b/docs/src/ai/agent-settings.md
index f421f2765cacf4..3919ebc24d007e 100644
--- a/docs/src/ai/agent-settings.md
+++ b/docs/src/ai/agent-settings.md
@@ -53,6 +53,35 @@ Use `agent.commit_message_instructions` for instructions that apply only to gene
 
 For feature-specific model examples, see [Feature-specific Models](#feature-specific-models).
 
+## Automatic Compaction {#automatic-compaction}
+
+Zed Agent can automatically compact long threads before they reach the selected model's context window. Compaction summarizes earlier messages and keeps the conversation usable without starting a new thread.
+
+Automatic compaction is enabled by default and runs when the thread reaches `90%` of the model's context window. You can change the threshold or disable automatic compaction in `settings.json`:
+
+```json [settings]
+{
+  "agent": {
+    "auto_compact": {
+      "enabled": true,
+      "threshold": "90%"
+    }
+  }
+}
+```
+
+The `threshold` value can be one of:
+
+| Value                           | Meaning                                                                        |
+| ------------------------------- | ------------------------------------------------------------------------------ |
+| Percentage string, like `90%`   | Compact when the thread uses that percentage of the model's context window.    |
+| Positive integer, like `100000` | Compact after that many tokens have been used.                                 |
+| Negative integer, like `-20000` | Compact once fewer than that many tokens remain in the model's context window. |
+
+`0` is not a valid threshold. If the threshold is invalid, Zed falls back to `90%`.
+
+You can compact a Zed Agent thread manually at any time by typing `/compact` in the Agent Panel message editor. For more on thread token usage and compaction behavior, see [Token Usage and Compaction](./agent-panel.md#token-usage).
+
 ## External Agents {#external-agents}
 
 The External Agents section configures ACP-integrated agents.