Configuration — Dispatch

Config File Location

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

Validate hand-edited files with dispatch config validate, ordispatch config validate --json for CI-friendly diagnostics. Use dispatch config validate --path <file> for alternate profiles. Editor completions are available fromdocs/config.schema.json, anddispatch config schema prints the same generated JSON Schema.

Managed by Dispatch

These values are maintained as you use Dispatch; edit them only when importing or repairing configuration.

Key	Type	Default	Description
`config_version`	int	`2`	Configuration schema version used to apply migrations.
`hiddenSessions`	array	`[]`	Session IDs hidden from the main list.
`sessionNotes`	object	`{}`	Per-session notes created with the note action.
`sessionLaunches`	object	`{}`	Per-session launch statistics used by frecency sorting.
`sessionTags`	object	`{}`	Per-session tags used for grouping and tag: searches.
`sessionAliases`	object	`{}`	Per-session aliases for opening sessions by a short name.
`views`	array	`[]`	Saved named views combining filters, sorting, and grouping.
`active_view`	string	`""`	Current named view. Empty or "Default" uses no named view.

Options

Key	Type	Default	Description
`default_shell`	string	`""`	Preferred shell (bash, zsh, pwsh, cmd.exe). Empty = auto-detect.
`default_terminal`	string	`""`	Terminal emulator. Empty = auto-detect.
`default_time_range`	string	`"1d"`	Time filter on startup: 1h, 1d, 7d, all.
`default_sort`	string	`"updated"`	Sort field: updated, created, turns, name, folder, frecency.
`default_sort_order`	string	`"desc"`	Sort direction: asc, desc.
`default_pivot`	string	`"folder"`	Grouping mode: none, folder, repo, branch, date, host.
`default_collapsed`	bool	`false`	Start group header rows collapsed (single-line).
`show_preview`	bool	`true`	Show preview pane on startup.
`preview_position`	string	`"right"`	Position of the preview pane: right, bottom, left, top.
`redact_preview_secrets`	bool	`false`	Mask common secret patterns (bearer tokens, GitHub PATs, connection strings, .env secrets) with [redacted] in the preview pane. Rendering only; stored data is unchanged.
`conversation_newest_first`	bool	`true`	Show newest conversation turns first in the preview.
`max_sessions`	int	`100`	Maximum sessions to load from the store.
`yoloMode`	bool	`false`	Pass --allow-all to Copilot CLI (auto-confirm commands).
`agent`	string	`""`	Pass --agent <name> to Copilot CLI.
`model`	string	`""`	Pass --model <name> to Copilot CLI.
`launch_mode`	string	`"tab"`	How to open sessions: in-place, tab, window, pane.
`pane_direction`	string	`"auto"`	Split direction for pane mode: auto, right, down, left, up (see Pane Direction Semantics below).
`resume_session_command`	string	`""`	Resume session command ({sessionId} is replaced). Defaults to copilot --resume.
`new_session_command`	string	`""`	Command to launch new sessions ({cwd} is replaced). Defaults to copilot.
`excluded_dirs`	array	`[]`	Directory paths to hide from the session list.
`excluded_words`	array	`[]`	Words to filter sessions by. Sessions whose name or turn content contains any word (case-insensitive) are hidden.
`attention_threshold`	string	`"15m"`	Duration after which an inactive running session is marked stale instead of waiting/active.
`notify_on_waiting`	bool	`false`	Ring the terminal bell and show a footer message when a session enters the waiting state.
`auto_refresh_seconds`	int	`(unset)`	Session-list poll interval in seconds. Unset uses the default (2s); 0 disables polling; a positive value sets the interval (minimum 1s).
`theme`	string	`"auto"`	Color scheme: auto or a named scheme.
`workspace_recovery`	bool	`true`	Detect sessions interrupted by crash/reboot. Disable if you see false positives.
`ai_search`	bool	`false`	Enable Copilot SDK-powered AI semantic search in addition to the local FTS5 index.
`hidden_columns`	array	`[]`	Optional session-list columns to hide (repo, folder, turns, host). Empty shows every column.
`keybindings`	object	`{}`	Remap keyboard shortcuts. Keys are action names; values are comma-separated key lists (see the Keys page).
`launch_sets`	array	`[]`	Named, ordered session ID collections for repeated multi-session launches. Missing IDs are shown and skipped.
`project_roots`	array	`[]`	Absolute directories to scan for git repos shown as New session rows when they have no recent session.
`favoriteSessions`	array	`[]`	Session IDs starred as favorites.

Example

{
  "default_shell": "",
  "default_terminal": "",
  "default_time_range": "1d",
  "default_sort": "updated",
  "default_pivot": "folder",
  "show_preview": true,
  "preview_position": "right",
  "max_sessions": 100,
  "yoloMode": false,
  "agent": "",
  "model": "",
  "launch_mode": "tab",
  "pane_direction": "auto",
  "resume_session_command": "",
  "excluded_dirs": [],
  "excluded_words": [],
  "favoriteSessions": [],
  "launch_sets": [],
  "project_roots": [],
  "theme": "auto",
  "workspace_recovery": true
}

Themes

Five built-in color schemes:

Dispatch Dark
Dispatch Light
Campbell
One Half Dark
One Half Light

Set theme to auto for automatic light/dark detection based on your terminal.

Custom Themes

Add custom schemes using Windows Terminal JSON format in the schemes config array. Each scheme's name field becomes available in the settings theme selector.

"schemes": [
  {
    "name": "My Custom Theme",
    "background": "#1a1b26",
    "foreground": "#c0caf5",
    "black": "#15161e",
    "red": "#f7768e",
    "green": "#9ece6a",
    "yellow": "#e0af68",
    "blue": "#7aa2f7",
    "purple": "#bb9af7",
    "cyan": "#7dcfff",
    "white": "#a9b1d6"
  }
]

Resume Session Command

Set resume_session_command to replace the default Copilot CLI launch command entirely. Use {sessionId} as a placeholder for the session ID.

When a Resume Session Command is set, the Agent, Model, and Yolo Mode fields are ignored (dimmed in the settings panel).

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

Pane Direction Semantics

When launch_mode is "pane", thepane_direction value maps to Windows Terminal's-H / -V split-pane flags:

down → -H — horizontal split (divider runs horizontally, new pane below)
up → -H — horizontal split (WT controls actual placement; closest available)
right → -V — vertical split (divider runs vertically, new pane to the right)
left → -V — vertical split (WT controls actual placement; closest available)
auto / empty — no flag; Windows Terminal decides automatically

Note: -H and -V control split orientation only (the direction the divider runs). Windows Terminal decides actual pane placement based on available space.