RoadRaven

# RoadRaven

**The plan that watches itself.** A local desktop tree of your project's plan
where every node can be wired to something real (a Claude Code task, a CI job,
a script) and flips status by itself as the work happens.

[![Latest release](https://img.shields.io/github/v/release/Shuffzord/RoadRaven?label=release&color=blue)](https://github.com/Shuffzord/RoadRaven/releases/latest)
[![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](#license)
[![Platform: Windows | Linux](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-blue.svg)](#install)
[![MCP server on npm](https://img.shields.io/npm/v/%40roadraven%2Fmcp?label=%40roadraven%2Fmcp)](https://www.npmjs.com/package/@roadraven/mcp)

<img width="1920" height="1080" alt="RoadRaven: a project plan as a tree, with live status on every node" src="https://github.com/user-attachments/assets/7a5ee9e9-33b1-4bab-9dad-f680a36fdc21" />

You 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 tree, updated live over a
local WebSocket by whatever is actually doing the work. No cloud, no accounts,
no sprints, no story points. Just a file you own.

The headline use case: give Claude Code (or any MCP host) the roadmap, and
watch it plan, work, and tick nodes green while you supervise.

> **Alpha (v0.8.9).** Core editing and the live Event API work today. The data
> format, APIs, and packaging may still change before v1.0. Bug reports and
> feature requests are very welcome via [Issues](https://github.com/Shuffzord/RoadRaven/issues).

## 60-second start

**1. Install** (Windows and Linux today; macOS is [next](#status)).

Windows x64, PowerShell. Downloads the latest release, verifies it against the
release's `SHA256SUMS`, runs the installer:

```powershell
irm https://raw.githubusercontent.com/Shuffzord/RoadRaven/master/install.ps1 | iex
```

Linux x86_64:

```bash
curl -fsSL https://raw.githubusercontent.com/Shuffzord/RoadRaven/master/install.sh | sh
```

Windows SmartScreen will say "Windows protected your PC" because the alpha
ships unsigned. Click **More info**, then **Run anyway**. Manual downloads,
version pinning, and checksum steps: [Install details](#install).

**2. Connect Claude Code.** Launch RoadRaven. The first-run **Setup Wizard**
detects Claude Code and OpenCode and registers the bundled MCP server with one
click. No commands, works offline. Restart your MCP host and the tools are live.

**3. Try it.** Open a sample from the Welcome screen, then tell Claude Code:

```
Read the open RoadRaven roadmap, pick the first todo node, do the work, and set its status as you go.
```

Nodes change colour on the canvas as the agent works. That is the whole idea.

## Demo

https://github.com/user-attachments/assets/404a1f7d-094d-42a4-b930-6e8f31a17b6a

![RoadRaven's own 0.8 release line: six versions shipped, the seventh in flight, each phase attributed to the agent that did it](screenshots/promo/readme-hero-rr-timeline-amber.png)

![The 0.8.6 subtree with the node panel open: status, type, notes and the agent badge on every card](screenshots/rr-detail-paper.png)

![Live event log: every MCP tool call streams into a filterable feed over WebSocket](screenshots/events.png)

## Why RoadRaven

- **Plan-as-file.** The roadmap is plain JSON in your repo. Diffable, reviewable, yours. No database, no proprietary format.
- **Live status from anything.** Any process that can open a WebSocket updates a node. A GitHub Action finishes, the node turns green. Claude Code completes a task, the node updates.
- **Built for agent supervision.** The MCP server exposes 21 tools so an agent can create, edit, move, delete nodes and push status as it works. You watch; it keeps the plan current.
- **Local-first.** Binds to `127.0.0.1`, works air-gapped. Nothing leaves your machine.
- **Keyboard-first.** Navigate and edit the whole tree without the mouse.
- **Zero-opinion schema.** You define the statuses, types, and hierarchy. The app stays dumb; your tools do the talking.

## Connect an MCP host

Three ways, easiest first. Every path needs the desktop app running: tools talk
to it over the local Event API and return `app_not_running` otherwise.

**Setup Wizard (recommended).** Described in [60-second start](#60-second-start).
Re-open it any time from the ⚙ button in the top bar. It writes to
`~/.claude.json` (Claude Code) and `~/.config/opencode/opencode.json`
(OpenCode) without touching other servers you have configured. If the Claude
Code plugin below is already installed, the wizard defers to it.

**Claude Code plugin.** Requires **Node.js >= 24**. From inside Claude Code:

```
/plugin marketplace add Shuffzord/RoadRaven
/plugin install roadraven@roadraven
```

Claude Code doesn't refresh third-party marketplaces on its own: turn on
auto-update for `roadraven` in `/plugin` → Marketplaces, or run
`/plugin marketplace update roadraven` before `/plugin update
roadraven@roadraven` when the app tells you the plugin is out of date.

**Any other MCP host.** Requires **Node.js >= 24**. Pin the version that
matches your installed app (the app warns when the versions differ):

```bash
claude mcp add -s user roadraven -- npx -y @roadraven/mcp@0.8.9
```

**Tell Claude to use it.** Tools alone give Claude no reason to plan in the
roadmap. This adds a short RoadRaven section to a `CLAUDE.md`, asking first
whether to put it in the current project or in `~/.claude/CLAUDE.md` for every
project. Safe to re-run; it updates its own block and touches nothing else:

```bash
npx -y @roadraven/mcp@0.8.9 init
```

Cursor, Codex, Copilot, Gemini, OpenCode, version-mismatch handling, and a
build-from-source path: [MCP install guide](docs/mcp-install.md).

Writing your own producer (a CI job, a script, a bot)? The Event API contract
is in the [plugin authoring guide](docs/plugin-authoring.md).
`@roadraven/core` (Zod schemas and types) is not on npm yet; build it from source.

## Skills for Claude Code

The Claude Code plugin install also brings two skills (the Setup Wizard and
`npx` paths give the tools only). `roadraven:orchestrate` plans a piece of
work as a roadmap tree and runs it phase by phase with sub-agents;
`roadraven:work-node` is how each task claims a node, checkpoints into it and
reports. Details in the [plugin README](plugins/claude-code/README.md). Try:

```
Plan the CSV export feature as a roadmap in RoadRaven and run it phase by phase.
```

## Claude Code HUD

A **mod** for Claude Code: a brand-new kind of extension that changes Claude Code's own interface, here a live RoadRaven pane inside your terminal session.

- Live agents per node, with model, effort and current action
- UAT checks you pass or fail in a batch, which wakes the orchestrator
- Backlog **Run** / **Next** buttons
- Follows the app theme

![UAT section with Pass and Fail buttons](screenshots/hud-uat.png)

Ships with the plugin: `/plugin install roadraven@roadraven`. [Details →](plugins/roadraven-hud/README.md)

## Install

Download from [GitHub Releases](https://github.com/Shuffzord/RoadRaven/releases/latest).
Every release since v0.8.0 ships a `SHA256SUMS` file.

**Windows x64.** The one-liner above, or by hand:

1. Download `win-x64-RoadRaven-Setup.zip` and `SHA256SUMS`. Check the download (prints `True` when it matches):
   `(Get-FileHash win-x64-RoadRaven-Setup.zip).Hash -eq (Select-String -SimpleMatch '  win-x64-RoadRaven-Setup.zip' SHA256SUMS).Line.Split(' ')[0]`
2. Extract the zip and run `RoadRaven-Setup.exe`.
3. SmartScreen: **More info**, then **Run anyway**. RoadRaven is unsigned in the alpha.

RoadRaven renders through the system WebView2 runtime on Windows, so the
download carries no bundled browser engine. Pin a version with
`$env:ROADRAVEN_VERSION = 'v0.8.9'` before the one-liner.

**Linux x86_64.** The one-liner above, or by hand:

```bash
sha256sum -c SHA256SUMS --ignore-missing
tar -xzf linux-x64-RoadRaven-Setup.tar.gz
chmod +x ./installer
./installer
```

The installer puts the app under `~/.local/share/` and creates a desktop
shortcut. Chromium (CEF) ships bundled, so no system browser dependency. Pin
a version with `ROADRAVEN_VERSION=v0.8.9` in front of `sh`.

Once installed, RoadRaven checks GitHub Releases for updates and asks before
downloading one.

## Status

| Shipped as of v0.8.9 | Next |
|---|---|
| Tree canvas, keyboard editor, side-panel markdown notes and metadata | macOS installer |
| Atomic autosave, `$ref` split files, File menu, Outline navigator | Code signing |
| Event API over WebSocket, agent-safe writes (optimistic locking, batch updates) | Drag-and-drop reparenting |
| MCP server on npm, Setup Wizard, Claude Code plugin with orchestrate and work-node skills and the HUD mod | `@roadraven/core` and `@roadraven/react` on npm |
| 8 themes with WCAG contrast gates, user theme files, in-app theme editor | |
| In-app updates: checks on launch, asks before downloading, restart to install | |
| Windows and Linux installers with verified checksums | `.deb` packaging |
| Undo / redo, status ribbons, per-file layout knobs, draggable custom layout, persistent collapse | |

Full feature list and keyboard reference: [docs/features.md](docs/features.md).
Release history: [CHANGELOG.md](CHANGELOG.md).

## Documentation

- [Features and keyboard reference](docs/features.md)
- [MCP install guide](docs/mcp-install.md)
- [Plugin authoring guide](docs/plugin-authoring.md) (write your own Event Producer)
- [Architecture overview](docs/architecture-overview.md)
- [Development guide](docs/development-guide.md)
- [Design system](docs/design-system.md)
- [Logging](docs/logging.md)

## Contributing

RoadRaven is built on [Electrobun](https://blackboard.sh/electrobun/) (not
Electron) with Bun as the runtime. Local setup, test commands, code style,
and project conventions are in [CONTRIBUTING.md](./CONTRIBUTING.md).

```bash
bun i