outbox-md

Local-first, agent-agnostic review for AI-generated Markdown specs.

▶ Watch the full walkthrough — what it is, how to use it, and the architecture

Read and inline-annotate AI-generated Markdown in your browser. Your comments never edit the document directly — they enter an ordered outbox and are handled by any AI agent you connect over MCP. The agent proposes a tracked change or replies; you accept; the file is rewritten and versioned. The document is never corrupted.

• Local-first — points at a folder of .md files on your machine. Nothing leaves it.
• Bring-your-own-agent — ships no LLM credentials. Connect Claude, GPT, or anything that speaks MCP.
• Safe by construction — feedback is ordered, edits are tracked changes you approve, the on-disk file is never silently changed.
• Live reload — add, edit, or delete a .md on disk and it appears in the review UI automatically (a filesystem watcher pushes the change over SSE). No restart.

---

Quickstart

1. Install (macOS + Linux) — Homebrew or the install script:

brew install rajanrx/tap/outbox-md
# or, without Homebrew:
curl -fsSL https://raw.githubusercontent.com/rajanrx/outbox-md/main/install.sh | sh

2. Point it at a folder of .md specs and start:

cd path/to/your/specs
outbox init             # scaffold outbox.yaml + auto-wire the MCP with your installed AI clients
outbox up --auto-reply  # serve the review UI, open it, and auto-reply to your comments

outbox init auto-wires Claude Code, Gemini CLI, Cursor, Windsurf, Claude Desktop, and Codex if installed. See Supported clients.

--auto-reply runs a hands-off in-process agent: on each comment you leave, it spawns your Claude CLI (your subscription — no API cost) to reply, reacting only to your comments, never its own. Drop the flag for interactive-only (a plain outbox up, where you drive an agent yourself in a chat). Details: hands-off auto-reply.

3. Connect your agent — if init didn't do it automatically, add this MCP endpoint to your AI client (one URL, no API key):

http://localhost:8181/mcp

4. Review — select a sentence, leave a comment. Your agent picks it up, proposes a tracked change, and you Accept — the .md is rewritten and versioned. That's the loop.

📖 Setup & Usage Guide →

Docker · multiple projects · other agents (Cursor / Claude Desktop / …) · sources scoping · hands-off automation & runners · all commands. Everything beyond the quickstart lives there.

---

Commands

Command	What it does
outbox up	Serve the review UI + MCP, then open it in your browser (the everyday command).
outbox up --auto-reply	Same, plus a hands-off in-process agent that replies to your comments automatically — opt-in, reuses your Claude CLI subscription (no API cost), reacts only to your comments. See Setup.
outbox serve	Same, without opening a browser (what the Docker image runs by default).
outbox init	Scaffold outbox.yaml and register the MCP with your installed AI client(s) in this folder.
outbox add <root> <docs...> [--agent <preset>] · remove · list	Register / unregister / list projects — review several projects from one server, switch in the UI. <root> is the repo root and at least one docs subpath is required (use . to serve the whole repo, e.g. outbox add ~/my-specs-repo .); pass several to serve their union (outbox add ~/work/app specs api-specs). Each project also takes an optional per-project agent (--agent claude|codex|copilot, or --agent-cmd '<cmd> {prompt}'). outbox remove with no argument is an interactive multiselect — tick the projects/docs to drop (removing a project's last docs entry drops the project); outbox remove <name> removes a whole project non-interactively. projects is an alias for list.
outbox paths	Print the resolved on-disk locations (registry, review database, outbox.yaml) for the current mode.
outbox settings [<key> <value>]	View or change the structured outbox.yaml fields (auto_update, auto_reply). No args → interactive walkthrough (Enter keeps current); <key> <value> sets one directly.
outbox upgrade	Update to the latest release (self-update). Homebrew installs update with brew update && brew upgrade outbox-md; Docker via image pull.
outbox version · outbox help [<command>]	Print the version / usage. Bare outbox (no arguments) also prints help; outbox help <command> shows one command's flags and examples.

serve and up take -dir (folder to serve, default .), -addr (listen address, default :8181), and -auto-reply (opt-in hands-off agent, default off). Precedence is flag > OUTBOX_DIR / OUTBOX_ADDR / OUTBOX_AUTO_REPLY env > default.

Full detail — install options, connecting each client, multiple projects, sources scoping, automation — is in the Setup & Usage Guide.

---

How it works

You comment on a doc; the comment enters an ordered outbox instead of touching the file. The server notifies your agent (over MCP) and updates your browser live. The agent claims a comment and either proposes a tracked change or replies; you accept, and only then is the .md rewritten and a new version recorded. Resolving comments and approving docs stay human-only — an agent can't accept its own work.

   you (browser)                              your AI agent
  ┌──────────────────┐                   ┌──────────────────────┐
  │ comment / accept │──▶ ordered outbox │ claim → propose /    │
  │ reply / resolve  │◀── live (SSE) ────│ reply  (via MCP)     │
  └──────────────────┘                   └──────────────────────┘
                   accept → file rewritten + versioned

---

Status & limitations

The review loop, governance, and audit log all work and are covered by tests. Honest caveats:

• Local-first & unauthenticated — built for a single user on localhost. Don't expose the port without auth in front (see SECURITY.md).
• Supervise long agent runs — a crashed agent's claims aren't auto-recovered yet (no reaper).
• Agents respond, they don't initiate — an agent acts on comments you raise; it can't open new ones (AI-council is on the roadmap).

---

Design

• Core design: docs/specs/2026-06-27-outbox-md-design.md
• Governance seam: docs/specs/2026-06-28-governance-seam-design.md
• Decision log: docs/specs/2026-06-30-decision-log-design.md

License

MIT — see LICENSE. Contributions welcome — see CONTRIBUTING.md.