# 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)

```js
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

```bash
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
```