dispatch

Dispatch

A terminal UI for browsing and launching GitHub Copilot CLI sessions. Built with Go and Bubble Tea.

Dispatch reads your local Copilot CLI session store and presents every past session in a searchable, sortable, groupable TUI. Full-text search, conversation previews, directory filtering, five built-in themes, and three launch modes — all without leaving the terminal.

Features

• Full-text search — two-tier: quick search (summaries, branches, repos, directories) returns results instantly; deep search (turns, checkpoints, files, refs) kicks in after 300ms
• Directory filtering — hierarchical tree panel for toggling directory exclusion, persisted to config
• Sorting — 5 fields (updated, folder, name, created, turns) with toggleable direction (s / S)
• Grouping (pivot) modes — flat, folder, repo, branch, date — displayed as collapsible trees with session counts
• Time range filtering — 1 hour, 1 day, 7 days, all (1–4 keys)
• Preview panel — metadata, chat-style conversation bubbles, checkpoints (up to 5), files (up to 5), refs (up to 5), scroll indicators
• Three launch modes — in-place, new tab, new window with per-session overrides
• Session hiding — h to hide, H to show hidden, persistent state
• Settings panel — , to open. 8 fields: Yolo Mode, Agent, Model, Launch Mode, Terminal, Shell, Custom Command, Theme
• Shell picker — auto-detects installed shells, modal picker when multiple available
• 5 built-in themes — Dispatch Dark, Dispatch Light, Campbell, One Half Dark, One Half Light + custom via Windows Terminal JSON
• Help overlay — ? for two-column grouped keyboard shortcuts
• Mouse support — click, double-click, Ctrl+double-click (window), Shift+double-click (tab), pane-aware scroll wheel
• Nerd Font detection — auto-detects Nerd Fonts and uses rich icons, falls back to ASCII
• Windows Terminal theme detection — inherits the active terminal color scheme
• Demo mode — dispatch --demo with synthetic data for experimentation
• Maintenance — --reindex (full chronicle reindex via Copilot CLI PTY), --clear-cache (reset config)
• Cross-platform — Windows (amd64/arm64), macOS (amd64/arm64), Linux (amd64/arm64)

Feature Highlights

Search & Preview	Grouping & Filtering

Settings	Help Overlay

Requirements

• GitHub Copilot CLI installed and used at least once (so the session store exists)
• Go 1.26+ — only required when building from source; binary releases have no dependencies

Installation

Shell script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/jongio/dispatch/main/install.sh | sh

PowerShell (Windows)

irm https://raw.githubusercontent.com/jongio/dispatch/main/install.ps1 | iex

From source

Requires Go 1.26+:

go install github.com/jongio/dispatch/cmd/dispatch@latest

Or clone and build locally:

git clone https://github.com/jongio/dispatch.git
cd dispatch
go install ./cmd/dispatch/

The installer also creates a disp alias automatically.

Usage

dispatch

Example Workflow

1. Run dispatch (or disp) in your terminal
2. Press / to search for previous sessions — try a keyword like "auth" or "refactor"
3. Navigate with arrow keys or j/k
4. Press p to toggle the preview pane and read the conversation
5. Press Enter to resume the selected session (opens in a new tab by default)
6. Use Tab to cycle grouping modes (folder → repo → branch → date → flat)
7. Press s to cycle sort fields, S to flip direction
8. Press , to open settings — change theme, launch mode, model, and more

Key Bindings

Navigation

Launch & Session

Search & Filter

View & Sorting

Time Range (when search is not focused)

Settings & Info

Overlay Navigation

Keys inside overlays (filter, settings, shell picker, help):

Mouse

Configuration

Configuration is stored in the platform-specific config directory:

• Linux: ~/.config/dispatch/config.json
• macOS: ~/Library/Application Support/dispatch/config.json
• Windows: %APPDATA%\dispatch\config.json

Options

Example config.json

{
  "default_shell": "",
  "default_terminal": "",
  "default_time_range": "1d",
  "default_sort": "updated",
  "default_pivot": "folder",
  "show_preview": true,
  "max_sessions": 100,
  "yoloMode": false,
  "agent": "",
  "model": "",
  "launch_mode": "tab",
  "custom_command": "",
  "excluded_dirs": [],
  "theme": "auto"
}

Custom Command

Set custom_command to replace the default Copilot CLI launch entirely. Use {sessionId} as the placeholder. When set, Agent, Model, and Yolo Mode fields are ignored.

"custom_command": "my-tool resume {sessionId}"

Themes

Five built-in color schemes:

• Dispatch Dark
• Dispatch Light
• Campbell
• One Half Dark
• One Half Light

Dispatch Dark	Dispatch Light	Campbell

One Half Dark	One Half Light

Set theme to "auto" (default) for automatic light/dark detection based on your terminal background. Or set it to any built-in scheme name.

Custom Themes

Add custom color schemes using Windows Terminal JSON format in the schemes array of your config file. Each scheme name becomes available in the settings theme selector.

CLI Flags

Environment Variables

Shell Aliases

The installer creates a disp shorthand automatically. To add it manually:

# bash / zsh
alias disp="dispatch"

# PowerShell
Set-Alias -Name disp -Value dispatch

Troubleshooting

"dispatch: command not found"

• Ensure $GOPATH/bin (or the install directory) is in your PATH
• Restart your terminal after installation

"session store not found"

• Copilot CLI must have been used at least once to create the session database
• Check that ~/.copilot/session-store.db exists (or the platform equivalent)
• Override with the DISPATCH_DB environment variable if your database is elsewhere

Sessions not appearing

• Check your time range filter — the default shows only the last day
• Use / to search by keyword
• Check excluded_dirs in your config
• Try dispatch --reindex to rebuild the session index (or press r inside the TUI)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for the security policy and vulnerability reporting.

Built With

• Bubble Tea — TUI framework
• Lip Gloss — Terminal styling
• Bubbles — TUI components
• modernc SQLite — Pure-Go SQLite driver

License

MIT