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:

1. Receives task spec and project context in initial prompt
2. Reads .xswarm/ state files in the project worktree
3. Executes TDD loop: tests RED → implement → tests GREEN → refactor → commit
4. Foreman polls via check_worker_status, relays progress via report_status
5. 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