a tool you install — not one that runs here

bosun‑x

Cross-agent handoff and task tracking for a set of projects you build with AI. The bosun is the hand who keeps the ship and crew in working order; bosun‑x does that for your projects — a record of what’s actually done, a clean starting point for the next session, and a task board that can’t drift.

A command-line tool and an MCP server over the same plain files. MIT.

the repo npm: bosun-x

the problem

If you build software with an AI assistant across more than one project, you know the tax. Every session starts cold — you re-explain what the project is, what’s done, what you were mid-way through, what not to touch. The record drifts: the assistant thinks a task is finished, the code says otherwise. Two assistants in two windows edit the same project, neither aware of the other. A session hits its limit mid-task and the next one has to guess what was already decided.

bosun‑x is the small amount of structure that fixes this — with no database, no web app, and no subscription. If you have one project and one assistant, you probably don’t need it. It earns its place once picking work back up has started to hurt.

how it works

When you start work, you open a handoff. As you go, you checkpoint what’s verified done, where things stand, and the one next action. Two files get written: an append-only log of everything, and a small fixed-size snapshot. The next session reads only the snapshot.

A checkpoint writes both files. Resume reads only the bounded snapshot — the current state plus a trail of the last four one-liners, so a hasty checkpoint can’t erase the trajectory.

Writes go through one command that holds a per-project lock, so two assistants working the same project take turns instead of clobbering each other — and a checkpoint from the wrong one is rejected outright.

One writer at a time. A checkpoint from an assistant that doesn’t hold the current turn is refused, not merged.

the dashboard

On its own, bosun‑x is a CLI and an MCP server — the engine that keeps the log honest. Control Room is the web application built on the same plain files: every project’s containers read live off the Docker socket, standards checked rather than claimed, the spec and handoff rendered and editable, the planning lifecycle, whole servers across a fleet. bosun‑x is the discipline; Control Room is where you look at all of it at once.

The Control Room detail page for a project, showing its status, running containers, standards results and latest handoff. — Control Room’s page for one project: lifecycle stage, live containers, the standards column, and the latest handoff with a staleness clock. The same plain files underneath.

Control Room is being prepared for release — the same “plain files, nothing stored, self-hosted” shape. bosun‑x is the part you can take today.

if you don’t write code

Plenty of people build real apps now without writing the code themselves — they describe what they want and an AI assistant does the typing. If that’s you, bosun‑x is still for you, and you don’t run any of the commands on this page yourself.

You point your assistant at it once:

“Set up bosun‑x for this project — the repo is github.com/x-hakt/bosun-x. From now on, checkpoint your progress as you work, and when I say resume, pick up from the last checkpoint.”

After that, the difference is: you stop re-explaining your project every time you sit down. You open a session and say “resume the pricing page,” and the assistant already knows the three-tier layout is done, the toggle is half-built, and the next job is wiring the prices — because the last session wrote that down in a form the next one can read. You can also ask “what’s the state of everything?” and get a straight list across all your projects.

It’s a folder of plain text files in your project. Nothing is uploaded anywhere, nothing runs in the background, and you can open any of it in a normal text editor if you ever want to look.

get it

Node 20 or newer. Once it’s published to npm:

npm i -g bosun-x          # or run it ad-hoc with: npx bosun-x <command>

Until then, from source:

git clone https://github.com/x-hakt/bosun-x
cd bosun-x && npm install && npm link

Run bosun from the directory that holds your project data, or point $BOSUN_DATA at it. Projects live in <data>/projects/<slug>/.

configure

`$BOSUN_DATA`	where the projects live (default: the current directory)
`$BOSUN_TZ`	timezone for timestamps (default: the system zone). Or `timezone` in `bosun.config.json`.
`$BOSUN_STALE_MINUTES`	when an open handoff is flagged stale (default: 30)

use it

The loop, once per project:

# starting work
bosun start pricing-page --agent Claude --summary "rebuild the pricing page" --task PP-1

# after every verified milestone, at least every 30 min, and before anything risky
bosun checkpoint pricing-page --agent Claude \
  --done "three-tier layout done, responsive to 360px" \
  --state "the annual/monthly toggle is stubbed, no real prices wired" \
  --next "pull prices from config and wire the toggle" \
  --task PP-2 --tests "visual check at 360/768/1200: clean"

# before you stop
bosun finish pricing-page --agent Claude --done "..." --state "..." --next "..." --task PP-2

On the next session, before touching anything:

$ bosun resume pricing-page

project:       pricing-page
status:        active
agent:         Claude
tasks:         PP-2
checkpoint:    2026-09-01T14:50 (3m ago)
work:          three-tier layout done, responsive to 360px
current_state: the annual/monthly toggle is stubbed, no real prices wired
verification:  visual check at 360/768/1200: clean
next_step:     pull prices from config and wire the toggle

trail (older, newest first):
  - 14:12 Claude: rebuild the pricing page

And to see the whole fleet at a glance, or catch anything that’s drifted:

$ bosun status
pricing-page:  active   · Claude · 3m · PP-2 · three-tier layout done
marketing-api: finished · Codex  · 2d  · shipped rate limiting
docs-site:     stale    · Claude · 5h  · mid-migration to Astro

$ bosun doctor
bosun doctor: all tracked projects are initialized, no drift

wire an AI to it

1. The convention, in the file your assistant reads. From inside a project:

bosun init

adds a short managed block — the checkpoint discipline in a few lines — to whichever of CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md is already there.

2. The MCP server, so your assistant has real tools instead of shelling out:

{
  "mcpServers": {
    "bosun-x": {
      "command": "bosun-mcp",
      "env": { "BOSUN_DATA": "/abs/path/to/your/data" }
    }
  }
}

Drop that into Claude Code’s .mcp.json, Claude Desktop’s config, or the same field in Cursor / Cline / Zed / Codex. It exposes project_brief (the session-start bundle), list_projects, list_tasks, the handoff verbs, set_task_status and create_task.

3. The skill (Claude Code) — skill/bosun/SKILL.md in the repo teaches the discipline and triggers on “resume”, “checkpoint”, “pick up work on”.

under the hood

One directory per project. Every file is meant to be read and edited by hand as comfortably as by the tool — grep is a first-class client.

projects/<slug>/ — the whole contract. No database, no proprietary format.

Anything an incoming assistant reads has a token budget: the snapshot is bounded, the trail is clipped one-liners, and noisy work-in-progress is collapsed into one clean entry before you finish. The full technical reference — every command, the config, the MCP tool list — is in the README on GitHub.