📚 Librarian

A decision library for AI agent sessions. Agents submit their plans and architecture docs over MCP; you read them, comment, and green- or red-light them from any device; every verdict — including every rejection — becomes memory that the agents themselves can query before they design anything else.

Rent the conversation. Own the decisions.

---

The problem

You run five or six agent sessions at once. Each one produces plans, ADRs, and design docs that are buried inside a linear chat transcript. One chat cannot show you many decisions. So:

• Decision docs scatter across repos and sessions; there is no one place to read them.
• Sessions sit blocked on approval while you are looking at a different terminal.
• Approvals get rubber-stamped, because the doc and the approve button live in different places.
• Rejections vanish. A red light shapes a design as much as a green light does — but nothing records it, so a fresh session cheerfully re-proposes the idea you turned down last week.

What Librarian does

One small daemon on your machine, holding one SQLite file:

• An MCP server any agent can talk to — Claude Code, Codex, or your own. Agents submit designs and wait for your verdict.
• A library — every decision, across every project, in one structured view instead of buried in chat.
• A red-light memory — rejections are first-class records, and agents can query them (get_constraints) before proposing, so you stop re-litigating the same bad idea.
• A safety net — a watcher reads your agent transcripts and captures decision docs even when the agent forgets to submit one.

Everything stays on your disk. There is no cloud, no account, and no telemetry.

Install

git clone https://github.com/ivankwongtszfung/librarian.git
cd librarian
npm install
npm run build
npm start

Then point an agent at it:

claude mcp add --transport http librarian http://127.0.0.1:7801/mcp

Open http://127.0.0.1:7801 to read the library.

Add this to your agent's instruction file (CLAUDE.md, AGENTS.md) to close the loop:

Before proposing any design or plan, call get_constraints for the project to see what has already been decided and rejected. Before finalizing one, call submit_for_review and poll get_review until it resolves.

The tools an agent gets

Tool	When the agent calls it
get_constraints(project, topic?)	Before designing. Queryless on purpose — you can't search for a constraint you don't know exists. Returns what was approved and what was rejected, with reasons.
search_decisions(query, …)	Mid-design, for a specific question: "has Redis been considered here?" Searches every decision, including rejected ones.
submit_for_review(project, title, doc, …)	Before acting on a design. Returns a review_id.
get_review(review_id, wait_seconds)	Waits for your verdict (server-side long-poll, ≤50s per call). Resolves to approved, rejected + reason, or changes_requested + your comments.
record_decision(…)	Files a decision that needs no approval. Doesn't gate, doesn't notify.

How a decision flows

1. An agent finishes a design and calls submit_for_review.
2. It appears in your library as pending, and your phone buzzes (if you set --ntfy).
3. You read the doc — the whole point — then approve, reject with a reason, or comment and request changes.
4. The agent's get_review resolves. On changes, it reads your comments, revises, and resubmits with parent_review_id; you get a v1 → v2 diff, so re-reading costs seconds.
5. The verdict is recorded forever, comments and all. The thread is the decision's rationale.
6. The next agent that calls get_constraints sees it — including the red light.

Design notes

A rejection must carry a reason. The API refuses a red light without one (422), and so does the database. A rejection that doesn't say why isn't a decision, it's a shrug.

Verdicts are append-only. rejected → revised → approved is the shape of a real decision record, and none of it is ever overwritten. That chain is exactly the "alternatives considered" section nobody writes by hand.

The long-poll cannot lose a verdict. get_review is an idempotent read reconstructed from committed rows. A dropped connection, a re-poll, or a daemon restart all return the same answer — losing the connection costs latency, never a decision.

One decision is one thread. A revision adds a version to the same decision; it does not mint a new one. Doc, comments, and verdict history stay together.

Options

librarian [options]

  --port <n>        HTTP port (default 7801)
  --host <addr>     bind address (default 127.0.0.1)
  --db <path>       SQLite file (default ~/.librarian/librarian.db)
  --token <secret>  require a bearer token on /api
  --ntfy <url>      ntfy topic URL for push notifications
  --watch [dir]     auto-capture from agent transcripts (default ~/.claude/projects)
  --no-watch        disable transcript capture

Reading from your phone. The daemon binds to localhost by default. To reach it from a phone, run it behind Tailscale (--host 0.0.0.0 --token <secret>) and open the tailnet address. The auth layer is transport-agnostic on purpose — a bearer token is what authorizes a request, not the interface it arrived on — so LAN, Tailscale, or a future relay are interchangeable.

Development

npm run dev      # watch mode
npm test         # unit tests (vitest)
npm run bdd      # acceptance scenarios (cucumber)
npm run check    # lint + typecheck + all tests

The .feature files under tests/features/ are the acceptance criteria, not decoration — they drive a real daemon over real HTTP with a real MCP client.

Status

Phase 1. The review loop works end to end; the library is browsable; the watcher captures decisions from Claude Code transcripts.

Not built yet: the reviewer panel (role-scoped agents that pre-review each doc — the "librarian" consistency checker is the interesting one), context verification against the local repo, the native iOS app, and a chat surface for notifications.

Licence

MIT