skills/src

Worker CLI

Multi-agent worker coordination CLI written in Nim.

Prerequisites

# Install Nim (>= 2.0.0)
# On NixOS: nix-shell -p nim

# Install dependencies
nimble install tiny_sqlite cligen

Static SQLite (Optional)

For a single static binary, download the SQLite amalgamation:

curl -LO https://sqlite.org/2024/sqlite-amalgamation-3450000.zip
unzip sqlite-amalgamation-3450000.zip
cp sqlite-amalgamation-3450000/sqlite3.c libs/

Build

# Development build
nim c src/worker.nim

# Release build (optimized)
nim c -d:release src/worker.nim

# The binary will be at src/worker

Usage

# Orchestrator commands (human)
worker spawn <task-id>              # Create workspace
worker status [--watch]             # Dashboard
worker approve <task-id>            # Approve work
worker request-changes <task-id>    # Request changes
worker merge <task-id>              # Merge to integration
worker cancel <task-id>             # Abort worker

# Agent commands (from worktree)
worker start                        # Begin work
worker done [--skip-rebase]         # Complete work
worker fail <reason>                # Signal failure
worker heartbeat                    # Manual heartbeat
worker show <task-id>               # Detailed view

Project Structure

src/
├── worker.nim           # CLI entry point (cligen)
├── worker.nimble        # Package definition
├── config.nims          # Build configuration
├── libs/
│   └── sqlite3.c        # SQLite amalgamation (optional)
└── worker/
    ├── types.nim        # Shared types and constants
    ├── db.nim           # SQLite operations
    ├── state.nim        # State machine
    ├── heartbeat.nim    # Background thread
    ├── git.nim          # Git/worktree operations
    └── context.nim      # Worker context handling

Design Docs

See docs/design/:

• mvp-scope.md - MVP scope and implementation order
• message-passing-layer.md - SQLite message bus
• worker-cli-primitives.md - CLI commands
• worker-state-machine.md - State transitions