Helm

Helm (formerly roadmap-board) is a live dashboard and job tracker for projects that you build with Claude Code. The command is roadmap; bin/helm is an identical alias. Repo: github.com/alisinaee/helm. State folders and the roadmap package keep their old names. It reads each project’s docs/tasks.json, shows the phases and the tasks left, and lists the jobs Claude is running now. It also shows your plan usage and your token limits, with rules that agents follow. The page is served on your Mac only, at http://127.0.0.1:8780/, and nothing leaves the machine except the usage check and the phone tunnel, which you start yourself. You use it as a GUI, and AI agents use the same data through the roadmap command, where every command takes --json. It is Python 3.9 or newer with the standard library only: nothing to pip install, no build step.

Install

You need a Mac, Python 3.9 or newer (python3 --version), and Git.

git clone  ~/Works/helm
cd ~/Works/helm
make check                               # lint and unit tests; it must pass before you use it
bin/roadmap service install              # the background agent that serves the page on 127.0.0.1:8780
mkdir -p ~/.local/bin
ln -s "$PWD/bin/roadmap" ~/.local/bin/roadmap

Put ~/.local/bin on your PATH if it is not there yet (add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc). Then check the install with roadmap version and roadmap doctor. roadmap doctor lists each check as ok, warn or fail, with the fix for each problem, and it is safe to run at any time. Keep the clone where it is: the launchd agent and the hooks in your projects point at this folder.

Quick start

Run roadmap init in your project folder (registers it, installs the hooks, starts the service; safe to repeat), then start Claude Code and run /head. --no-service skips the service.

First run

1. Register your project. A project is any folder with a docs/ folder inside it: roadmap project init and roadmap project add --name "My App".
2. Install the hooks, so Claude Code records jobs for you: roadmap hooks install my-app.
3. Open the dashboard: roadmap open, or go to http://127.0.0.1:8780/ yourself.

The details, and a job recorded by hand, are in Quick start with a project.

The dashboard

The GUI has these sections, in the navigation rail: Overview, Inbox, Roadmap, Work, Issues, Agents, Tokens, Rules, Research, Activity and Settings.

Honest notes

• Usage. The usage collector reads the Claude Code sign-in from the keychain, which needs a Claude Code CLI login on this Mac for the account token. macOS asks once, and you should choose Always Allow. Without that login, enter the numbers yourself with roadmap usage push (see Plan usage).
• Phone access. roadmap phone start needs one step from you first: the tunnel host key must be added to known_hosts by hand (see Phone access).
• Hooks. roadmap hooks install edits the project’s .claude/settings.local.json, makes a backup first, and changes nothing when run again.

Quick start with a project

A project is any folder with a docs/ folder inside it. project init writes the template data files into docs/ and keeps any file that already exists. project add registers the folder under an id.

roadmap project init 
roadmap project add  --name "My App"
roadmap project check my-app

`` is the folder of your project, for example ~/Works/my-app. The id my-app comes from the name. The check reads every data file and prints its schema version.

Next, install the hooks, so Claude Code records jobs for you:

roadmap hooks install my-app

This merges three hook entries into /.claude/settings.local.json. A backup of the old file is made first, and running the command again changes nothing. See Hooks.

Record a job by hand. The task id must exist in the project’s tasks.json:

roadmap job start "Write the README" haiku P1.1
roadmap job done j1 "README drafted" --tokens 12
roadmap job list

job start prints the job id (j1 in a fresh project). Use the id it printed in job done. --tokens is in thousands of tokens.

Then start the background service and open the page:

roadmap service install

Open http://127.0.0.1:8780/ in a browser tab. The page refreshes itself every 2 seconds.

New project

For a new project, an agent follows the draft skill docs/skill-draft/roadmap-plan-new/SKILL.md. It reads roadmap agent-guide, asks a few questions, and writes up to 6 research notes in docs/research/. Then it imports the plan. Check the notes with roadmap research check, and the plan with roadmap plan import and --dry-run first. To install the packaged skills, run roadmap skills install, which copies them into /.claude/skills.

Plan usage

The usage band on the page shows your weekly and five-hour plan usage, the time until each limit resets, and when the reading was taken. It comes from the account that is signed in to Claude Code on this Mac.

What roadmap usage sync does, step by step:

1. It runs security find-generic-password -s "Claude Code-credentials" -w. That is the keychain item where Claude Code keeps its sign-in. The security tool is run with an argument list; no shell is involved.
2. macOS asks once. The first time, the Keychain shows a prompt that asks whether security may use this item. Choose Always Allow if you want the background service to keep the usage fresh. If you choose Deny, the sync fails with “keychain access denied”, and nothing else changes. You can run the sync again later and answer the prompt then.
3. The access token from that item is kept in memory for one request. It is never printed, logged, or written to a file.
4. It sends one HTTPS GET to api.anthropic.com (/api/oauth/usage) with the token. Redirects are refused. No other host is contacted. This endpoint and its beta header are not a documented public API, so they can change. If they do, the usage reading fails with a plain reason and the last good numbers stay.
5. It keeps the five-hour and weekly percentages, their reset times, the time of the reading and the source. The record goes to ~/Library/Application Support/roadmap-board/usage.json. It is then copied into the usage block of each registered project’s docs/autonomy.json, so the work-limit rules your agents follow can read it there.

The background service runs step 1 to 5 every 120 seconds. After 3 failures in a row it waits 600 seconds. A reading older than 240 seconds (twice the interval) is marked stale on the page and by usage show.

