> ## 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.
# History
> Track all agent activity with searchable, filterable history including Auto Run completions and user annotations.
The History panel provides a timestamped log of all agent activity - both automated (Auto Run) and manual (user interactions). Use it to review past work, resume sessions, and validate completed tasks.
## Entry Types
History entries are categorized by source:
| Type | Label | Description |
| -------- | ------- | -------------------------------------------- |
| **AUTO** | 🤖 AUTO | Entries created by Auto Run task completions |
| **USER** | 👤 USER | Entries created manually by the user |
### Auto Entries
Auto entries are created automatically when Auto Run completes a task. Each entry includes:
* **Summary** of what the agent accomplished
* **Session ID** (clickable to jump to that conversation)
* **Duration** and **cost** of the task
* **Timestamp** of completion
### User Entries
User entries are created in three ways:
1. **History Toggle** - Enable the **History** pill in the AI input box. Each completed prompt-response cycle that did real work creates a user history entry. Turns that only exchanged text (a plain question answered with prose, no tool use) are skipped, so asking a quick question never clutters your history.
2. **`/history` Command** - Run `/history` to create a synopsis entry covering all activity since the last time you ran the command. This is useful for periodic summaries without logging every single interaction.
3. **`/clear` Command** - Running `/clear` automatically creates a history entry before clearing the conversation, preserving a synopsis of your work.
**Toggle the default History behavior** in Settings → General → "Enable 'History' by default for new tabs".
### Synopsis Debounce
Each history entry is generated by a short follow-up run that asks the agent to summarize its work, so a burst of quick completions can produce a burst of synopses. **Synopsis Debounce** (Settings → General, shown beneath the History toggle when it is on) waits for the agent to be idle for a chosen interval before generating the synopsis. Rapid back-to-back completions within the window are coalesced into a single entry covering everything since the last synopsis, so a fast-moving conversation settles into one clean summary instead of many fragments.
Set it to **Off** to generate a synopsis immediately after every completion (the default), or pick **15s**, **30s**, **1 min**, or **2 min** to coalesce. Regardless of this setting, turns that did no real work are never synopsized.
## Filtering History
### By Type
Use the **AUTO** and **USER** filter buttons at the top of the History panel to show or hide each entry type:
* Click **AUTO** to toggle Auto Run entries
* Click **USER** to toggle user-created entries
* Both can be active simultaneously
### By Keyword
Press `Cmd+F` / `Ctrl+F` to open the search box, or click in the filter area to type. The search matches against:
* Entry summaries
* Session names and IDs
* Full response content
### By Time Range
The **Graph View** at the top shows activity distribution over time. **Right-click the graph** to change the time range:
* 24 hours
* 72 hours
* 1 week
* 2 weeks
* 1 month
* 6 months
* 1 year
* All time
The graph bars are clickable - click a time period to jump to entries from that window. Hover over any bar to see the exact count and time range.
## Entry Details
Click any history entry to open the **Detail View**:
The detail view shows:
* **Full entry header** with type badge, session ID, timestamp, and validation status
* **Context usage** - tokens consumed and context window percentage
* **Token breakdown** - input tokens, output tokens
* **Duration** and **cost**
* **Full summary text** of what was accomplished
* **RESUME button** - Jump directly to the AI session to continue from where Maestro left off
### Navigation
* **Prev / Next** buttons to navigate between entries (or use `←` / `→` arrow keys)
* **Close** button to return to the list view
* **Delete** button to remove the entry (with confirmation dialog)
## Validating Entries
The **Validated** flag helps you track which Auto Run tasks have been human-reviewed.
**To mark an entry as validated:**
1. Open the entry detail view
2. Click the **VALIDATED** toggle in the header
Validated entries show a **checkmark icon** (✓✓) in the list view, making it easy to see at a glance which tasks have been reviewed.
**Workflow tip:** After an Auto Run session completes, use the History panel to review each task:
1. Open the first AUTO entry
2. Click **RESUME** to jump to the session and verify the work
3. If satisfied, toggle **VALIDATED**
4. Click **Next** to review the next entry
5. Repeat until all entries are validated
This ensures human oversight of automated work while maintaining the full context needed to continue any task.
## Resuming Sessions
Every history entry with a Session ID has a **RESUME** button. Clicking it:
1. Opens the AI Terminal for that agent
2. Loads the exact session where the work was done
3. Positions you to continue the conversation
This is especially powerful for Auto Run tasks - you can pick up exactly where the agent left off, with full conversation context preserved.
## Keyboard Navigation
### List View
| Key | Action |
| ------------------ | ----------------------------------- |
| `↑` / `↓` | Navigate between entries |
| `Enter` | Open detail view for selected entry |
| `Cmd+F` / `Ctrl+F` | Open search filter |
| `Esc` | Clear selection or close search |
### Detail View
| Key | Action |
| --------- | --------------------------------- |
| `←` / `→` | Navigate to previous/next entry |
| `Esc` | Close detail view, return to list |
## Cross-Host Shared History
When working with [SSH Remote Execution](/ssh-remote-execution), history entries can be synchronized across machines. Remote entries appear with a **☁ Remote** pill and a hostname badge showing their origin.
This enables:
* **Same user, multiple machines** - see your work from any machine you use
* **Team collaboration** - see what teammates have done on a shared project
Enable this per-session via the **Sync history to remote** toggle in the SSH Remote Execution dropdown. See [Collaborating over SSH](/ssh-remote-execution#collaborating-over-ssh) for full details.
## Storage
History is stored per-session in JSON files within the `history/` subdirectory of your Maestro data folder:
* **macOS**: `~/Library/Application Support/maestro/history/.json`
* **Windows**: `%APPDATA%/maestro/history/.json`
* **Linux**: `~/.config/maestro/history/.json`
The maximum number of entries per session is controlled by the **Maximum Log Buffer** setting in Settings → Display (default: 5,000). History files can be passed to AI agents as context for understanding past work patterns.
## Help Panel
Click the **?** button in the History panel header to open a detailed guide explaining all features, entry types, status indicators, and keyboard shortcuts.