hostplan

A home for the plans your coding agents write.

Hostplan is an open-source CLI and web viewer that gives coding-agent plans stable, shareable, machine-readable URLs. Agents produce plans constantly and they land wherever — ~/.claude/plans, a repo's PLAN.md, a scratch file that gets deleted. Hostplan gives every plan one address, filed by project and branch, readable in a browser or by the next agent.

$ hsp add PLAN.md
✓ stored  Worktree GC  ·  nest / feat/delivery  ·  a3f9c2  ·  private
→ https://plans.host-plan.com/p/a3f9c2            asks for the code
→ https://plans.host-plan.com/p/a3f9c2?code=KRWT  opens directly

Another agent runs hsp get a3f9c2 to read it back. You open the URL and get a rendered page, with an Open in button that hands the plan straight to Codex, Claude Code, or Cursor. The same URL is machine-readable: curl it and Hostplan returns the original Markdown without the Next.js page, scripts, or viewer chrome.

curl -fsSL 'https://plans.host-plan.com/p/a3f9c2?code=KRWT'

Works entirely offline against a folder on your machine. Sign in to a deployment and the same plans become shareable links.

Requires Bun and Node 20+.

bun add --global hostplan
hsp --version

You can also run npm install --global hostplan; the CLI still uses Bun at runtime. To install from source, clone the repository, run bun install, bun run build, and bun link.

hsp is global — the store lives at ~/.hostplan and every command works from any directory, so it's the same in every project. The viewer starts itself the first time you need it.

hsp add PLAN.md              # store a plan, print its URL
hsp get <id>                 # print a plan to stdout
hsp get latest               # the most recent plan here
hsp list                     # plans for this repo and branch
hsp share <id>               # print its shareable links

Plans are live objects, not just documents:

hsp status <id> approved     # draft → approved → in-progress → done
hsp stack s1.md s2.md s3.md  # chain steps; each waits on the one before
hsp next                     # the first plan that's not done and not blocked
hsp check <id> 2 3           # tick the plan's checkboxes off
hsp update <id> PLAN.md      # revise in place — same id, same link
hsp search rate limiting     # full-text, across every project

Project and branch are detected from git, so there's nothing to configure.

Fenced mermaid blocks render as accessible dark diagrams, including Mermaid flowcharts and block diagrams. They stay plain text in the stored Markdown and become SVG only in the browser.

For plans that need a visual layout, Hostplan also supports static custom HTML with a versioned component kit for cards, stats, lists, badges, grids, callouts, steps, and tables. Agents can fetch the exact contract, validate the file, and store it through the same workflow:

hsp guide custom-html
hsp validate plan.html
hsp add plan.html

Custom plans run without scripts or network access inside a sandboxed document.

Plans are private by default. A private plan gets a 4-letter code, and hsp add prints both forms of its link — the bare one asks for the code, the ?code= one opens directly. hsp add --public gives a single link that opens for anyone. Publishing should be deliberate, which is why it takes a flag.

Codes are casual privacy, not cryptography: 4 letters is ~234,000 combinations, rate-limited but guessable given time. Don't host anything genuinely sensitive.

Full command reference, sharing rules, and environment variables: docs/cli.md. Runnable plans for every workflow command: examples/.

Web guides: coding-agent plans, plan handoffs, Hostplan vs. PLAN.md, and agent setup.

Everything above works with no server. To get shareable links and a dashboard of your own plans, deploy it: Next.js on Vercel, Supabase for storage and accounts, sign-in by magic link, and hsp login to connect a terminal.

See docs/deploying.md.

bun test          # unit tests and the plan-store contract
bun run typecheck
bun run lint      # biome
bun run dev       # viewer with hot reload on :7433

Three workspaces:

• packages/core — the store. Paths, ids, metadata, git detection, access rules. Used by both apps.
• apps/cli — hsp. Run straight from TypeScript by Bun, no build step.
• apps/web — the Next.js viewer.

Both store backends run the same contract suite, so the filesystem and hosted implementations can't quietly drift.

MIT