Installation

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

Prerequisites

• Node.js >= 20 (.node-version pins 20.19.0)
• npm >= 9
• A terminal and a browser
• At least one supported CLI agent installed (any combination):
  • Claude Code (claude CLI)
  • OpenAI Codex (codex CLI)
  • Google Gemini CLI (gemini CLI)
  • GitHub Copilot (VS Code extension with MCP support; no CLI spawn)

None of the providers are required. Dispatch works with zero agents running (you can browse existing .tasks/ data), but session tracking requires at least one provider installed.

Windows users

Dispatch is tested on macOS and Linux. On Windows, use WSL 2 with a Linux distribution. Native Windows (PowerShell / cmd) is not supported.

1. Clone and install

git clone https://github.com/thepixelabs/dispatch.git
cd dispatch
npm install

2. Start in development mode

npm run dev

This starts the backend server and a Vite dev server with hot reload. Open http://localhost:5173 in your browser.

3. Production build

npm run build && npm start

The production build serves everything from the backend server. Open http://localhost:4242 in your browser.

4. Register a project

Dispatch watches the .tasks/ directory inside each registered project. Register your first project:

node cli.js add /path/to/your/project --name "My Project"

The path must exist on disk. Dispatch validates it and saves the registration to ~/.dispatch/config.json. You can register multiple projects, and Dispatch watches them all simultaneously.

Check what is registered:

node cli.js list

Remove a project:

node cli.js remove "My Project"

For the full ~/.dispatch/config.json format and how to edit it directly, see CLI Reference: Configuration file.

Running Dispatch persistently

By default the server runs in your terminal and stops when you close it. For day-to-day use, you want it to start automatically and stay running in the background.

Option 1: pm2 (cross-platform, recommended)

pm2 is a Node.js process manager that restarts your process on crash and survives terminal sessions.

npm install -g pm2
cd /path/to/dispatch
npm run build          # build once before starting in production mode
pm2 start "npm start" --name dispatch
pm2 save               # persist across reboots
pm2 startup            # follow the printed instructions to install the startup hook

Useful commands:

pm2 status             # show running processes
pm2 logs dispatch      # stream logs
pm2 restart dispatch   # restart after config changes
pm2 stop dispatch      # stop without removing
pm2 delete dispatch    # remove from pm2 entirely

Option 2: launchd (macOS)

launchd is the native macOS service manager. Create a plist at ~/Library/LaunchAgents/com.dispatch.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.dispatch.server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/npm</string>
    <string>start</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/path/to/dispatch</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/dispatch.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/dispatch.err</string>
</dict>
</plist>

Replace /path/to/dispatch with your actual clone path and /usr/local/bin/npm with the output of which npm.

Load and start it:

npm run build          # build once
launchctl load ~/Library/LaunchAgents/com.dispatch.server.plist
launchctl start com.dispatch.server

To stop or disable:

launchctl stop com.dispatch.server
launchctl unload ~/Library/LaunchAgents/com.dispatch.server.plist

Option 3: systemd user service (Linux)

Create ~/.config/systemd/user/dispatch.service:

[Unit]
Description=Dispatch server
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/dispatch
ExecStartPre=/usr/bin/env npm run build
ExecStart=/usr/bin/env npm start
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable dispatch
systemctl --user start dispatch

Check status and logs:

systemctl --user status dispatch
journalctl --user -u dispatch -f

To make user services start at boot without login (useful on a headless server):

loginctl enable-linger "$USER"

---

Next step

Once the server is running and a project is registered, follow the Quick Start to start agents and see the dashboard in action.