tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs: sessions reorg and conversation features (#4462)

Browse Source 
Co-authored-by: Rizel Scarlett <rizel@squareup.com>
This commit is contained in:
dianed-square
2025-09-01 16:42:43 -07:00
committed by GitHub
parent ce69b396ce
commit e73b6037a2
20 changed files with 368 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/sessions/_category_.json
+8
View File
@@ -0,0 +1,8 @@
{
"label": "Managing Sessions",
"position": 1,
"link": {
"type": "doc",
"id": "guides/sessions/index"
}
}
documentation/docs/guides/sessions/in-session-actions.md
+260
View File
@@ -0,0 +1,260 @@
---
sidebar_position: 2
title: In-Session Actions
sidebar_label: In-Session Actions
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { PanelLeft, Paperclip, Edit2, Send, GripVertical, X, ChevronUp, ChevronDown } from 'lucide-react';
Goose provides features you can use to manage conversations and share information during sessions.
## Edit Message
Edit your previously sent messages to refine conversations and correct course.
Editing any message in the session gives you complete control over the conversation history by overwriting all the context that follows the edited message. Your change can be as simple as fixing a path in your last message or completely starting over from a given point.
This is useful when:
- You realize a prompt you sent was unclear or incomplete
- Goose misunderstood your intent and went in the wrong direction
- You want to try different approaches to a problem without starting a new session
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
1. Hover over any of your previous messages to reveal the edit button
2. Click the <Edit2 className="inline" size={16} /> edit button that appears
3. Make your changes in the inline editor
4. Click `Save` to save your changes and reprompt Goose (or use `Cmd+Enter` (macOS) or `Ctrl+Enter` (Windows/Linux))
Goose removes all conversation history after the edited message and responds contextually from that point.
:::warning Deleted Context
Subsequent conversation history is permanently deleted from the session and removed from Goose's context. Edit a message only if you don't need Goose to remember the context that follows it.
:::
#### Example Message Flow
Your original conversation has five messages. After editing message 3, the conversation continues from that point, and all message and response context from messages 4 and 5 is deleted.
```
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│ 1 │ -> │ 2 │ -> │ 3 │ -> │ 4 │ -> │ 5 │
└─────┘ └─────┘ └─────┘ └─────┘ └─────┘
Edit here
↓
┌─────┐ ┌─────┐ ┌─────┐ conversation
│ 1 │ -> │ 2 │ -> │ 3 │ -> continues
└─────┘ └─────┘ └─────┘ from here
```
#### Editing Scenario Tips
- **Iterative Prompt Refinement**: Start with a basic prompt, then edit and refine based on Goose's response. This often works better than trying to craft the perfect prompt from the start.
- **When to Edit vs. Interrupt**: Editing earlier messages when a conversation has gone off track can be more effective than trying to correct course using new messages or [interruptions](#interrupt-task). By editing messages, you rewrite history. With interruptions, you only affect the conversation from the current message onwards.
</TabItem>
<TabItem value="cli" label="Goose CLI">
Message editing is not available in the Goose CLI.
</TabItem>
</Tabs>
## Queue Messages
Queue messages while Goose is processing a task to manage your workflow. This is useful when:
- You want to prepare next steps while Goose is working
- You have a sequence of related tasks to complete
- You're using [voice dictation](#voice-dictation) and need to capture thoughts quickly
:::tip
Goose may perform better when complex tasks are split into subtasks, a technique called [*prompt chaining*](https://www.promptingguide.ai/techniques/prompt_chaining). This structured approach can both improve accuracy and give you more control over the process.
:::
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Add a message to the queue:
1. While Goose is processing a response, type your next message
2. Press `Enter` to add it to the queue (or interrupts if using [interruption keywords](#interrupt-task))
Queued messages appear as numbered cards showing the queue order. The first message in the queue is automatically sent when Goose finishes each response.
:::info Related Features
- In general, pressing `Enter` while Goose is processing a task queues the message, but clicking `Send` sends the task immediately and [interrupts the task](#interrupt-task)
- When you type common interrupt keywords like "stop", "wait", or "hold on" in a queued message, Goose pauses until you enter or send the next message and then continues processing the queue
:::
#### Queue Management Controls
Queued messages run automatically in order as Goose finishes each task, but you can manage the queue:
- **Edit a message**: Click the message text to reveal the edit controls, then type your change and click `Save`
- **Reorder messages**: Hover over the message card to reveal the <GripVertical className="inline" size={16} /> button, then grab it and drag the message up or down
- **Send a message**: Click the <Send className="inline" size={16} /> button to send a message immediately and interrupt the current task
- **Delete a message**: Click the <X className="inline" size={16} /> button to delete the message
- **Clear the queue**: Click `Clear All` on the **Message Queue** card
- **Collapse or expand the queue**: Click the <ChevronUp className="inline" size={16} /> or <ChevronDown className="inline" size={16} /> button on the **Message Queue** card
#### Example Message Flow
**Without queuing:**
You send: "Can you refactor our authentication code to support OAuth 2.0 and add proper error handling? Also include unit tests for the OAuth flow, update the API documentation to reflect these changes, and create a migration script to help existing users transition to the new system."
This approach might lead to overwhelming responses where important details get missed or tasks are handled superficially. Even sending a single prompt with clear sequential steps doesn't allow Goose to focus on each task individually or build context progressively.
**With queuing:**
1. You send: "Refactor the authentication code to support OAuth 2.0"
2. While Goose is working, you queue the following messages:
- "And add proper error handling"
- "Add unit tests for the OAuth flow"
- "Update the API documentation"
- "Create migration script for existing users"
Each task builds on the previous one.
</TabItem>
<TabItem value="cli" label="Goose CLI">
Message queuing is not available in the Goose CLI.
</TabItem>
</Tabs>
## Interrupt Task
Interrupt Goose while it's processing a task to take control of the conversation. This is useful when:
- Goose is heading in the wrong direction
- You realize you need to add important context
- You want to switch to a completely different task
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
There are two ways to interrupt a task:
#### Send interruption keyword
1. Type a prompt that includes common interruption keywords like `stop`, `wait`, `hold on`, `actually`, or `instead`. Using keywords alone or at the beginning of sentences works best for reliable detection.
2. Click `Send`
Goose stops processing the current task and asks for more information.
#### Provide immediate redirection
1. Type a prompt with more context and clarification or that changes direction. For example:
- "I forgot to mention this is for a mobile app"
- "Let's focus on React instead of TypeScript"
2. Click `Send`
Goose stops processing the current task and pivots to the new request context.
:::info Related features
- Clicking `Send` while Goose is processing a task interrupts the task but pressing `Enter` [queues the message](#queue-messages)
- Typing a stop or pause keyword in a queued message also stops Goose from processing the current task
- You can also [edit a sent message](#edit-message) to provide more context and clarification or change direction during a session
:::
<details>
<summary>Interruption Keywords List</summary>
**High-priority keywords** (interrupt in any context):
```
stop, halt, cease, quit, end, abort, cancel, wait, hold, pause, hold on, wait up, hold up
```
**Medium-priority keywords** (interrupt only as exact matches or at beginning of sentences):
```
no, nope, nah, wrong, incorrect, not right, actually, instead, rather, better idea, change of plans, nevermind, never mind, forget it, ignore that, disregard
```
**Detection Rules**:
- **Exact match** (100% confidence): Word/phrase matches exactly and always interrupts
- **Beginning of sentence** (very high confidence): Word/phrase starts your message and always interrupts
- **Short messages only** (high confidence): In messages ≤20 characters, only high-priority keywords interrupt
- **Case insensitive**: All detection is case-insensitive
**Examples**:
- ✅ "stop" interrupts (exact match)
- ✅ "Wait, I meant something else" interrupts (beginning of sentence)
- ✅ "no" interrupts (short message, high-priority)
- ❌ "actually" in short message doesn't interrupt (medium-priority in short message)
- ✅ "Actually, let's try React instead" interrupts (beginning of sentence)
</details>
</TabItem>
<TabItem value="cli" label="Goose CLI">
1. Press `Ctrl+C` to interrupt the current task
2. Type your prompt that provides more context or changes direction
3. Press `Enter`
Goose responds contextually to your new request.
</TabItem>
</Tabs>
## Voice Dictation
Speak to Goose directly instead of typing your prompts.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
To enable voice dictation:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `Settings` in the sidebar
3. Click `Chat`
4. Under `Voice Dictation`, toggle `Enable Voice Dictation` on
5. Choose between `OpenAI Whisper` or `ElevenLabs` as your dictation provider
6. Enter your API key for the provider you chose
To use voice dictation:
1. Return to the chat interface (click `Chat` in the sidebar)
2. Click the microphone on the right of the chat box and begin speaking
The first time you use voice dictation, Goose will request access to your microphone. While recording, you'll see a live waveform of your audio in the input field, a timer, and the current size of your recording. Click the microphone button again to finish recording.
**If you don't see the microphone**, check the [models you have configured](/docs/getting-started/providers.md). ElevenLabs can be used as a dictation provider alongside any LLM, but OpenAI Whisper requires that you have an OpenAI model configured in Goose, even if using another LLM provider for chat.
#### Important Notes
* You can record up to 10 minutes or 25MB of audio
* The audio is processed by your chosen provider (OpenAI or ElevenLabs)
* Voice input is appended to any existing text in the text input field, so you can combine typing and speaking your prompts
* Recordings are not stored locally after transcription
</TabItem>
<TabItem value="cli" label="Goose CLI">
Voice dictation is not available in the Goose CLI.
</TabItem>
</Tabs>
## Share Files in Session
Provide Goose with context from your codebase, documents, and other files to get more relevant and accurate assistance.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Share files with Goose in several ways:
1. **Drag and Drop**: Simply drag files from your computer's file explorer/finder and drop them anywhere in the chat window. The file paths will be automatically added to your message.
2. **File Browser**: Click the <Paperclip className="inline" size={16} /> button at the bottom of the app to open your system's file browser and select files
3. **Manual Path**: Type or paste the file path directly into the chat input
4. **Quick File Search**: Use the [`@` shortcut key](/docs/guides/file-management#quick-file-search-in-goose-desktop) to quickly find and include files
</TabItem>
<TabItem value="cli" label="Goose CLI">
You can reference files by their paths directly in your messages. Since you're already in a terminal, you can use standard shell commands to help with file paths:
```bash
# Reference a specific file
What does this code do? ./src/main.rs
# Use tab completion
Can you explain the function in ./src/lib<tab>
# Use shell expansion
Review these test files: ./tests/*.rs
```
</TabItem>
</Tabs>
documentation/docs/guides/sessions/index.md
+56
View File
@@ -0,0 +1,56 @@
---
title: Managing Sessions
hide_title: true
description: Manage your session lifecycle and ongoing interactions with Goose
---
import Card from '@site/src/components/Card';
import styles from '@site/src/components/Card/styles.module.css';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<h1 className={styles.pageTitle}>Managing Sessions</h1>
<p className={styles.pageDescription}>
Sessions are your continuous interactions with Goose. Each session maintains context and conversation history, enabling Goose to understand your ongoing work and provide relevant assistance.
</p>
<div className={styles.categorySection}>
<h2 className={styles.categoryTitle}>📚 Documentation & Guides</h2>
<div className={styles.cardGrid}>
<Card
title="Session Management"
description="Learn how to start, resume, or search sessions, and perform other session management tasks."
link="/docs/guides/sessions/session-management"
/>
<Card
title="In-Session Actions"
description="Discover features you can use to share information and communicate with Goose during sessions."
link="/docs/guides/sessions/in-session-actions"
/>
<Card
title="Smart Context Management"
description="Maintain productive sessions using features that help manage context and conversation limits."
link="/docs/guides/sessions/smart-context-management"
/>
</div>
</div>
<div className={styles.categorySection}>
<h2 className={styles.categoryTitle}>📝 Featured Blog Posts</h2>
<div className={styles.cardGrid}>
<Card
title="6 Essential Tips for Working with Goose"
description="Learn how focused sessions, step-by-step guidance, and refining your prompts can lead to more productive sessions."
link="/blog/2025/03/06/goose-tips"
/>
<Card
title="AI Prompting 101: How to Get the Best Responses from Your AI Agent"
description="Make your sessions more effective by adding structure to your prompts."
link="/blog/2025/03/19/better-ai-prompting"
/>
<Card
title="The AI Skeptic’s Guide to Context Windows"
description="Learn how context windows, tokens, and Goose help you manage memory and long conversations."
link="/blog/2025/08/18/understanding-context-windows"
/>
</div>
</div>
documentation/docs/guides/sessions/session-management.md
+326
View File
@@ -0,0 +1,326 @@
---
sidebar_position: 1
title: Session Management
sidebar_label: Session Management
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { AppWindow, PanelLeft, FolderDot, Paperclip, Copy, Edit2 } from 'lucide-react';
A session is a single, continuous interaction between you and Goose, providing a space to ask questions and prompt action. This guide covers how to manage the session lifecycle.
## Start Session
:::info First-time setup
In your first session, Goose prompts you to [set up an LLM (Large Language Model) provider](/docs/getting-started/installation#set-llm-provider).
:::
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
When you open Goose, you'll see the session interface ready for use. Just type&mdash;[or speak](/docs/guides/sessions/in-session-actions#voice-dictation "Learn how to enable voice dictation")&mdash;your questions, requests, or instructions directly into the input field, and Goose will immediately get to work.
When you're ready to work on a new task, you can start a new session in the same directory or a different one. This directory is where Goose reads and writes files by default.
<Tabs>
<TabItem value="same-directory" label="Same Directory" default>
To start a session in the same Goose window:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `Home` in the sidebar
3. Send your first prompt from the chat box
To start a session in a new Goose window:
1. Click the <AppWindow className="inline" size={16} /> button in the top-left
2. In the new Goose window, send your first prompt from the chat box
</TabItem>
<TabItem value="diff-directory" label="Different Directory">
1. Click the <FolderDot className="inline" size={16} /> directory switcher at the bottom of the app
2. Navigate to the new directory or create a new folder
3. Click `Open` to open a new Goose window for the selected directory
4. Send your first prompt from the chat box
</TabItem>
</Tabs>
:::tip
On macOS, you can drag and drop a folder onto the Goose icon in the dock to open a new session in that directory.
:::
You can also use keyboard shortcuts to start a new session or bring focus to open Goose windows.
| Action | macOS | Windows/Linux |
|--------|-------|---------------|
| New Session in Current Directory | `Cmd+N` | `Ctrl+N` |
| New Session in Different Directory | `Cmd+O` | `Ctrl+O` |
| Focus Goose Window | `Cmd+Option+Shift+G` | `Ctrl+Alt+Shift+G` |
</TabItem>
<TabItem value="cli" label="Goose CLI">
From your terminal, navigate to the directory from which you'd like to start, and run the [session](/docs/guides/goose-cli-commands#session-options) command:
```sh
goose session
```
If you want to interact with Goose in a web-based chat interface, start a session with the [`web`](/docs/guides/goose-cli-commands#web) command:
```sh
goose web --open
```
</TabItem>
</Tabs>
## Name Session
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Within the Desktop app, sessions are automatically named based on the context of your initial prompt.
You can rename sessions after they're created:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `History` in the sidebar
3. Hover over the session you'd like to rename
4. Click the <Edit2 className="inline" size={16} /> button that appears on the session card
5. Enter the new session name
6. Click `Save`
Session names can also help you manage multiple Goose windows. When you're in the Goose chat interface, session names appear in the `Window` menu and in the Dock (macOS) or taskbar (Windows) menu, making it easy to identify and switch between different Goose sessions.
</TabItem>
<TabItem value="cli" label="Goose CLI">
By default, Goose names your session using the current timestamp in the format `YYYYMMDD_HHMMSS`. If you'd like to provide a specific name, this is where you'd do so. For example to name your session `react-migration`, you would run:
```
goose session -n react-migration
```
You'll know your session has started when your terminal looks similar to the following:
```
starting session | provider: openai model: gpt-4o
logging to ~/.local/share/goose/sessions/react-migration.json1
```
</TabItem>
</Tabs>
## Exit Session
Note that sessions are automatically saved when you exit.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
To exit a session, simply close the application.
</TabItem>
<TabItem value="cli" label="Goose CLI">
To exit a session, type `exit`. Alternatively, you exit the session by holding down `Ctrl+C`.
Your session will be stored locally in `~/.local/share/goose/sessions`.
</TabItem>
</Tabs>
## Search Sessions
Search allows you to find specific content within sessions or find specific sessions.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
You can use keyboard shortcuts and search bar buttons to search sessions in Goose Desktop.
| Action | macOS | Windows/Linux |
|--------|-------|---------------|
| Open Search | `Cmd+F` | `Ctrl+F` |
| Next Match | `Cmd+G` or `↓` | `Ctrl+G` or `↓` |
| Previous Match | `Shift+Cmd+G` or `↑` | `Shift+Ctrl+G` or `↑` |
| Use Selection for Find | `Cmd+E` | n/a |
| Toggle Case-Sensitivity | `Aa` | `Aa` |
| Close Search | `Esc` or `X` | `Esc` or `X` |
The following scenarios are supported:
#### Search Within Current Session
To find specific content within your current session:
1. Use `Cmd+F` to open the search bar
2. Enter your search term
3. Use shortcuts and search bar buttons to navigate the results
#### Search For Session By Name or Path
To search all your sessions by name or working directory path:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `History` in the sidebar
3. Use `Cmd+F` to open the search bar
4. Enter your search term
5. Use keyboard shortcuts and search bar buttons to navigate the results (`Cmd+E` not supported)
This is a metadata-only search. It doesn't search conversation content. Note that searching by file name is supported (e.g. `20250727_130002.jsonl`), but this property isn't displayed in the UI.
:::tip
You can [rename sessions](#name-session) to give them descriptive names that you'll remember later.
:::
#### Search Within Historical Session
To find specific content within a historical session:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `History` in the sidebar
3. Click a specific session tile from the list to view its content
4. Use `Cmd+F` to open the search bar
5. Enter your search term
6. Use keyboard shortcuts and search bar buttons to navigate the results
:::info No Regex or operator support
Using regular expressions or search operators in search text isn't supported.
:::
</TabItem>
<TabItem value="cli" label="Goose CLI">
Search functionality is provided by your terminal interface. Use the appropriate shortcut for your environment:
| Terminal | Operating System | Shortcut |
|----------|-----------------|-----------|
| iTerm2 | macOS | `Cmd+F` |
| Terminal.app | macOS | `Cmd+F` |
| Windows Terminal | Windows | `Ctrl+F` |
| Linux Terminal | Linux | `Ctrl+F` |
:::info
Your specific terminal emulator may use a different keyboard shortcut. Check your terminal's documentation or settings for the search command.
:::
The Goose CLI supports [listing session history](/docs/guides/goose-cli-commands#session-list-options) but doesn't provide search functionality. As a workaround, you can use your terminal's search capabilities (including regex support) to search for specific content within sessions or find specific sessions.
Examples for macOS:
```bash
# Search session IDs (filenames)
ls ~/.local/share/goose/sessions/ | grep "full or partial session id"
# List sessions modified in last 7 days
find ~/.local/share/goose/sessions/ -mtime -7 -name "*.jsonl"
# Show first line (metadata) of each session file
for f in ~/.local/share/goose/sessions/*.jsonl; do
head -n1 "$f" | grep "your search term" && echo "Found in: $(basename "$f" .jsonl)"
done
# Find search term in session content
rg "your search term" ~/.local/share/goose/sessions/
# Search and show session IDs that contain search term
for f in ~/.local/share/goose/sessions/*.jsonl; do
if grep -q "your search term" "$f"; then
echo "Found in session: $(basename "$f" .jsonl)"
fi
done
```
</TabItem>
</Tabs>
## Resume Session
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `History` in the sidebar
3. Click the session you'd like to resume. Goose provides [search features](#search-sessions) to help you find the session.
4. Choose how to resume:
- Click `Resume` to continue in the current window
- Click `New Window` to open in a new window
:::tip
You can also quickly resume one of your three most recent sessions by clicking it in the `Recent chats` section on the `Home` page.
:::
</TabItem>
<TabItem value="cli" label="Goose CLI">
To resume your latest session, you can run the following command:
```
goose session -r
```
To resume a specific session, run the following command:
```
goose session -r --name <name>
```
For example, to resume the session named `react-migration`, you would run:
```
goose session -r --name react-migration
```
:::tip
While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of [doom spiraling](/docs/troubleshooting#stuck-in-a-loop-or-unresponsive).
:::
</TabItem>
</Tabs>
### Resume Session Across Interfaces
You can resume a CLI session in Desktop.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
All saved sessions are listed in the Desktop app, even CLI sessions. To resume a CLI session within the Desktop:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `History` in the sidebar
3. Click the session you'd like to resume
4. Choose how to resume:
- Click `Resume` to continue in the current window
- Click `New Window` to open in a new window
</TabItem>
<TabItem value="cli" label="Goose CLI">
Currently, you cannot resume a Desktop session within the CLI.
</TabItem>
</Tabs>
### Resume Project-Based Sessions
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Project-based sessions are only available through the CLI.
</TabItem>
<TabItem value="cli" label="Goose CLI">
You can use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#projects) commands to start or resume sessions from a project, which is a tracked working directory with session metadata. For a complete guide to using Projects, see [Managing Projects Guide](/docs/guides/managing-projects).
</TabItem>
</Tabs>
## Remove Sessions
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Removing sessions is only available through the CLI.
</TabItem>
<TabItem value="cli" label="Goose CLI">
You can remove sessions using CLI commands. For detailed instructions on session removal, see the [CLI Commands documentation](/docs/guides/goose-cli-commands#session-remove-options).
</TabItem>
</Tabs>
## Export Sessions
Export sessions to Markdown to share with your team, create documentation, archive conversations, or review them in a readable format.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Session export is currently only available through the CLI.
</TabItem>
<TabItem value="cli" label="Goose CLI">
Export sessions using the `export` subcommand:
```bash
# Interactive export - prompts you to select a session
goose session export
```
For more details on export options, available flags, and output formats, see the [CLI commands documentation](/docs/guides/goose-cli-commands#session-export-options).
</TabItem>
</Tabs>
documentation/docs/guides/sessions/smart-context-management.md
+389
View File
@@ -0,0 +1,389 @@
---
title: Smart Context Management
sidebar_position: 3
sidebar_label: Smart Context Management
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { ScrollText } from 'lucide-react';
import { PanelLeft } from 'lucide-react';
When working with [Large Language Models (LLMs)](/docs/getting-started/providers), there are limits to how much conversation history they can process at once. Goose provides smart context management features to help handle context and conversation limits so you can maintain productive sessions. Here are some key concepts:
- **Context Length**: The amount of conversation history the LLM can consider
- **Context Limit**: The maximum number of tokens the model can process
- **Context Management**: How Goose handles conversations approaching these limits
- **Turn**: One complete prompt-response interaction between Goose and the LLM
## How Goose Manages Context
Goose uses a two-tierd approach to context management:
1. **Auto-Compaction**: Proactively summarizes conversation when approaching token limits
2. **Context Strategies**: Backup strategy used if the context limit is still exceeded after auto-compaction
This layered approach lets Goose handle token and context limits gracefully.
## Automatic Compaction
Goose automatically compacts (summarizes) older parts of your conversation when approaching token limits, allowing you to maintain long-running sessions without manual intervention.
Auto-compaction is triggered by default when you reach 80% of the token limit in Goose Desktop and the Goose CLI.
Control the auto-compaction behavior with the `GOOSE_AUTO_COMPACT_THRESHOLD` [environment variable](/docs/guides/environment-variables.md#session-management).
Disable this feature by setting the value to `0.0`.
```
# Automatically compact sessions when 60% of available tokens are used
export GOOSE_AUTO_COMPACT_THRESHOLD=0.6
```
When you reach the auto-compaction threshold:
1. Goose will automatically start summarizing the conversation to make room.
2. You'll see a message that says **"Auto-compacted context: X → Y tokens (Z% reduction)"**
3. Once complete, previous messages in your conversation remain visible, but only the summary is included in the active context for Goose.
4. Continue the session with the summarized context in place.
### Manual Compaction
You can also trigger compaction manually before reaching context or token limits:
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
1. Point to the token usage indicator dot next to the model name at the bottom of the app
2. Click <ScrollText className="inline" size={16} /> `Summarize now` in the context window that appears
2. Confirm the summarization in the modal
3. View or edit the generated summary if needed
:::note
Before the scroll icon appears, you must send at least one message in the chat. Simply starting a new session won't trigger it.
:::
</TabItem>
<TabItem value="cli" label="Goose CLI" default>
To proactively trigger summarization before reaching context limits, use the `/summarize` command:
```sh
( O)> /summarize
◇ Are you sure you want to summarize this conversation? This will condense the message history.
│ Yes
│
Summarizing conversation...
Conversation has been summarized.
Key information has been preserved while reducing context length.
```
</TabItem>
</Tabs>
## Context Limit Strategies
When auto-compaction is disabled, or if a conversation still exceeds the context limit, Goose offers different ways to handle it:
| Feature | Description | Best For | Availability | Impact |
|---------|-------------|-----------|-----------|---------|
| **Summarization** | Condenses conversation while preserving key points | Long, complex conversations | Desktop and CLI | Maintains most context |
| **Truncation** | Removes oldest messages to make room | Simple, linear conversations | CLI only | Loses old context |
| **Clear** | Starts fresh while keeping session active | New direction in conversation | CLI only | Loses all context |
| **Prompt** | Asks user to choose from the above options | Control over each decision in interactive sessions | CLI only | Depends on choice made |
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Goose Desktop exclusively uses summarization to manage context, preserving key information while reducing size.
</TabItem>
<TabItem value="cli" label="Goose CLI">
The CLI supports all context limit strategies: `summarize`, `truncate`, `clear`, and `prompt`.
The default behavior depends on the mode you're running in:
- **Interactive mode**: Prompts user to choose (equivalent to `prompt`)
- **Headless mode** (`goose run`): Automatically summarizes (equivalent to `summarize`)
You can configure how Goose handles context limits by setting the `GOOSE_CONTEXT_STRATEGY` environment variable:
```bash
# Set automatic strategy (choose one)
export GOOSE_CONTEXT_STRATEGY=summarize # Automatically summarize (recommended)
export GOOSE_CONTEXT_STRATEGY=truncate # Automatically remove oldest messages
export GOOSE_CONTEXT_STRATEGY=clear # Automatically clear session
# Set to prompt the user
export GOOSE_CONTEXT_STRATEGY=prompt
```
When you hit the context limit, the behavior depends on your configuration:
**With default settings (no `GOOSE_CONTEXT_STRATEGY` set)**, you'll see this prompt to choose a management option:
```sh
◇ The model's context length is maxed out. You will need to reduce the # msgs. Do you want to?
│ ○ Clear Session
│ ○ Truncate Message
// highlight-start
│ ● Summarize Session
// highlight-end
final_summary: [A summary of your conversation will appear here]
Context maxed out
--------------------------------------------------
Goose summarized messages for you.
```
**With `GOOSE_CONTEXT_STRATEGY` configured**, Goose will automatically apply your chosen strategy:
```sh
# Example with GOOSE_CONTEXT_STRATEGY=summarize
Context maxed out - automatically summarized messages.
--------------------------------------------------
Goose automatically summarized messages for you.
# Example with GOOSE_CONTEXT_STRATEGY=truncate
Context maxed out - automatically truncated messages.
--------------------------------------------------
Goose tried its best to truncate messages for you.
# Example with GOOSE_CONTEXT_STRATEGY=clear
Context maxed out - automatically cleared session.
--------------------------------------------------
```
</TabItem>
</Tabs>
## Maximum Turns
The `Max Turns` limit is the maximum number of consecutive turns that Goose can take without user input (default: 1000). When the limit is reached, Goose stops and prompts: "I've reached the maximum number of actions I can do without user input. Would you like me to continue?" If the user answers in the affirmative, Goose continues until the limit is reached and then prompts again.
This feature gives you control over agent autonomy and prevents infinite loops and runaway behavior, which could have significant cost consequences or damaging impact in production environments. Use it for:
- Preventing infinite loops and excessive API calls or resource consumption in automated tasks
- Enabling human supervision or interaction during autonomous operations
- Controlling loops while testing and debugging agent behavior
This setting is stored as the `GOOSE_MAX_TURNS` environment variable in your [config.yaml file](/docs/guides/config-file). You can configure it using the Desktop app or CLI.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click the `Settings` button on the sidebar
3. Click the `Chat` tab
4. Scroll to `Conversation Limits` and enter a value for `Max Turns`
</TabItem>
<TabItem value="cli" label="Goose CLI">
1. Run the `configuration` command:
```sh
goose configure
```
2. Select `Goose Settings`:
```sh
┌ goose-configure
│
◆ What would you like to configure?
│ ○ Configure Providers
│ ○ Add Extension
│ ○ Toggle Extensions
│ ○ Remove Extension
// highlight-start
│ ● Goose Settings (Set the Goose Mode, Tool Output, Tool Permissions, Experiment, Goose recipe github repo and more)
// highlight-end
└
```
3. Select `Max Turns`:
```sh
┌ goose-configure
│
◇ What would you like to configure?
│ Goose Settings
│
◆ What setting would you like to configure?
│ ○ Goose Mode
│ ○ Router Tool Selection Strategy
│ ○ Tool Permission
│ ○ Tool Output
// highlight-start
│ ● Max Turns (Set maximum number of turns without user input)
// highlight-end
│ ○ Toggle Experiment
│ ○ Goose recipe github repo
│ ○ Scheduler Type
└
```
4. Enter the maximum number of turns:
```sh
┌ goose-configure
│
◇ What would you like to configure?
│ Goose Settings
│
◇ What setting would you like to configure?
│ Max Turns
│
// highlight-start
◆ Set maximum number of agent turns without user input:
│ 10
// highlight-end
│
└ Set maximum turns to 10 - Goose will ask for input after 10 consecutive actions
```
:::tip
In addition to the persistent `Max Turns` setting, you can provide a runtime override for a specific session or task via the `goose session --max-turns` and `goose run --max-turns` [CLI commands](/docs/guides/goose-cli-commands).
:::
</TabItem>
</Tabs>
**Choosing the Right Value**
The appropriate max turns value depends on your use case and comfort level with automation:
- **5-10 turns**: Good for exploratory tasks, debugging, or when you want frequent check-ins. For example, "analyze this codebase and suggest improvements" where you want to review each step
- **25-50 turns**: Effective for well-defined tasks with moderate complexity, such as "refactor this module to use the new API" or "set up a basic CI/CD pipeline"
- **100+ turns**: More suitable for complex, multi-step automation where you trust Goose to work independently, like "migrate this entire project from React 16 to React 18" or "implement comprehensive test coverage for this service"
Remember that even simple-seeming tasks often require multiple turns. For example, asking Goose to "fix the failing tests" might involve analyzing test output (1 turn), identifying the root cause (1 turn), making code changes (1 turn), and verifying the fix (1 turn).
## Token Usage
After sending your first message, Goose Desktop and Goose CLI display token usage.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
The Desktop displays a colored circle next to the model name at the bottom of the session window. The color provides a visual indicator of your token usage for the session.
- **Green**: Normal usage - Plenty of context space available
- **Orange**: Warning state - Approaching limit (80% of capacity)
- **Red**: Error state - Context limit reached
Hover over this circle to display:
- The number of tokens used
- The percentage of available tokens used
- The total available tokens
- A progress bar showing your current token usage
</TabItem>
<TabItem value="cli" label="Goose CLI">
The CLI displays a context label above each command prompt, showing:
- A visual indicator using dots (●○) and colors to represent your token usage:
- **Green**: Below 50% usage
- **Yellow**: Between 50-85% usage
- **Red**: Above 85% usage
- Usage percentage
- Current token count and context limit
</TabItem>
</Tabs>
## Model Context Limit Overrides
Context limits are automatically detected based on your model name, but Goose provides settings to override the default limits:
| Model | Description | Best For | Setting |
|-------|-------------|----------|---------|
| **Main** | Set context limit for the main model (also serves as fallback for other models) | LiteLLM proxies, custom models with non-standard names | `GOOSE_CONTEXT_LIMIT` |
| **Lead** | Set larger context for planning in [lead/worker mode](/docs/tutorials/lead-worker) | Complex planning tasks requiring more context | `GOOSE_LEAD_CONTEXT_LIMIT` |
| **Worker** | Set smaller context for execution in lead/worker mode | Cost optimization during execution phase | `GOOSE_WORKER_CONTEXT_LIMIT` |
| **Planner** | Set context for [planner models](/docs/guides/creating-plans) | Large planning tasks requiring extensive context | `GOOSE_PLANNER_CONTEXT_LIMIT` |
:::info
This setting only affects the displayed token usage and progress indicators. Actual context management is handled by your LLM, so you may experience more or less usage than the limit you set, regardless of what the display shows.
:::
This feature is particularly useful with:
- **LiteLLM Proxy Models**: When using LiteLLM with custom model names that don't match Goose's patterns
- **Enterprise Deployments**: Custom model deployments with non-standard naming
- **Fine-tuned Models**: Custom models with different context limits than their base versions
- **Development/Testing**: Temporarily adjusting context limits for testing purposes
Goose resolves context limits with the following precedence (highest to lowest):
1. Explicit context_limit in model configuration (if set programmatically)
2. Specific environment variable (e.g., `GOOSE_LEAD_CONTEXT_LIMIT`)
3. Global environment variable (`GOOSE_CONTEXT_LIMIT`)
4. Model-specific default based on name pattern matching
5. Global default (128,000 tokens)
**Configuration**
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
Model context limit overrides are not yet available in the Goose Desktop app.
</TabItem>
<TabItem value="cli" label="Goose CLI">
Context limit overrides only work as [environment variables](/docs/guides/environment-variables#model-context-limit-overrides), not in the config file.
```bash
export GOOSE_CONTEXT_LIMIT=1000
goose session
```
</TabItem>
</Tabs>
**Scenarios**
1. LiteLLM proxy with custom model name
```bash
# LiteLLM proxy with custom model name
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="my-custom-gpt4-proxy"
export GOOSE_CONTEXT_LIMIT=200000 # Override the 32k default
```
2. Lead/worker setup with different context limits
```bash
# Different context limits for planning vs execution
export GOOSE_LEAD_MODEL="claude-opus-custom"
export GOOSE_LEAD_CONTEXT_LIMIT=500000 # Large context for planning
export GOOSE_WORKER_CONTEXT_LIMIT=128000 # Smaller context for execution
```
3. Planner with large context
```bash
# Large context for complex planning
export GOOSE_PLANNER_MODEL="gpt-4-custom"
export GOOSE_PLANNER_CONTEXT_LIMIT=1000000
```
## Cost Tracking
Display real-time estimated costs of your session.
<Tabs groupId="interface">
<TabItem value="ui" label="Goose Desktop" default>
To manage live cost tracking:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click the `Settings` button on the sidebar
3. Click the `App` tab
4. Toggle `Cost Tracking` on/off
The session cost is shown at the bottom of the Goose window and updates dynamically as tokens are consumed. Hover over the cost to see a detailed breakdown of token usage. If multiple models are used in the session, this includes a cost breakdown by model. Ollama and local deployments always show a cost of $0.00.
Pricing data is regularly fetched from the OpenRouter API and cached locally. The `Advanced settings` tab shows when the data was last updated and allows you to refresh.
These costs are estimates only, and not connected to your actual provider bill. The cost shown is an approximation based on token counts and public pricing data.
</TabItem>
<TabItem value="cli" label="Goose CLI">
Show estimated cost in the Goose CLI by setting the `GOOSE_CLI_SHOW_COST` [environment variable](/docs/guides/environment-variables.md#session-management) or including it in the [configuration file](/docs/guides/config-file.md).
```
# Set environment variable
export GOOSE_CLI_SHOW_COST=true
# config.yaml
GOOSE_CLI_SHOW_COST: true
```
</TabItem>
</Tabs>