Frequently Asked Questions

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

This page answers the most common questions about setting up Dispatch, working with agents, and understanding what to do when something goes wrong.

Do I need to change my agent prompts to use Dispatch?

No. Dispatch reads files your agents write and session data from all four supported providers (Claude Code, Codex, Copilot, Gemini). It does not inject itself into agent prompts or require any API calls from agents.

The one exception: if you want full coordination across multiple agents (phase claiming, handoff notes, live status in the Tasks view), your agents need to follow the .tasks/ protocol. Dispatch ships with 13 bundled agent persona files that have the protocol already included. See Agent Catalog and .tasks/ Protocol Reference.

If your existing agents do not write to .tasks/, Dispatch still tracks their sessions. You get session cards, provider badges, and cost tracking. You just will not see phase progress or the Tasks view for their work.

Optionally, agents can call Dispatch’s MCP tools to query state, update phases, and emit activity events. This is not required. Agents that only write to .tasks/ work without it.

Does this work on Windows?

Dispatch itself (the Node.js server and React dashboard) runs on Windows. The web UI works in any browser.

Launch agents with claude --agent <name> from your project directory. The agent appears in the dashboard; dispatch detects it via the JSONL session file your CLI writes automatically. The Sessions view and conversation replay work without any wrapper script.

Which providers does Dispatch support?

Dispatch supports four providers natively:

Provider	Session tracking	Agent spawning	MCP tools
Claude Code	Real-time (JSONL file watcher)	Yes (Run button + CLI)	Yes (auto-injected `.mcp.json`)
OpenAI Codex	Periodic poller	Yes (Run button + CLI)	Yes (auto-injected `.codex/config.toml`)
Google Gemini	Periodic poller	Yes (Run button + CLI)	Yes (manual config or SDK)
GitHub Copilot	Periodic poller	No (MCP-only, permanent)	Yes (manual VS Code settings)

All four providers appear in the agent sidebar, Sessions tab, and activity feed. The provider filter in the header lets you scope the dashboard to any combination of providers.

The .tasks/ protocol is tool-agnostic. Any agent from any provider that reads and writes the blackboard files participates in epic coordination automatically.

Can I use Dispatch with agents from other tools (Cursor, Windsurf, etc.)?

The .tasks/ protocol works with any tool that can read and write text files. If a non-supported agent writes correctly-formatted plan.md and execution-log.md files, Dispatch will display those epics and phases in the dashboard.

What you will not get for unsupported providers: session tracking, provider badges, the Sessions tab, or cost estimates. Those require a dedicated session scanner for each provider.

What happens if an agent crashes mid-phase?

The phase stays at IN_PROGRESS. Dispatch does not automatically reset stuck phases. This is intentional: the system has no way to distinguish “agent crashed” from “agent is running slowly on a large task.”

When the agent exits, its CLI stops writing to the session JSONL file. Dispatch detects liveness via that file’s mtime (5-minute staleness threshold). Once the file goes stale the dashboard moves the agent to idle. The phase status does not change automatically.

To recover: read the execution log to understand what was completed, then manually reset the phase status to TODO in plan.md and start a fresh agent. See Recovering abandoned work for the full step-by-step.

What happens if two agents claim the same phase simultaneously?

The claim operation is a file edit: the agent reads plan.md, finds the phase with status: TODO, and writes status: IN_PROGRESS. If two agents attempt this at the same time, the second edit will fail because the old_string it is trying to replace (status: TODO) no longer exists. The first agent already changed it.

The protocol handles this explicitly: if the edit call fails because the string is not found, the agent backs off and scans for other available phases. It does not retry the same phase.

This is a soft lock, not a hard one. It relies on agents following the protocol. An agent that ignores the edit-failure signal and writes IN_PROGRESS anyway will break coordination for that phase.

Can I run Dispatch without any agents running?

Yes. Dispatch starts up, scans registered projects, and displays whatever epics and phases are in .tasks/ regardless of whether any agents are currently running. All epic cards, phase railroads, and execution log entries are visible.