roadmap doctor checks that the keychain item exists. It does not read the secret.

To enter the numbers yourself, for example from the usage panel of the Claude app, pipe JSON into roadmap usage push. The windows that you leave out keep their values:

echo '{"rateLimits":[{"kind":"seven_day","percentUsed":61,"resetsAt":"2026-10-16T07:59:00+00:00"},{"kind":"five_hour","percentUsed":13,"resetsAt":"2026-10-13T18:00:00+00:00"}]}' | roadmap usage push

Hooks

roadmap hooks install adds three entries to the project’s .claude/settings.local.json:

Each entry runs the absolute path of bin/roadmap with the word hook. The desktop app gives hooks a minimal PATH, so the absolute path is needed. The hook never fails a tool call and prints nothing.

The job title comes from the agent’s description, and the task id comes from the description or prompt. Put the task id in the description, for example P1.3 parser review. Tokens are not known to hooks, so add them with roadmap job done "" --tokens .

roadmap hooks status shows which events are installed, and roadmap hooks uninstall removes only roadmap’s entries.

Commands

Every command accepts --json and then prints {"ok": true, "data": ...} or {"ok": false, "error": {"code", "message"}}. Exit codes are listed under Exit codes.

--project ID is optional. Without it, roadmap uses $ROADMAP_PROJECT, and then the registered project whose folder contains the current directory.

Phone access

roadmap phone start makes a new random token (file mode 0600), starts a read-only listener on 127.0.0.1:8766, and opens an ssh tunnel to localhost.run for a public address. roadmap phone link prints the private link, roadmap phone status shows whether the tunnel runs, and roadmap phone stop closes it and deletes the token.

Before the first phone start, add the tunnel host key once, by hand: run ssh-keyscan localhost.run, check the key yourself, and append its lines to the known_hosts file in Helm’s state folder. roadmap never fetches the key itself, and phone start exits 6 until the key is there. See docs/SECURITY.md.

Troubleshooting

Run roadmap doctor first. Each row below is a message it can print, with the fix it gives.

If a job or a task is refused, the message names the id. job start with an unknown task id exits 3 and says task 'X' is not in tasks.json. Add the task to the file, or leave the task argument out.

If the page shows a banner for a file, the file is the problem, not the server. Run roadmap project check and fix the file it names. A file written by a newer Helm is never overwritten: update Helm first.

Exit codes

Migrating a project from tools/roadmap-web

Older projects carry a copy of the dashboard in tools/roadmap-web/. The copy is replaced by this command, and the data files stay where they are.

1. Install Helm as above, and run make check.

2. Keep docs/tasks.json, docs/jobs.json and docs/autonomy.json as they are. project init keeps them.

3. Turn docs/roadmap.config.json into the new format, if the project has one. The old keys map like this:

   Old key	New key
   title	title (same)
   files.spikes	extras.spikes (a file name)
   files.testing with testing_section	extras.testing = {"file": ..., "section": ...}
   files.roadmap with next_heading and log_heading	extras.roadmap = {"file": ..., "next": ..., "log": ...}

   A project with none of these needs only "schemaVersion": 1. Keep taskIdPattern and hookDetectors if you changed them.

4. Register the project as in the quick start (roadmap project init and roadmap project add), then replace its hooks:

   roadmap hooks install my-app --replace-legacy
   roadmap project check my-app
   

   --replace-legacy removes only the old jobs_auto.py entries. It leaves every other hook alone.

5. Restart the service, then check the page: roadmap service restart and roadmap doctor.

6. When the page shows the project and the hooks work, delete tools/roadmap-web/ from the project yourself, and remove the old hook lines by hand if --replace-legacy did not find them.

Nothing in Helm deletes the old copy for you.

Uninstall

roadmap service uninstall
roadmap hooks uninstall my-app
roadmap project remove my-app
rm ~/.local/bin/roadmap

service uninstall removes the launchd plist and unloads the agent. hooks uninstall removes only roadmap’s entries from the project’s settings. project remove unregisters the folder and keeps its files. Your project’s docs/ files are never deleted by Helm.

To remove roadmap’s own state, delete these folders by hand. Nothing else on your Mac is touched:

• ~/.config/roadmap-board/ (the registry and the phone token, once phone access exists)
• ~/Library/Application Support/roadmap-board/ (usage, hook state, backups)
• ~/Library/Logs/roadmap-board/ (logs)

Development

See CONTRIBUTING.md for make check, the layering rule, change fragments and the definition of done. The design is in docs/ARCHITECTURE.md. The HTTP contract is in docs/API.md, and the threat model is in docs/SECURITY.md.

Interactive project manager (agents and GUI)

An interactive management bridge combining a browser GUI for humans with a fast, cheap CLI for AI agents. Both interfaces share a unified command layer where every write executes as a validated, undoable operation. Agents receive compact text outputs without parsing JSON, minimizing token spend and latency. Enforces oversight through live budget meters, weekly usage limits, task rules, and tool-use guard hooks.

GUI capabilities

• Overview & Inbox: One-click stop/resume, live budget and usage meters, active agents card, and single-click answers to agent questions.
• Roadmap & Work: Phase lanes with progress bars and spend, task reordering, phase approvals, and Kanban board or tree task management.
• Task drawer: Inspect status, manage subtasks and comments, view linked issues, and check applicable rules.
• Issues: Open new issues, link them to tasks, and close resolved issues with one click.
• Tokens & Rules: Adjust spend caps and weekly stop limits, trigger temporary overrides, and edit rules with one-click sync to CLAUDE.md.