Search

Applies to: Dispatch v1.0.0, last verified 2026-04-07

This page explains how to use both search surfaces in Dispatch to find sessions, epics, agents, and activity events.

Dispatch has two search surfaces built for different jobs.

Surface	Shortcut	When to use
Command Palette	Cmd+K / Ctrl+K	Quick jump when you know roughly what you are looking for
Search Panel	Cmd+Shift+F / Ctrl+Shift+F	Faceted discovery to filter by type, status, provider, or date

Both search across the same four corpora: epics, sessions, agents, and activity events.

---

What you can search

Corpus	What is indexed
Epics	Epic title, plan body, phase titles
Sessions	Opening prompt, project name, git branch, agent name
Agents	Agent name, persona slug, assigned project
Activity	Event type, associated epic title, persona name

Session conversation content (the full message history) is not indexed by default. It can be enabled separately. See Searching inside conversations.

---

Quick search: Command Palette (Cmd+K)

Press Cmd+K (Mac) or Ctrl+K (Linux/Windows) to open the palette from anywhere in the dashboard.

Example: You want to find the session where you debugged an authentication bug.

1. Press Cmd+K
2. Type auth error
3. Use ↑ / ↓ to highlight the matching session
4. Press Enter to open the session drawer

Clicking a result works too.

How the palette behaves

• Empty input: shows your five most recent searches
• Typing: results appear after a short pause; stale requests are automatically cancelled so fast typing never shows outdated results
• Results grouped: Epics first, then Sessions, Agents, Activity. Each group shows up to 5 results with a “Show all (N)” button to expand
• Deep-links: selecting a result opens the relevant drawer (Epic Drawer, Session Drawer, Agent Panel, or jumps to the Activity entry) and closes the palette
• No matches: a “Start a new task with this prompt” button appears so you can immediately hand the query to an agent
• Close: Esc or click the backdrop

Recent searches are stored in your browser’s local storage. They persist across page reloads but are local to this device and browser.

---

Faceted search: Search Panel (Cmd+Shift+F)

Press Cmd+Shift+F (Mac) or Ctrl+Shift+F (Linux/Windows), or click the magnifying-glass icon in the header, to open the Search Panel drawer.

The Search Panel is a right-side drawer with free-text search and filter chips. Use it when you want to narrow results by type, status, provider, or time window rather than just searching by name.

Example: You want all blocked epics from the last week that a Claude agent worked on.

1. Press Cmd+Shift+F
2. Type a query (or leave it empty to browse)
3. Click the Epic chip under Entity Type
4. Click the BLOCKED chip under Status
5. Click the Claude chip under Provider
6. Set a Date Range from seven days ago to today

Results update as you change filters.

Filter chips

Filter group	Options	Logic
Entity Type	Epic, Session, Agent, Activity	Multiple selections: OR within this group
Status	TODO, IN_PROGRESS, DONE, BLOCKED, ON_HOLD, CANCELLED	Multiple selections: OR within this group
Provider	Claude, Codex, Copilot, Gemini	Multiple selections: OR within this group
Date Range	From / To date pickers	AND: both bounds apply simultaneously

Filters across different groups combine with AND. For example: Entity Type = Session AND Status = IN_PROGRESS shows only in-progress sessions.

Click Clear to remove all active filters at once.

Results

Results appear in four sections: Epics, Sessions, Agents, Activity. Each result row shows a type badge, title, and subtitle. Matched text is highlighted inline.

If the index has not synced recently, a small “results may be outdated” badge appears next to the result count. This clears automatically after the next successful search.

Zero results

When no results match, Dispatch shows:

• “No matches for ‘your query’”
• A hint to clear filters or broaden the search if filters are active
• A “Start a new task with this prompt” button (when agent spawning is configured)

---

Advanced mode

After you have run three searches, an Advanced collapsible section appears below the filter chips. It lets you scope the search to specific fields rather than searching all indexed text at once.

