xswarm

packages/app — Daemon, Foreman, Workers, Channel

On-machine component of xSwarm. Runs under CC OAuth subscription — no per-token API cost.

Architecture

npx xswarm
  └─► daemon (PM2-managed Node.js)
        ├─► foreman (CC session in tmux + xswarm-channel MCP)
        │     └─► tools: report_status, request_worker, relay_to_user,
        │               get_projects, get_project_status, check_worker_status
        └─► workers (headless claude -p sessions in tmux)
              └─► execute TDD loops in project git worktrees

Key Files

src/daemon/

File	Purpose
foreman.js	Foreman CC session lifecycle — start, monitor, restart (max 10). Writes MCP config, injects system instructions.
worker.js	Spawns headless claude -p workers in tmux windows. Tracks worker state per project.
terminal-relay.js	Reads tmux pane output via capture-pane, streams to API as terminal:output WebSocket messages.
devserver-relay.js	HTTP dev server proxy. Receives http_req from dashboard, forwards to local port, sends http_res back.
tmux-manager.js	tmux session and window management. Session prefix: xswarm.
claude-executor.js	Launches CC processes with correct flags, MCP config, and system prompt.
auth.js	Loads ~/.xswarm config: auth token, machine ID.
websocket.js	Persistent WebSocket connection to API relay. Auto-reconnects on drop.
api-client.js	REST calls to api.xswarm.ai for project registration and status.
project-db.js	Local SQLite for project registry and worker tracking.
daemon-entry.js	PM2 entry point. Starts all subsystems in order.
setup.js	First-run setup: GitHub OAuth, machine registration, config file.

src/channel/

File	Purpose
xswarm-channel.js	MCP stdio server. Exposes 6 tools to foreman. Bridges CC ↔ API via WebSocket.
foreman-instructions.md	System prompt for the foreman CC session. BA persona. Audio-optimized response rules.

MCP Tools (xswarm-channel)

report_status(project_id, summary, status)
// status: 'idle' | 'working' | 'blocked' | 'complete'
// Pushes to dashboard via API relay

request_worker(project_id, task, context)
// Spawns headless claude -p in a tmux window, returns worker_id

relay_to_user(message)
// Sends chat:response through API relay to all connected dashboards

get_projects()
// Returns list of projects registered on this machine

get_project_status(project_id)
// Returns cached status from API relay

check_worker_status(worker_id)
// Returns: 'running' | 'complete' | 'error' | 'not_found'

Foreman Persona Rules

From foreman-instructions.md:

• Responses must be 1-3 sentences maximum (audio-optimized, user may be listening)
• Act as Business Analyst: clarify requirements before spawning workers
• Use report_status on every meaningful state change
• Use relay_to_user only for information the user needs to act on
• Spawn workers via request_worker with full context so they can work without callbacks

Workers

Each worker is a headless claude -p session in a tmux window:

• Receives task spec and project context in initial prompt
• Reads .xswarm/ state files in the project worktree
• Executes TDD loop: tests RED → implement → tests GREEN → refactor → commit
• Foreman polls via check_worker_status, relays progress via report_status
• Worker window visible in dashboard terminal view

npm Scripts

npm run dev        # Start daemon in development mode (nodemon)
npm run build      # Build CLI for publishing
npm run test       # Run vitest test suite
npm run lint       # ESLint check