selfdocs

Drafts five architecture docs from a repo with your local claude CLI. Your notes survive every regeneration.

The problem

Architecture docs go stale because regenerating them throws away the one thing worth keeping: the note someone wrote about why express is pinned to 4.x. selfdocs splits each doc into anchored blocks and pins your notes to them, so a regeneration updates the draft and leaves your notes where you put them.

Matt Waite, founder

Get it

npx @excellent-so/selfdocs build --mock

Source on GitHub Package on npm

Version 0.1.0 · MIT license

Quick start

# in the repo you want documented
npx @excellent-so/selfdocs build --mock   # draft all five docs, offline
npx @excellent-so/selfdocs open           # the viewer, http://127.0.0.1:4630

# with the claude CLI installed and signed in
npx @excellent-so/selfdocs build --type=architecture   # one doc first
npx @excellent-so/selfdocs build                       # all five

How to use it

In the repo you want documented, run npx @excellent-so/selfdocs build --mock. It needs Node 20 or later and nothing else.
Run npx @excellent-so/selfdocs open, read each doc and add a note under any paragraph, list, table or code block.
Install the claude CLI and sign in, then build without --mock to have the model write the docs. Start with one: --type=architecture.
Build again whenever the code moves. The draft changes and your notes stay where you put them.

Where it came from

In November 2023 I asked Cursor whether it could generate a readme or a compressed outline of a codebase to give prompts context, because chatting with a codebase never really worked for me. In July 2026 I built it.

Each doc is one call to the model through your claude CLI, plus up to two more if its markdown needs repair. On a small Express app, one doc took under a minute and all five took about five minutes.

The same split runs through Excellent: the agent does the work, and something else checks it before you rely on it. excellent.so