Open source · Local first

Your coding agent wrote a plan.Read it like a document.

better-md opens your agent's Markdown in a local editor. Watch plans update live, make changes, and save straight back to the original file.

Install better-md Try the playground →

$ curl -fsSL https://better-md.dev/install.sh | sh

macOS and Linux · arm64 and x64 · no Node.js required

~/.claude/plans/search-indexing.md

## Task 1: Tokenizer

- [x] Split on Unicode word boundaries
- [x] Fold case and strip diacritics
- [ ] Property test: tokens round-trip

## Task 2: Inverted index

| Structure | Cost |
| --------- | ---: |
| `Map`     | O(1) |
| `Uint32`  | 4n B |

Preview · editable

Task 1: Tokenizer

Split on Unicode word boundaries
Fold case and strip diacritics
Property test: tokens round-trip

Task 2: Inverted index

Structure	Cost
`Map`	O(1)
`Uint32`	4n B

127.0.0.1 · local only

Browsers can't open your files. This one can.

That restriction is why a web editor normally cannot touch your work. The CLI closes the gap by becoming a small local server the editor talks to — no account, no sync service, nothing to upload.

$ better-md --plan
   │
   ├─ pick the newest plan your agent wrote     claude · cursor
   ├─ serve the editor from inside the binary   no dist/ on disk
   ├─ watch the workspace and stream changes    plans update live
   └─ open http://127.0.0.1:8080/?t=<token>

--plan

Follows your agent

Opens whichever of Claude Code or Cursor wrote most recently. --agent cursor picks one.

live

Keeps up as it writes

The workspace is watched, so a plan updates on screen while the agent is still writing it. Unsaved edits are never overwritten.

Cmd+S

Saves to the real file

Nothing is written until you press it. If the file moved on disk meanwhile, the write is refused rather than silently winning.

better-md showing a plan: Markdown source on the left, rendered preview on the right — The editor, serving a real plan from disk on 127.0.0.1

$EDITOR · no server

Or stay in the terminal.

-t renders the plan where you already are. Same file resolution, same live reload, no server and no browser — and when you do want to change something, one key hands the file to your editor and another opens the browser editor.

$ better-md --plan -t

Auth Plan
═════════

Goal
────

Ship password login behind a flag.

✓ schema migration
✓ session store
○ rate limiting
○ audit log

live

Keeps your place

The pane updates as the agent rewrites the plan, and holds the spot you were reading inside a section rather than jumping back to the top.

/ and o

Search and outline

/ finds text literally, so plan.md never matches planXmd. o lists the headings to jump between.

e and b

Leave when you need to

e opens the file in $EDITOR; b opens the browser editor, reusing the server if one is already running.

Piping prints plain text and exits, so -t plan.md | less and > plan.txt both work. There is no editing in the terminal itself, and code blocks are shown verbatim rather than reflowed.

~/.claude/settings.json

Or never type the command at all.

better-md init claude shows you a Claude Code hook that opens each finished plan the moment it is written. Add --write to apply it, and everything already in your settings is preserved.

$ better-md init claude --write

Bearer token · origin check · path confinement

It runs a server on your machine, so it earns the trust.

Any page in your browser can reach a localhost port. Three independent layers guard the file API, and the editor's own assets are embedded in the binary — that route resolves no paths and opens no files, so it cannot be walked out of.

A fresh 32-byte token per run, required on every request, compared in constant time, and sent as a header that a cross-site request cannot forge. It is stripped from the address bar at boot.
Requests carrying a foreign origin are refused.
File access is confined to one directory, checked after resolving symlinks, and limited to .md, .markdown and .txt.
Almost nothing is kept. No account and no browser storage. The one exception is ~/.better-md, where a detached run records the port it is listening on so the next one reuses it instead of starting a second server — and better-md uninstall removes that along with the binary.

~/.local/bin

One file. No runtime to install.

The installer picks the right build, verifies it against the published SHA256SUMS — refusing if that does not match — and drops it in ~/.local/bin. Prefer to read it first? It is served as plain text, so better-md.dev/install.sh opens in a browser.

$ curl -fsSL https://better-md.dev/install.sh | sh

`better-md --plan`	Your agent's plans — whichever of Claude Code or Cursor wrote most recently, with that plan active
`better-md --agent cursor`	Narrow `--plan` to one agent
`better-md notes.md`	A single file, or point it at a directory
`better-md notes.md -t`	Read it in the terminal instead of the browser — same live reload, and `e` or `b` when you want to edit
`better-md init claude`	Preview a Claude Code hook that opens each finished plan; add `--write` to apply it
`better-md update`	Verify and replace this binary with the latest release
`better-md --sessions`	Which detached servers are running, and where — stale records pruned
`better-md stop`	Stop the detached servers — all of them, or one workspace
`better-md uninstall`	Remove it, alias included

Serves on 8080 by default, falling back to a free port if that one is busy. btr-md is a shorter alias for the same binary.

Rather not install anything? Try the editor in your browser — it runs with sample documents, since opening your own files is exactly the part that needs the local command.