Helmo

Agents write, humans read and meet. Helmo is a self-hosted work record for AI agent teams, the roadmap above it, and the supervisor that keeps the agents turning — one product, three areas, one version.

That view is the whole interface. Helmo exists for the moment your agents outrun your ability to re-read everything they did: what needs you is at the top, "done" without an evidence link surfaces as a flagged claim, and every line traces to who wrote it — which agent, which model, at what cost.

The two stores stay separate and unmigrated: together they read as one system, apart each stands alone. Nothing a configuration file, a plist, a bookmark or a loaded tool schema names changed when the three products became one.

Status

MVP, one version. The current number is the root package.json version; every area and shipped protocol surface reports that same one, and a figure restated here would only drift from it. All three areas are dogfooded on this product's own development. What the version number promises, and what counts as a breaking change, is VERSIONING.md. The automated floor is the root npm run build and npm test; independent review still gates acceptance, and publication is a separate release decision. No 1.0 gate is claimed.

Related MCP server: Rapiber Ticket Manager

Install

Agent-led install is the primary path. Tell your agent: "I want to use Helmo — install it and set it up." and point it at AGENT-INSTALL.md — one guide for the one product. It runs end to end, turns on the areas you asked for, and returns your links and getting-started instructions.

Manual setup, if you prefer:

git clone https://github.com/arthurcoulston/helmo.git
cd helmo
npm ci
npm run prepare:cold
npm run build
npm install        # links the commands that point at built output
npm test

That is the isolated cold setup: it needs no sibling project and the tests use fresh temporary databases. Node.js 20 or newer. A few design-source drift comparisons report skipped when the private estate source is absent; the vendored copies are still tested.

npm run prepare:cold marks a fresh git checkout as writable and refuses an export or assembled release tree. The root build writes only into a checkout carrying that ignored build marker — refusing in any release directory and any checkout an installation resolves through, so a build can never overwrite the code a running view or supervisor loads. It is a deliberate speed bump that makes the choice explicit, not an authentication boundary; scripts/build.mjs is the whole of it.

better-sqlite3 uses a prebuilt binary when one matches your Node version; otherwise it compiles from source, which needs a C toolchain and Python ≥ 3.8 (node-gyp). If install fails in node-gyp rebuild, an old python3 on your PATH is the usual culprit — on macOS, PYTHON=/usr/bin/python3 npm install fixes it.

The one command

node_modules/.bin/helmo --help

helmo is the front door to every area: helmo work, helmo roadmap, helmo run, helmo team, helmo release, helmo service, helmo serve <area> and helmo mcp. The unified MCP entry point serves both Work and Roadmap tools; helmo mcp work and helmo mcp roadmap retain the individual surfaces for compatibility. The older per-area binaries helmo-cli, helmo-mcp, roadmap-mcp and helmo-view still work and print what replaces them; rev is a permanent alias for helmo run. COMPATIBILITY.md has the dates, and the rest of this page names the packages/*/dist paths that have not moved.

Running more than one installation

One installation needs none of this. For more than one, or to change which release one runs:

• INSTALLATIONS.md — install identity, pinned releases, upgrade, rollback and removal. An installation assembled from immutable releases sets INSTALLATION_RELEASE to its selection file; every entry point then verifies the selected commit and refuses to run from another checkout.

• ENTRY-POINTS.md — the checklist of every path your setup names, and how to verify what is actually running rather than trust it.

• ISOLATION-CHECKS.md — an independent review of those guarantees, with a two-installation checklist and the public tests.

Connect an agent (MCP, stdio)

Each agent's MCP config launches the server with the agent's identity:

{
  "mcpServers": {
    "helmo": {
      "command": "node",
      "args": ["/path/to/helmo/packages/work/dist/server.js"],
      "env": {
        "HELMO_ACTOR": "{\"name\": \"builder-loop\", \"kind\": \"agent\", \"model\": \"claude-sonnet-5\", \"version\": \"1.0\"}"
      }
    }
  }
}

Roadmap's server is packages/roadmap/dist/server.js, with ROADMAP_ACTOR or the same HELMO_ACTOR. The tool descriptions teach correct usage; no separate convention doc is required. Each area's README covers its own surface in full — the work-record tool set, product acceptance and the workflow gate in Work, derived rank and charters in Roadmap, and what an unattended loop session can actually do in Runtime. Read that last one before registering a loop.

Run a meeting

In your agent session (Claude Code, Codex): "Summon helmo orchestrator" → HELMO-ORCHESTRATOR.md is loaded as context. The orchestrator walks you through the awaiting-human queue and records your answers. For the running machine, "summon the watch officer" → WATCH-OFFICER.md. AGENTS.md routes every other kind of session.

Development

npm run build       # every package, in dependency order
npm test            # every package, including the invariant that every
                    # record rebuilds exactly from its event log

DEV.md is the coding context for the repository as a whole; each area has its own DEV.md for its internals. Changes are tracked in Helmo itself.

Bugs and feature requests go in this repository's issue tracker — one tracker for all three areas. Security reports do not: use private vulnerability reporting, per SECURITY.md.

Prior art

Helmo sits in a small family of agent work-trackers and owes a nod to beads, Steve Yegge's git-backed issue graph that gives coding agents long-horizon memory of their own work. If what you want is agent memory — epics, dependency graphs, issues that travel with the repo — use beads; it is excellent at that.

Helmo's center of gravity is the other side of the table: the human who has to trust the work without re-reading it. Hence the append-only event log with full actor provenance, "done" without an evidence link surfacing as a flagged claim rather than a fact, an awaiting_human queue designed to protect the operator's attention, and per-ticket metering of what the work actually cost. Same genus, different optimization.

License

MIT. Third-party notices: THIRD_PARTY_NOTICES.md.