Session Tracking
Applies to: Dispatch v1.0.0, last verified 2026-04-05
Dispatch tracks sessions from all four supported providers and shows them in a unified list. This page covers what sessions are, how to read the session list, and what happens when you click into one.
TL;DR: A session is one running agent process from any provider. Dispatch reads session data from Claude Code (real-time JSONL watcher), Codex, Copilot, and Gemini (30-second poller) to show live status, task lists, subagents, and git branch.
What is a session?
Section titled “What is a session?”A session is a single running agent process. Every time you start claude, codex, or gemini in a terminal (or interact with Copilot in VS Code), it creates a new session. Dispatch reads each provider’s local session data and surfaces:
- What the session is currently working on (a task list, if the agent used task-tracking tools)
- Which subagents it has spawned (if any)
- Which git branch it is operating on (if the working directory is a git repository)
- A provider badge (Claude, Codex, Copilot, or Gemini) on each session card
How sessions are discovered
Section titled “How sessions are discovered”| Provider | Mechanism | Latency |
|---|---|---|
| Claude Code | File watcher on JSONL conversation files | Near-instant (seconds) |
| Codex | Multi-session poller scanning .codex/ logs | Up to 30 seconds |
| Copilot | Multi-session poller scanning workspace files | Up to 30 seconds |
| Gemini | Multi-session poller scanning Gemini chat JSON | Up to 30 seconds |
The poll interval is configurable via the DISPATCH_PROVIDER_POLL_MS environment variable (default: 30000 ms). When HTTP hooks are configured (currently Claude Code), updates arrive in real time regardless of the poll interval.
Viewing sessions
Section titled “Viewing sessions”Sessions appear in the center panel under a Sessions tab. The tab is shown alongside Epics and Tasks only when the “Session List” toggle is enabled in Settings (it is on by default).
A live count badge on the Sessions tab shows how many active sessions exist for the currently selected project.
Single-project view
Section titled “Single-project view”When you have one project selected, all sessions for that project are listed flat. Active sessions appear first. Idle sessions appear below a dashed offline divider.
If there are idle sessions, a small ”− hide idle” button appears in the section header. Click it to collapse idle sessions; click ”+ N idle” to reveal them again.
All-projects view
Section titled “All-projects view”When no project filter is selected (you are looking at all projects), sessions are grouped by project name. Each group shows its own N/total active count and its own hide/show idle control.
Session events in the activity feed
Section titled “Session events in the activity feed”When a session starts or ends, the activity feed creates an entry for it. That entry uses the session’s opening prompt as its title rather than a generic placeholder. The origin badge tells you whether the session was launched from a terminal (terminal, green) or an IDE integration (ide, cyan). Each session event also shows a provider badge (Claude, Codex, Copilot, or Gemini) so you can tell at a glance which tool the session belongs to. Expanding the entry shows the full prompt text in a Prompt callout.
This means the same prompt preview you see on the session card (described below) also appears in the activity feed, so you can identify a session from either panel without opening the full drawer.
For full details on the activity feed entry format, see Activity Feed.
Reading a session card
Section titled “Reading a session card”Each session is displayed as a card with the following information:
| Element | What it shows |
|---|---|
| Status dot | A color-coded, animated dot showing the agent’s current micro-state. See Status dot reference below. |
| Provider badge | The CLI tool that created this session (Claude, Codex, Copilot, or Gemini), shown as a colored pill with brand colors. |
| Title | The first 60 characters of the prompt that started the session. Falls back to the first 8 characters of the session ID if no prompt is available. |
| Session ID badge | An 8-character hex prefix identifying the session, shown below the title when a prompt preview is available. |
| Git branch badge | The branch the session’s working directory is on, shown in cyan. Only appears when a branch is detected. |
| Subagents badge | A purple “N subs” badge when the session has spawned subagents. Click it to collapse or expand the subagent list without opening the full drawer. |
Task list on the card
Section titled “Task list on the card”If the session used task-tracking tools (such as Claude Code’s TaskCreate), its task list appears below the header row. Each task shows a status icon:
- ● (grey): pending
- ▶ (purple): in progress
- ✓ (green): completed; the task subject is struck through
Subagents on the card
Section titled “Subagents on the card”When the subagent list is expanded, each subagent appears as a nested sub-card indented under the parent session. Sub-cards show the same activity dot, the subagent’s type (e.g. @staff-engineer), an optional description, and the subagent’s own task list.
Offline appearance
Section titled “Offline appearance”Cards for idle sessions are shown at reduced opacity and desaturated. When you hover an idle card it lifts slightly but does not show the active neon glow, so the offline status remains visually distinct even on hover.
Status dot reference
Section titled “Status dot reference”Every session card and subagent sub-card shows a small circular dot in its header. The dot reflects the agent’s current micro-state: what it is doing right now, based on the latest entries in the session’s log data. For Claude Code sessions, the dot updates on every JSONL file change. For other providers, the dot updates on each poll cycle (default 30 seconds).
| State | Color | Animation | Meaning |
|---|---|---|---|
thinking | Cyan | Slow breathing pulse | The model is generating a response. |
tool_use | Purple | Ring pulse | A tool is executing. |
waiting | Amber | Slow ring pulse | The model has replied with plain text and is waiting for your next message. |
approval | Amber | Slow ring pulse | The agent is blocked on a permission prompt. A tool call is pending user approval. Visually identical to waiting but the aria-label reads “Waiting for approval”. |
idle | Grey | Static (no animation) | No recent activity. |
error | Pink/Red | Blink | Reserved for future use. |
Tooltip: When the state is tool_use, hovering the dot shows a tooltip with the name of the active tool, for example “Running Bash” or “Running Write”. Internal task-management tools are excluded from this label.
Subagent borders: The left border of each subagent sub-card uses the same color coding as the dot. A cyan border means the subagent is thinking; purple means it is running a tool; amber means it is waiting or pending approval; grey means it is idle.
How the server derives micro-state
Section titled “How the server derives micro-state”For Claude Code sessions, on every file change the server checks the end of the session’s JSONL conversation file to figure out the current micro-state. For non-Claude providers, the poller derives micro-state from the provider’s native session data format.
- Last record is a
userrecord →thinking - Last record is an
assistantrecord withtool_useblocks and no subsequenttool_result→tool_use - Last record is an
assistantrecord with text only (notool_use) →waiting - File has not been modified recently →
idle(takes priority over JSONL content) - Any read or parse failure →
idle(safe fallback)
Cache efficiency
Section titled “Cache efficiency”Dispatch tracks cache efficiency per session (what fraction of tokens were served from cache rather than billed at full input rate). For the full formula, how the aggregate ratio is computed, and what “poor performers” means in the cost dashboard, see Cost Accuracy.
The session drawer
Section titled “The session drawer”Click any session card to open the session drawer. It slides in from the right and shows the full details for that session.
Header
Section titled “Header”The drawer header shows:
- The full prompt text (not truncated), or the session ID if no prompt is available
- An activity dot and Active / Idle label
- The project name
- The git branch badge (if present)
- The full session ID
Details section
Section titled “Details section”The Details section shows the session’s working directory path (cwd), project name, and full session ID in a two-column grid.
Tasks section
Section titled “Tasks section”The Tasks section lists every task created by the session, each with its status icon and full subject text. If the session has a description for a task (beyond the subject line), it appears beneath the subject in smaller text.
If the session did not produce any tasks, the section shows: “No tasks.”
Subagents section
Section titled “Subagents section”When the session has spawned subagents, a Subagents section appears with a count badge. Each subagent row shows its activity dot, type (e.g. @staff-engineer), optional description, and a collapsed task list.
Click a subagent row to open the subagent detail drawer, a panel that slides in to the left of the session drawer and shows:
- Task prompt: the full instruction the orchestrator sent to this subagent; absent until the subagent’s first conversation turn is recorded
- Current activity: what the subagent is doing right now, with a live pulse when it is thinking or running a tool; includes the file path when a file-system tool is active
- Final reply: the subagent’s last assistant text block (up to 4,000 characters)
- Files read: deduplicated list of file paths the subagent has read
- Files modified: files the subagent has written or edited, with
+N / -Nline-count changes per file - View Diff button: opens a full-screen unified diff viewer when diff data is available
The task list is still visible inside the detail drawer. The collapse/expand chevron button on the right of the row toggles the inline task list without opening the drawer.
Agent spawn graph
Section titled “Agent spawn graph”When a session has spawned subagents, a small graph icon button appears in the drawer header. Clicking it opens the Agent Spawn Tree: a modal showing the parent session as the root node and each subagent as a child node, connected by labelled edges.
Edge styles in the graph:
| Edge style | Meaning |
|---|---|
| Solid line | Subagent was launched synchronously (blocking) |
| Dashed line | Subagent was launched in the background (fire-and-forget) |
Active nodes glow; idle nodes are dimmed. Close the graph by clicking the ✕ button, pressing Escape, or clicking the backdrop.
Session click-through from the agent sidebar
Section titled “Session click-through from the agent sidebar”The agent sidebar on the left shows your defined agent personas. Clicking a persona opens the Agent Profile Panel on the right. The panel has a Live Sessions section listing every session where that agent type is currently active. Clicking any of those session entries opens the full session drawer described above.
How sessions link to phases
Section titled “How sessions link to phases”Dispatch automatically links sessions to phases in your epics. When you open a phase in the Epic Drawer, any sessions Dispatch matched to that phase appear as a Sessions row, letting you navigate directly to the conversation replay.
Linking is done by scoring each session-phase pair. Two signals matter most:
Git branch name (strongest signal). Dispatch checks whether the session’s git branch contains the epic slug. A branch named feat/multi-cli-agent-support links to the multi-cli-agent-support epic. The slug is the kebab-case directory name under .tasks/, and the match is case-insensitive substring, so feat/multi-cli-agent-support, fix/multi-cli-agent-support, and multi-cli-agent-support all match. A correct branch name adds +5 points to the score.
Temporal overlap (primary gate). Session timestamps are compared against the phase’s work window. Phase windows are derived from completion timestamps in execution-log.md: a DONE phase gets the window between the previous phase completion and its own; an IN_PROGRESS phase gets from the previous completion to now. If a session has no time overlap with a phase window at all, it is excluded regardless of branch name. Overlap duration adds 1–10 points proportional to hours of overlap.
A session maps to at most one phase per epic. The highest-scoring match wins.
If a session does not appear under a phase, the most common cause is the git branch name not containing the epic slug. Check what branch the session ran on (visible on the session card as a cyan badge) and compare it to the epic’s directory name in .tasks/. Renaming or switching to a branch that includes the slug will cause the session to link on the next dashboard refresh.
Keyboard shortcuts
Section titled “Keyboard shortcuts”| Key | Action |
|---|---|
| Escape | Close the innermost open panel in order: subagent detail drawer → spawn graph → session drawer |
| Click backdrop | Close the session drawer |
The session card also responds to keyboard activation: press Enter or Space when a card is focused to open its drawer.
Controlling session list visibility
Section titled “Controlling session list visibility”Go to Settings → Layout and toggle Session List off to hide the Sessions tab entirely. This hides the tab and the view but does not affect session data collection. You can re-enable it at any time.