> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runmaestro.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Context Management
> Compact, merge, and transfer conversation context between sessions and agents.
## Tab Menu
Hover over any tab with an established session to access the tab menu overlay:
| Action | Requires Session | Description |
| ----------------------------------- | ---------------- | ------------------------------------------------------------------------ |
| **Copy Session ID** | Yes | Copy the session ID to clipboard (for session continuity) |
| **Star Session** | Yes | Bookmark this session for quick access |
| **Rename Tab** | Yes | Give the tab a descriptive name |
| **Mark as Unread** | Yes | Add unread indicator to the tab |
| **Export as HTML** | No (1+ logs) | Export conversation as self-contained HTML file |
| **Context: Copy to Clipboard** | No (1+ logs) | Copy the full conversation to clipboard |
| **Context: Compact** | No (5+ logs) | Compress context while preserving key information |
| **Context: Merge Into** | Yes | Merge this context into another session |
| **Context: Send to Agent** | Yes | Transfer context to a different agent |
| **Context: Publish as GitHub Gist** | No (1+ logs) | Share conversation as a public or secret GitHub Gist (requires `gh` CLI) |
| **Move to First Position** | No | Move this tab to the first position |
| **Move to Last Position** | No | Move this tab to the last position |
### Tab Close Operations
The tab menu also provides bulk close operations for managing multiple tabs:
| Action | Description |
| --------------------------- | --------------------------------------- |
| **Close** | Close the current tab |
| **Close Others** | Close all tabs except this one |
| **Close Tabs to the Left** | Close all tabs to the left of this one |
| **Close Tabs to the Right** | Close all tabs to the right of this one |
These operations respect the **Unread Filter**: when the filter is active, only visible tabs are affected - hidden "read" tabs are preserved.
**Position-aware options:** The menu intelligently hides inapplicable options:
* First tab: "Close Tabs to the Left" is disabled
* Last tab: "Close Tabs to the Right" is disabled
* Single tab: "Close" and "Close Others" are disabled
All close operations support **undo** - press `Cmd+Shift+T` / `Ctrl+Shift+T` to reopen recently closed tabs (up to 25 tabs are remembered).
These actions are also available via **Quick Actions** (`Cmd+K` / `Ctrl+K`) with keyboard shortcuts displayed:
## Tab Export
Export any tab conversation as a self-contained HTML file:
1. Hover over the tab → **Export as HTML**
2. Choose a save location when prompted
The exported HTML file includes:
* **Full conversation history** with all messages
* **Your current theme colors** - the export adopts your active Maestro theme
* **Maestro branding** with links to the website and GitHub
* **Session metadata** - agent type, working directory, timestamps, token usage
* **Rendered markdown** - code blocks, tables, and formatting preserved
This is useful for sharing conversations, creating documentation, or archiving important sessions.
**Alternative sharing options:**
* **Context: Copy to Clipboard** - Copy the raw conversation text to clipboard (for pasting into documents or chat)
* **Context: Publish as GitHub Gist** - Share as a public or secret GitHub Gist (requires `gh` CLI to be installed)
***
Context management lets you combine or transfer conversation history between sessions and agents, enabling powerful workflows where you can:
* **Compact & continue** - Compress your context to stay within token limits while preserving key information
* **Merge sessions** - Combine context from multiple conversations into one
* **Transfer to other agents** - Send your context to a different AI agent (e.g., Claude Code → Codex)
## Context Window Warnings
As your conversation grows, Maestro monitors context window usage and displays warnings when you're approaching limits.
The warning banner appears below the input box showing:
* Current context usage percentage
* **Compact & Continue** button for one-click context compression
### Why Context Usage Matters
**Operating near context limits degrades AI performance.** When context reaches \~80% capacity or higher:
* The AI loses access to earlier parts of your conversation
* Important decisions, code changes, and context get pushed out
* Response quality drops as the model struggles to maintain coherence
* You may experience more hallucinations and forgotten instructions
For best results, **compact your context before reaching 60-70% usage** - don't wait for the red warning.
### Configuring Warnings
Customize warning thresholds in **Settings** (`Cmd+,` / `Ctrl+,`) → **Display** → **Context Window Warnings**:
| Setting | Default | Description |
| ------------------------------------- | ------- | --------------------------------------------------- |
| **Show context consumption warnings** | Enabled | Toggle warning banners on/off |
| **Yellow warning threshold** | 60% | Early warning - good time to consider compacting |
| **Red warning threshold** | 80% | Critical - compact immediately to avoid degradation |
**Recommended thresholds:**
* Set yellow to **50-60%** if you prefer earlier warnings
* Set red to **70-80%** - going higher risks quality degradation
* Lower both thresholds if you frequently work on complex tasks that require the AI to remember many details
## Compact & Continue
When your conversation approaches context limits, you can compress it while preserving essential information:
1. **Hover over** a tab → **"Context: Compact"**, or use **Command Palette** (`Cmd+K` / `Ctrl+K`) → "Context: Compact"
2. The AI compacts the conversation, extracting key decisions, code changes, and context
3. A new tab opens with the compressed context, ready to continue working
**When to use:**
* The context warning sash appears (yellow at 60%, red at 80% usage)
* You want to continue a long conversation without losing important context
* You need to free up context space for new tasks
**What gets preserved:**
* Key decisions and their rationale
* Code changes and file modifications
* Important technical details and constraints
* Current task state and next steps
### How Compaction Works
Compaction uses a multi-pass approach to handle conversations of any size:
**Eligibility Check:**
Compaction requires any one of these conditions:
* Context usage ≥ 25% (as reported by the agent), OR
* Estimated conversation size ≥ 2,000 tokens (\~8k characters), OR
* At least 8 meaningful messages (user and AI exchanges)
Multiple fallbacks ensure compaction is available even when the context gauge resets to 0 (which can happen when context fills up) - as long as there's meaningful conversation history, you can compact it.
**Single-Pass Compaction (\< 50k tokens):**
For smaller conversations, the entire context is sent to a fresh AI agent in batch mode, which returns a compressed summary.
**Chunked Compaction (≥ 50k tokens):**
For larger conversations that exceed 50,000 tokens:
1. **Chunking** - The conversation is split into chunks of \~50k tokens each
2. **Parallel summarization** - Each chunk is sent to a separate batch-mode agent process
3. **Combination** - Chunk summaries are combined together
4. **Consolidation** - If the combined result exceeds 40k tokens, additional passes reduce it further
**Consolidation Passes:**
When chunk summaries combine to more than 40k tokens, the system performs up to 3 consolidation passes:
* Each pass asks the AI to aggressively reduce the summary while preserving key information
* A pass is only accepted if it reduces size by at least 10%
* Consolidation stops early if no meaningful reduction is achieved
This ensures that even a conversation at 95%+ context capacity (e.g., 190k tokens) will be compacted to a manageable size (\~40k tokens or less) that leaves room for continued work.
**Progress Indicators:**
During compaction, you'll see status updates:
* "Extracting context..." - Preparing the conversation
* "Summarizing chunk 1/4..." - Processing large conversations in parts
* "Consolidation pass 1/3..." - Additional reduction passes if needed
* "Finalizing compacted context..." - Creating the new tab
## Merging Sessions
Combine context from multiple sessions or tabs into one:
1. **Hover over** a tab → **"Context: Merge Into"**, or use **Command Palette** (`Cmd+K` / `Ctrl+K`) → "Context: Merge Into"
2. Search for or select the target session/tab from the modal
3. Review the merge preview showing estimated token count
4. Optionally enable **Clean context** to remove duplicates and reduce size
5. Click **"Merge Into"**
The modal shows:
* **Paste ID** tab - Enter a specific session ID directly
* **Open Tabs** tab - Browse all open tabs across all agents
* **Token estimate** - Shows source size and estimated size after cleaning
* **Agent grouping** - Tabs organized by agent with tab counts
The merged context creates a new tab in the target session with conversation history from both sources. Use this to consolidate related conversations or bring context from an older session into a current one.
**What gets merged:**
* Full conversation history (user messages and AI responses)
* Token estimates are shown before merge to help you stay within context limits
**Tips:**
* You can merge tabs within the same session or across different sessions
* Large merges (100k+ tokens) will show a warning but still proceed
* Self-merge (same tab to itself) is prevented
* Enable "Clean context" for large merges to reduce token count
## Sending to Another Agent
Transfer your context to a different AI agent:
1. **Hover over** a tab → **"Context: Send to Agent"**, or use **Command Palette** (`Cmd+K` / `Ctrl+K`) → "Context: Send to Agent"
2. Search for or select the target agent from the list
3. Review the token estimate and cleaning options
4. Click **"Send to Session"**
The modal shows:
* **Searchable agent list** with status indicators (Idle, Busy, etc.)
* **Agent paths** to distinguish between agents with similar names
* **Token estimate** - Shows source size and estimated size after cleaning
* **Clean context option** - Remove duplicates and reduce size before transfer
**Context Cleaning:**
When transferring between agents, the context can be automatically cleaned to:
* Remove duplicate messages and verbose output
* Condense while preserving key information
* Optimize token usage for the target session
Cleaning is enabled by default but can be disabled for verbatim transfers.
**Use Cases:**
* Start a task in Claude Code, then hand off to Codex for a different perspective
* Transfer a debugging session to an agent with different tool access
* Move context to an agent pointing at a different project directory
* Share context with a worktree sub-agent working on the same codebase