robolab — connect a Claude Code agent to your board

The published npm package that feeds one Claude Code agent from a RoboLab board (the single-agent loop in ../docs/single-agent-spec.md). One binary, three subcommands:

| command | who runs it | what it does | |---|---|---| | npx robolab connect <token> | you, once per project | writes .mcp.json + drafts the board note from the repo | | npx robolab mcp | Claude Code (via .mcp.json) | the MCP bridge — each tool is a thin call to POST <BASE>/api/agent | | npx robolab run | you (optional) | hands-off auto-agent: watches the board, runs Claude on new work |

Quick start

1. Open your board at https://robolove.vercel.app/robolab → 🔌 Connect and copy the one-liner (or grab the token from the …/l/<token> page).

2. In the project you want worked:

   npx robolab connect <token>

   This validates the token, writes a .mcp.json pointing Claude Code at npx -y robolab mcp, gitignores it (it holds your token), and drafts the board note from your CLAUDE.md / AGENTS.md / README.md / package.json. No clone, no install.

3. Start the agent — claude, then say “Work my RoboLab board.” On connect it calls robolab_get_board (the protocol + your board note) and loops.

Local dev: add --base http://localhost:3000 to connect (both the deployed app and a local next dev talk to the same Neon board DB).

Environment

| var | required | default | used by | |---|---|---|---| | ROBOLAB_TOKEN | yes (or cached by connect) | — | all | | ROBOLAB_BASE_URL | no | https://robolove.vercel.app | all | | ROBOLAB_PROJECT_DIR | no | cwd (or --cwd <dir>) | run | | ROBOLAB_MODEL | no | account default | run | | ROBOLAB_SESSION_RESET_HOURS | no | 12 | run |

connect caches {token, base} per project in ~/.robolab/config.json, so robolab run works with no args from that project.

The stdio transport owns stdout — the bridge logs only to stderr.

Hands-off auto-agent — npx robolab run

Normally you start the agent. run makes the board hands-off: post a task and walk away, and an agent wakes on its own to work it — without spending tokens while idle. It long-polls the board's wait_for_work (a single held-open fetch, so idle costs $0); the moment work lands it boots a headless claude to drain the queue (using your logged-in subscription, no API key), then waits again. It pulls (no inbound webhook; works behind NAT), pins one session and --resumes it for continuity (auto-reset every ROBOLAB_SESSION_RESET_HOURS), and is single-flight.

# in your project, after `robolab connect` (prereq: `claude` logged in)
npx robolab run
# or target another dir:  npx robolab run --cwd /path/to/project
# test detection without spawning:  ROBOLAB_DRY_RUN=1 npx robolab run

⚠ One agent per working dir. Don't run a second interactive Claude in the same folder while the daemon runs — they clobber each other.

Tools (the bridge exposes ~20 robolab_*)

robolab_get_board, robolab_set_board_note, robolab_read_board_messages, robolab_post_board_message, robolab_list_open_tasks, robolab_pull_next, robolab_wait_for_work, robolab_get_task, robolab_set_verifying, robolab_block, robolab_propose_plan, robolab_post_message, robolab_read_replies, robolab_update_checklist, robolab_propose_checklist, robolab_mark_done, robolab_suggest_task, robolab_skip_task, robolab_report_bug, robolab_signal_idle.

Dev note (this repo)

The committed root ../.mcp.json and the local claude mcp add robolab still point at the in-repo mcp/server.mjs for development. End users get the published-package flow above (npx -y robolab mcp).