libraryan 0.2.2

Your AI agents write Markdown faster than anyone can keep it true.
Libraryan makes one agent the only writer of your project's docs. Every other agent, and every person, files a request.

Quick start · How it works · Demo · Safety · Guide

The problem

Give a repo a few coding agents and a few months, and the Markdown rots: a README that documents flags the code dropped, three setup guides that disagree, NOTES.md, TODO_old.md, an empty ideas.md, and agent instruction files nobody has read since they were written. Every agent writes docs. No one owns them.

The fix: one owner

Libraryan installs an agent that owns every Markdown file in your project: knowledge base, docs and agent instruction files. It is vendor-neutral where it matters: your docs stay plain Markdown in git, the rules live in AGENTS.md (read by Codex, Cursor, Gemini, Copilot, Claude and others), and the lock is a git hook that stops every tool alike.

• 🔒 Single writer, enforced. A git pre-commit hook blocks every other edit, from any agent or editor. This is a hook, not a polite prompt.
• 📨 Everyone else files a request. Other agents and people drop a note in .libraryan/requests/. Libraryan writes the change.
• 🧭 Docs checked against the code. When docs contradict the code, it fixes the docs and reports suspected code bugs. It never edits code.
• 🧹 Junk removed, facts kept. Outdated Markdown is deleted only after a deletion ledger proves where each fact went.
• 🧑‍⚖️ A second agent reviews every commit. A separate, read-only process with a fresh context. Anything but an exact APPROVE blocks the commit.
• 💸 Cost caps built in. Per-call and daily budgets, and a model-free audit that makes quiet nights cost $0.

Quick start

pipx install libraryan     # once per machine
cd your-project            # any git repo, on its default branch
libraryan init             # once per project: installs, builds the KB, commits

That's it. From now on Libraryan updates the docs after your commits and checks them once a day. It commits locally and never pushes. Remove it at any time with libraryan uninstall; the docs stay.

/plugin marketplace add narek-mn/libraryan
/plugin install libraryan@libraryan
/libraryan:init

How it works

flowchart LR
    A["🤖 Other agents<br/>👩‍💻 People"] -- "edit README.md" --> L{{"🔒 Lock<br/>git pre-commit hook<br/>any agent, any editor"}}
    L -- blocked --> A
    A -- "request file" --> Q[".libraryan/requests/"]
    T["⏱ Triggers<br/>commit · daily · manual"] --> R
    Q --> R["📚 Libraryan run<br/>audit → write → checks"]
    R --> G["🧾 Deletion ledger<br/>facts accounted for"]
    G --> V{"🧑‍⚖️ Independent<br/>reviewer"}
    V -- APPROVE --> C["✅ docs(libraryan): commit"]
    V -- anything else --> X["↩ restore + report"]

1. Commit as usual. After a quiet period (10 minutes by default), Libraryan wakes up. A daily run catches anything else.
2. Audit first, for free. A deterministic check finds broken links, paths that no longer exist and notes older than their sources. If there is nothing to do, it stops there without calling a model.
3. Write. Libraryan updates the knowledge base (docs/kb/, with an index.md and a log.md), fixes stale docs, merges duplicates and deletes junk.
4. Gate. Lint, secret scan, deletion ledger, then an independent reviewer. Only fully approved runs are committed, and only Libraryan's own files.
5. Report. Each run leaves a report (.libraryan/state/reports/latest.md) and a trace line with its cost. libraryan stats shows the totals.

See it on a real repo

We built a small weather CLI the way agent-heavy repos really look: a README that documents flags and an env var the code dropped, a second setup guide that disagrees with it, scratch notes, meeting notes, an old to-do list, an empty stub, and one quiet bug in the code. Then we ran libraryan init once. These are the real results:

CHANGELOG-draft.md
CLAUDE.md
README.md          stale flags, wrong env var
NOTES.md
TODO_old.md
meeting-notes-2024.md
docs/ideas.md      empty "TBD"
docs/setup-old.md  disagrees with README

README.md          fixed against the code
AGENTS.md          project rules in one place
CLAUDE.md          -> @AGENTS.md
CHANGELOG-draft.md filled in
docs/kb/
  index.md  log.md
  api-key.md          forecast-days.md
  office-network-ssl.md  owm-api-version.md
  response-cache.md   stdlib-only.md
  units-flag.md

• 5 junk files deleted, no fact lost. The ledger mapped all 10 facts they held to their new homes, with quotes checked mechanically, and named the 2 files that held nothing worth keeping.
• The README was fixed against the code: Python version, the WEATHER_API_KEY env var, the --units/--days/--json flags, and dev setup.
• It caught the code bug we planted and reported it without touching the code: "weather_cli/cache.py:13: get() returns the cached entry only when it is older than the TTL… The check is backwards."
• It flagged a conflict for a human: an old AGENTS.md rule told agents to edit the README directly.
• A later request ("document the new Dockerfile") was applied in 53 s for $0.39. Total for the day: $2.68, 2 commits, 0 failures, and an audit with no findings.

Rebuild the demo yourself: examples/demo.

Why trust it with your docs

Honest limits: Libraryan's own writer and reviewer run through Claude Code today; more runtimes (Codex CLI, Gemini CLI) are planned. Linux and macOS only. The lock is a guardrail, not a security boundary (git commit --no-verify skips it). See Known limits.

Commands

Configuration, reports, upgrade notes and every option are in the guide.

FAQ

Contributing

Issues and PRs are welcome. Start with CONTRIBUTING.md. Report security issues privately (SECURITY.md).

If Libraryan keeps your docs honest, a ⭐ helps others find it.

_{MIT © narek-mn · Changelog}