The Sessions tab shows no active sessions, and all agents in the sidebar show as idle. The dashboard is functional; it just has nothing live to report.

This is useful for reviewing past work, checking what phases are ready to be claimed, or exploring a project’s task history before starting a new session.

How do I find a past session?

Use the Command Palette: press Cmd+K (Mac) or Ctrl+K (Linux/Windows) and type part of the session’s opening prompt, the project name, or the git branch it ran on. Results appear after a short pause and are grouped by type: Sessions, Epics, Agents, Activity.

If you want to filter by status, provider, or date range, use the Search Panel (Cmd+Shift+F) and click the appropriate filter chips. For example, to find a specific Claude session from last Tuesday: open the Search Panel, type a keyword, click the Session chip, click the Claude chip, and set the date range.

See Search for the full guide.

Can I search inside conversation history?

Not by default. The search index covers session metadata (the opening prompt, project name, git branch, and agent name). The full message-by-message conversation content is not indexed.

To search inside conversation content, enable the search_stream_grep_enabled flag in ~/.dispatch/config.json:

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

After restarting the server, open the Search Panel (Cmd+Shift+F), expand the Advanced section, and check Conversation content. Dispatch will grep the session’s JSONL log on demand. Very large session files are skipped automatically.

Are saved searches synced across devices?

No. Saved queries in the Search Panel are stored in your browser’s local storage. They persist across page reloads on the same device and browser but do not sync to other devices or browsers. The “Saved (device-only)” label in the panel reflects this.

Recent searches (shown in both the Command Palette and Search Panel when the input is empty) are also device-local.

Do I need to restart Dispatch after registering a new project?

No. When you register a project with node cli.js add /path/to/project, the server picks it up immediately. The file watcher starts watching the new project’s .tasks/ directory without a restart.

My activity feed is empty. Where are the entries?

The activity feed is driven by ActivityEvent objects emitted server-side. Phase completion events are triggered when Dispatch parses a correctly-formatted entry in execution-log.md. Each entry must follow this exact format:

## [<ISO timestamp>] Phase <id>: <title> — @<persona>

The — character must be an em dash (U+2014), not a regular hyphen. If agents are writing a hyphen, the entry will not be parsed, no phase_completed event will be emitted, and nothing will appear in the feed. See Troubleshooting for the verification steps.

The feed also shows session_started, session_ended, and agent_spawned events. Claude Code session events are generated from JSONL session logs. Non-Claude provider events are generated by the periodic multi-session poller. If session events are missing for Claude, check that the server can read ~/.claude/projects/. For other providers, wait for the poller to discover the session (check the Dispatch server logs for the polling interval).

The dashboard shows “Connecting…” and never loads

The Dispatch server is not running. Start it:

# Development mode
npm run dev

# Production mode
npm run build && npm start

If the server starts but the dashboard still shows “Connecting…”, check that you are opening the correct URL. Both the development and production URLs are printed to the terminal when the server starts.

Can I run Dispatch in CI or Docker?

Dispatch is designed for local use. It watches your local filesystem and reads Claude Code’s local session files. These do not exist in a standard CI environment.

Running Dispatch in Docker is possible but requires mounting the project directories and the Claude Code session directory (~/.claude/) into the container. There is no official Docker setup at this time.

Where is the config stored?

The ~/.dispatch/ directory contains two files:

config.json: user configuration, including registered project paths, the onboarding flag, and paths to any imported custom agent files.
agent-profiles.json: agent analytics cache with aggregated token counts, tool usage, task completion rates, and relationship data built from your session history. Dispatch writes this automatically while the server runs.

If you delete config.json, Dispatch recreates it with an empty default on the next start. You will need to re-register your projects. If you delete agent-profiles.json, Dispatch rebuilds it from your session files on the next run. No data is permanently lost by deleting either file.

For the full configuration format, see CLI Reference. iles.json`, Dispatch rebuilds it from your session files on the next run. No data is permanently lost by deleting either file.

For the full configuration format, see CLI Reference.