{"slug": "show-hn-roadraven-a-project-plan-your-coding-agents-keep-up-to-date", "title": "Show HN: RoadRaven – a project plan your coding agents keep up to date", "summary": "Shuffzord released RoadRaven v0.8.9, an alpha local-first desktop tool that stores a project plan as a plain roadmap.json in a repository and updates node status live over a local WebSocket as Claude Code or other MCP hosts complete work. The bundled MCP server exposes 21 tools so agents can create, edit, move and delete nodes and push status, with installers available for Windows x64 and Linux x86_64 and macOS planned next. The alpha ships unsigned, requires Node.js >= 24 for the Claude Code plugin, and its data format, APIs and packaging may change before v1.0.", "body_md": "**The plan that watches itself.** A local desktop tree of your project's plan\nwhere every node can be wired to something real (a Claude Code task, a CI job,\na script) and flips status by itself as the work happens.\n\nYou plan in a doc. The work happens in terminals, CI, and AI agents. Within a\nday the doc is fiction. RoadRaven keeps the plan and the work in one place: a\nplain `roadmap.json` in your repo, rendered as a tree, updated live over a\nlocal WebSocket by whatever is actually doing the work. No cloud, no accounts,\nno sprints, no story points. Just a file you own.\n\nThe headline use case: give Claude Code (or any MCP host) the roadmap, and watch it plan, work, and tick nodes green while you supervise.\n\n**Alpha (v0.8.9).** Core editing and the live Event API work today. The data\nformat, APIs, and packaging may still change before v1.0. Bug reports and\nfeature requests are very welcome via [Issues](https://github.com/Shuffzord/RoadRaven/issues).\n\n**1. Install** (Windows and Linux today; macOS is [next](#status)).\n\nWindows x64, PowerShell. Downloads the latest release, verifies it against the\nrelease's `SHA256SUMS`, runs the installer:\n\n```\nirm https://raw.githubusercontent.com/Shuffzord/RoadRaven/master/install.ps1 | iex\n```\n\nLinux x86_64:\n\n```\ncurl -fsSL https://raw.githubusercontent.com/Shuffzord/RoadRaven/master/install.sh | sh\n```\n\nWindows SmartScreen will say \"Windows protected your PC\" because the alpha\nships unsigned. Click **More info**, then **Run anyway**. Manual downloads,\nversion pinning, and checksum steps: [Install details](#install).\n\n**2. Connect Claude Code.** Launch RoadRaven. The first-run **Setup Wizard**\ndetects Claude Code and OpenCode and registers the bundled MCP server with one\nclick. No commands, works offline. Restart your MCP host and the tools are live.\n\n**3. Try it.** Open a sample from the Welcome screen, then tell Claude Code:\n\n```\nRead the open RoadRaven roadmap, pick the first todo node, do the work, and set its status as you go.\n```\n\nNodes change colour on the canvas as the agent works. That is the whole idea.\n\n## roadraven-showreel.mp4\n\n- **Plan-as-file.** The roadmap is plain JSON in your repo. Diffable, reviewable, yours. No database, no proprietary format.\n- **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.\n- **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.\n- **Local-first.** Binds to`127.0.0.1` , works air-gapped. Nothing leaves your machine.\n- **Keyboard-first.** Navigate and edit the whole tree without the mouse.\n- **Zero-opinion schema.** You define the statuses, types, and hierarchy. The app stays dumb; your tools do the talking.\n\nThree ways, easiest first. Every path needs the desktop app running: tools talk\nto it over the local Event API and return `app_not_running` otherwise.\n\n**Setup Wizard (recommended).** Described in [60-second start](#60-second-start).\nRe-open it any time from the ⚙ button in the top bar. It writes to\n`~/.claude.json` (Claude Code) and `~/.config/opencode/opencode.json`\n(OpenCode) without touching other servers you have configured. If the Claude\nCode plugin below is already installed, the wizard defers to it.\n\n**Claude Code plugin.** Requires **Node.js >= 24**. From inside Claude Code:\n\n```\n/plugin marketplace add Shuffzord/RoadRaven\n/plugin install roadraven@roadraven\n```\n\nClaude Code doesn't refresh third-party marketplaces on its own: turn on\nauto-update for `roadraven` in `/plugin` → Marketplaces, or run\n`/plugin marketplace update roadraven` before `/plugin update roadraven@roadraven` when the app tells you the plugin is out of date.\n\n**Any other MCP host.** Requires **Node.js >= 24**. Pin the version that\nmatches your installed app (the app warns when the versions differ):\n\n```\nclaude mcp add -s user roadraven -- npx -y @roadraven/mcp@0.8.9\n```\n\n**Tell Claude to use it.** Tools alone give Claude no reason to plan in the\nroadmap. This adds a short RoadRaven section to a `CLAUDE.md`, asking first\nwhether to put it in the current project or in `~/.claude/CLAUDE.md` for every\nproject. Safe to re-run; it updates its own block and touches nothing else:\n\n```\nnpx -y @roadraven/mcp@0.8.9 init\n```\n\nCursor, Codex, Copilot, Gemini, OpenCode, version-mismatch handling, and a\nbuild-from-source path: [MCP install guide](https://github.com/Shuffzord/RoadRaven/blob/master/docs/mcp-install.md).\n\nWriting your own producer (a CI job, a script, a bot)? The Event API contract\nis in the [plugin authoring guide](https://github.com/Shuffzord/RoadRaven/blob/master/docs/plugin-authoring.md).\n`@roadraven/core` (Zod schemas and types) is not on npm yet; build it from source.\n\nThe Claude Code plugin install also brings two skills (the Setup Wizard and\n`npx` paths give the tools only). `roadraven:orchestrate` plans a piece of\nwork as a roadmap tree and runs it phase by phase with sub-agents;\n`roadraven:work-node` is how each task claims a node, checkpoints into it and\nreports. Details in the [plugin README](https://github.com/Shuffzord/RoadRaven/blob/master/plugins/claude-code/README.md). Try:\n\n```\nPlan the CSV export feature as a roadmap in RoadRaven and run it phase by phase.\n```\n\nA **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.\n\n- Live agents per node, with model, effort and current action\n- UAT checks you pass or fail in a batch, which wakes the orchestrator\n- Backlog **Run** /**Next** buttons\n- Follows the app theme\n\nShips with the plugin: `/plugin install roadraven@roadraven`. [Details →](https://github.com/Shuffzord/RoadRaven/blob/master/plugins/roadraven-hud/README.md)\n\nDownload from [GitHub Releases](https://github.com/Shuffzord/RoadRaven/releases/latest).\nEvery release since v0.8.0 ships a `SHA256SUMS` file.\n\n**Windows x64.** The one-liner above, or by hand:\n\n1. 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]`\n2. Extract the zip and run `RoadRaven-Setup.exe` .\n3. SmartScreen: **More info** , then**Run anyway** . RoadRaven is unsigned in the alpha.\n\nRoadRaven renders through the system WebView2 runtime on Windows, so the\ndownload carries no bundled browser engine. Pin a version with\n`$env:ROADRAVEN_VERSION = 'v0.8.9'` before the one-liner.\n\n**Linux x86_64.** The one-liner above, or by hand:\n\n```\nsha256sum -c SHA256SUMS --ignore-missing\ntar -xzf linux-x64-RoadRaven-Setup.tar.gz\nchmod +x ./installer\n./installer\n```\n\nThe installer puts the app under `~/.local/share/` and creates a desktop\nshortcut. Chromium (CEF) ships bundled, so no system browser dependency. Pin\na version with `ROADRAVEN_VERSION=v0.8.9` in front of `sh`.\n\nOnce installed, RoadRaven checks GitHub Releases for updates and asks before downloading one.\n\n| Shipped as of v0.8.9 | Next | \n|---|---|\n| Tree canvas, keyboard editor, side-panel markdown notes and metadata | macOS installer | \n| Atomic autosave, `$ref` split files, File menu, Outline navigator | Code signing | \n| Event API over WebSocket, agent-safe writes (optimistic locking, batch updates) | Drag-and-drop reparenting | \n| 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 | \n| 8 themes with WCAG contrast gates, user theme files, in-app theme editor |  | \n| In-app updates: checks on launch, asks before downloading, restart to install |  | \n| Windows and Linux installers with verified checksums | `.deb` packaging | \n| Undo / redo, status ribbons, per-file layout knobs, draggable custom layout, persistent collapse |  | \n\nFull feature list and keyboard reference: [docs/features.md](https://github.com/Shuffzord/RoadRaven/blob/master/docs/features.md).\nRelease history: [CHANGELOG.md](https://github.com/Shuffzord/RoadRaven/blob/master/CHANGELOG.md).\n\n- [Features and keyboard reference](https://github.com/Shuffzord/RoadRaven/blob/master/docs/features.md)\n- [MCP install guide](https://github.com/Shuffzord/RoadRaven/blob/master/docs/mcp-install.md)\n- [Plugin authoring guide](https://github.com/Shuffzord/RoadRaven/blob/master/docs/plugin-authoring.md) (write your own Event Producer)\n- [Architecture overview](https://github.com/Shuffzord/RoadRaven/blob/master/docs/architecture-overview.md)\n- [Development guide](https://github.com/Shuffzord/RoadRaven/blob/master/docs/development-guide.md)\n- [Design system](https://github.com/Shuffzord/RoadRaven/blob/master/docs/design-system.md)\n- [Logging](https://github.com/Shuffzord/RoadRaven/blob/master/docs/logging.md)\n\nRoadRaven is built on [Electrobun](https://blackboard.sh/electrobun/) (not\nElectron) with Bun as the runtime. Local setup, test commands, code style,\nand project conventions are in [CONTRIBUTING.md](https://github.com/Shuffzord/RoadRaven/blob/master/CONTRIBUTING.md).\n\n```\nbun install\nbun run dev:hmr       # Vite HMR + Electrobun\nbun run verify        # tests + typecheck + build + lint\n```\n\nI built RoadRaven to scratch my own itch. When you're working on something with a lot of moving parts, your plan and your actual work drift apart fast. The plan lives in a doc or in your head, while the real state is scattered across terminals, CI, and AI agents. The doc is out of date the moment you write it, and slowly turns into fiction.\n\nIt started as a personal study- and project-tracker. The moment it clicked was\nwatching nodes flip status on their own as Claude Code worked through tasks. I\nhadn't touched anything, I just opened the app and the current state was right\nthere. That's the whole idea: **your plan, watching itself.**\n\nIf you have ideas, hit rough edges, or want a node to watch something I haven't\nthought of yet, please open an [issue](https://github.com/Shuffzord/RoadRaven/issues)\nor a PR.\n\n[Functional Source License 1.1, MIT future license](https://github.com/Shuffzord/RoadRaven/blob/master/LICENSE) (FSL-1.1-MIT),\nthe same license Sentry uses. In plain words:\n\n- **You can use it for anything** , at home or at work, free, including\ninside a company. Modify it, fork it, ship it with your own tools.\n- **The one thing you can't do** is sell or host RoadRaven itself (or a thin\nfork of it) as a competing product.\n- **Every release turns into plain MIT two years after it ships** , automatically.\nNothing is locked away forever.\n\nNot OSI \"open source\", but close: source-available, free to use, MIT in time.", "url": "https://wpnews.pro/news/show-hn-roadraven-a-project-plan-your-coding-agents-keep-up-to-date", "canonical_source": "https://github.com/Shuffzord/RoadRaven", "published_at": "2026-10-10 15:52:59+00:00", "updated_at": "2026-10-10 16:17:16.396186+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "agent-protocols", "ai-tools"], "entities": ["RoadRaven", "Shuffzord", "Claude Code", "OpenCode", "MCP", "Node.js", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-roadraven-a-project-plan-your-coding-agents-keep-up-to-date", "markdown": "https://wpnews.pro/news/show-hn-roadraven-a-project-plan-your-coding-agents-keep-up-to-date.md", "text": "https://wpnews.pro/news/show-hn-roadraven-a-project-plan-your-coding-agents-keep-up-to-date.txt", "jsonld": "https://wpnews.pro/news/show-hn-roadraven-a-project-plan-your-coding-agents-keep-up-to-date.jsonld"}}