Scope field	What it searches
Epic plan body	The full prose body of each plan.md
Phase title / description	Phase titles from the YAML frontmatter
Agent name	Agent persona slug and display name
Activity event type	The event type string (phase_completed, session_started, etc.)
Conversation content	Full message history (requires a feature flag; see Searching inside conversations)

Leaving all scope fields unchecked searches all default fields. Checking one or more scope fields restricts the search to only those fields.

The Advanced section auto-expands once you have run three searches. It stays collapsed before that to avoid cluttering the panel for new users.

---

Saved queries

Any query can be saved for quick reuse.

1. Type a query in the Search Panel
2. Click the bookmark icon (save button) that appears to the right of the input
3. Enter a name, or leave blank to use the first 40 characters of the query
4. Press Enter or click Save

Saved queries appear in the Saved (device-only) section when the search input is empty, below Recent searches.

To load a saved query: click its name. To delete one: click the ✕ button on the right, or focus the item and press Cmd+Delete / Ctrl+Delete.

Important: Saved queries are stored in browser local storage. They do not sync across devices or browsers. The “device-only” label in the UI reflects this.

---

Searching inside conversations

By default, Dispatch indexes only session metadata (the opening prompt, project, branch name), not the full conversation history. This is fast and keeps the index small.

To search inside the actual message content of a session, enable the search_stream_grep_enabled feature flag in ~/.dispatch/config.json:

{
  "featureFlags": {
    "search_stream_grep_enabled": true
  }
}

Restart the Dispatch server after editing the file.

With the flag on, a Conversation content checkbox becomes active in the Advanced section of the Search Panel. Check it, then search. Dispatch will grep the selected session’s JSONL log file using a background worker thread with a timeout.

Limitations:

• Stream-grep runs one query at a time (subsequent requests queue, not fail)
• Very large session files are skipped automatically
• If a session file has been deleted since indexing, you will see “This session’s message log is no longer available” rather than an error

---

Shared recent searches

The Command Palette and Search Panel share the same recent-search history. A query you typed in Cmd+K will appear as a recent search the next time you open the Search Panel, and vice versa.

The list stores the last five distinct queries, newest first, in browser local storage.

---

Keyboard shortcuts

Key	Action
Cmd+K / Ctrl+K	Open Command Palette
Cmd+Shift+F / Ctrl+Shift+F	Open Search Panel
↑ / ↓	Navigate results or recent searches
Enter	Open the highlighted result
Esc	Close palette or panel
/	(Search Panel only) Refocus the search input from anywhere in the panel
Cmd+Backspace / Ctrl+Backspace	(Search Panel only) Clear the query
Cmd+Delete / Ctrl+Delete	(Search Panel only) Delete a focused saved query

---

First-run tooltip

The first time you open the Search Panel, a brief tooltip appears:

Press / to focus search, Cmd+Shift+F to open/close.

It fires exactly once per install (tracked in browser local storage). If you missed it, the Keyboard Shortcuts page has the full reference.

---

FAQ

Why does a result show up even though the text I searched for is not in the title?

The index searches multiple fields. For a session, that includes the project name, git branch, and the agent name, not just the opening prompt. The matched field is highlighted in the result subtitle.

Searches that worked yesterday return nothing today.

The search index is rebuilt each time the server refreshes its state (every file change or poll cycle). If the server was just restarted, the first search triggers a full index build. Wait a few seconds and retry.

Can I share a search URL with a teammate?

The Search Panel encodes the current query and filters in the URL (?search=&scope=&result=). Copying and sharing the URL gives your teammate the same search state. Saved queries are device-only and do not travel with the URL.

Why is the Advanced section not showing?

The Advanced section is hidden until you have run three searches (progressive disclosure). Run a few searches and it will appear automatically.

---

Related pages

• Sessions: understanding session cards and the session drawer
• Epics and Tasks: epic cards and the epic drawer
• Activity Feed: the activity event stream
• Keyboard Shortcuts: complete shortcut reference