roboluv — connect Claude Code to your board

The published npm package that feeds one interactive Claude Code session from a roboluv board. One binary, three subcommands:

| command | who runs it | what it does | |---|---|---| | npx roboluv connect <token> | you, once per project | writes .mcp.json + drafts the board note from the repo | | npx roboluv run | you (hands-off) | watches the board and auto-runs Claude on new work, one task at a time | | npx roboluv mcp | Claude Code (via .mcp.json) | the MCP bridge — each tool is a thin call to POST <BASE>/api/agent | | npx roboluv watch | you (optional) | mirrors your terminal session into the board's 🖥 Terminal tab |

Quick start

1. Open your board at https://roboluv.baraklikeyou.workers.dev/roboluv → 🔌 Connect and copy the one-liner (or grab the token).

2. In the project you want worked:

   npx roboluv connect <token>

   This validates the token, writes a .mcp.json pointing Claude Code at npx -y roboluv 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. Put it to work — two ways:

   • Hands-off: npx roboluv run (or roboluv run --local from this checkout). It long-polls the board and auto-runs Claude on new work, one task at a time. $0 while idle. Ctrl-C to stop.
   • Drive it yourself: claude, then say “Work my board.” On connect it calls roboluv_get_board (the protocol + your board note + tech-stack note) and works tasks one at a time, reporting back to the board.

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 | |---|---|---|---| | ROBOLUV_TOKEN | yes (or cached by connect) | — | all | | ROBOLUV_BASE_URL | no | https://roboluv.baraklikeyou.workers.dev | all | | ROBOLUV_PROJECT_DIR | no | cwd (or --cwd <dir>) | watch |

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

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

Terminal mirror — npx roboluv watch

Optional. Run it in a second terminal while you work an interactive claude session. It tails the session's JSONL transcript and forwards each assistant message / tool call into the board's 🖥 Terminal tab — a read-only mirror of what Claude is doing in the terminal. It spawns nothing and changes no code; it only reads and forwards. Stop it any time with Ctrl-C.

# in your project, after `roboluv connect`
npx roboluv watch
# or target another dir:  npx roboluv watch --cwd /path/to/project

Tools (the bridge exposes ~20 roboluv_*)

roboluv_get_board, roboluv_set_board_note, roboluv_read_board_messages, roboluv_post_board_message, roboluv_list_open_tasks, roboluv_pull_next, roboluv_wait_for_work, roboluv_get_task, roboluv_set_verifying, roboluv_block, roboluv_propose_plan, roboluv_post_message, roboluv_read_replies, roboluv_update_checklist, roboluv_propose_checklist, roboluv_mark_done, roboluv_suggest_task, roboluv_skip_task, roboluv_report_bug, roboluv_signal_idle, roboluv_set_handoff.

Dev note (this repo)

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