RoadRaven

The plan that watches itself

You write a plan in a doc. The work happens in terminals, CI and AI agents. Within a day the doc is fiction.

RoadRaven keeps the plan and the work in one place: a plain roadmap.json in your repo, rendered as a keyboard-driven tree and updated live over a local WebSocket by whatever is doing the work. Hand the roadmap to Claude Code and watch it plan, build and turn nodes green while you supervise.

Orchestration skills: from plan to verified phases

Installing the Claude Code plugin adds two skills that turn the roadmap into an execution plan:

• roadraven:orchestrate breaks work into a roadmap tree, then runs it phase by phase with sub-agents. It checks each phase with your project's own test and lint commands before moving on.
• roadraven:work-node is the contract for a single task: claim the node, checkpoint progress into its notes, stay inside the agreed files, report back.
• Acceptance built in. The orchestrator creates uat nodes with test steps and marks them ready only after the work they check is verified. Nodes you flag as priority go first.
• Works in any language, and falls back to a markdown worklog when the desktop app isn't running.

MCP-native, host-agnostic

• 21 MCP tools let agents create, edit, move and delete nodes and push status as they work.
• Agent-safe writes. Optimistic locking and atomic batch updates let agents and you write to the same roadmap safely. Your undo never rewinds an agent's work, and an agent's note never overwrites what you're typing.
• One-click setup. The first-run wizard registers the server with Claude Code and OpenCode, fully offline. Cursor, Codex, Copilot and Gemini are covered in the install guide. @roadraven/mcp is published to npm and the MCP Registry.
• npx @roadraven/mcp init adds a RoadRaven section to your CLAUDE.md, so Claude plans in the roadmap instead of just having the tools.
• Live event log. Every tool call streams into a filterable feed.

Mission control inside Claude Code: the RoadRaven HUD

Built on Claude Code's new Mods system, the HUD draws a live RoadRaven pane right inside your session. It opens by itself when a roadmap is open, or with /roadraven.

• Active work: every in-progress node with the agent on it, its model and effort, elapsed time, current action, and tokens used once it finishes.
• UAT: pass or fail a batch of acceptance checks, with a note per failure. One Send writes every status atomically and wakes the orchestrator with a summary.
• Backlog: Run starts a one-off agent for a node. Next moves it to the front of the queue.
• Toasts when checks are ready, a status-line entry, and the app's themes.

Plan-as-file, local-first

• Plain JSON in your repo: diffable, reviewable, splittable with $ref files. No database, no proprietary format.
• Binds to 127.0.0.1 and works air-gapped. Nothing leaves your machine.
• Live status from anything that can open a WebSocket, such as a GitHub Action, a script or a bot.
• Zero-opinion schema: you define the statuses, types and hierarchy.
• Keyboard-first editor, undo/redo, outline navigator, and 8 WCAG-checked themes plus your own.

Get started in 60 seconds

1. Install with a checksum-verified one-liner on Windows or Linux. macOS is next.
2. In Claude Code, run /plugin marketplace add Shuffzord/RoadRaven, then /plugin install roadraven@roadraven. That installs the MCP server, the skills and the HUD in one go. You need Node.js 24+, and the HUD needs Claude Code v2.1.287+.
3. Tell Claude: "Read the open RoadRaven roadmap, pick the first todo node, do the work, and set its status as you go."

Alpha (v0.8.9) and shipping fast. Source-available under FSL-1.1-MIT: free for any use, including at work, and every release becomes MIT two years after it ships.