Documentation lies. Not on purpose β it just stops being true.
You rename a function. You add a required parameter. You retire that env var that never should have existed. And somewhere in your docs, the old name is still there. The old signature. The old example that will throw an error if anyone actually runs it.
It will stay there until someone files a bug. Or a new hire wastes a morning. Or a customer's integration breaks.
The problem isn't that developers don't care about docs. It's that keeping them accurate is invisible work β no CI check, no compiler error, no test failure. Docs rot in silence.
What I built
living-docs is a Claude Code plugin that fixes the feedback loop.
After you make code changes, run /living-docs. It:
- Diffs your code since the last commit
- Extracts semantic markers β function names, parameters, env vars, CLI flags, config keys, API endpoints
- Finds every doc file that references them
- Compares what the doc says vs what the code now does
- Shows you exactly what's wrong, with a proposed fix
- Applies surgical edits to only the stale lines
Here's what the output looks like after renaming an env var and adding a parameter to a function:
Scanning docs against changes since HEAD~1...
STALE docs/api.md 2 issues
STALE docs/configuration.md 1 issue
STALE src/auth.ts (JSDoc) 1 issue
OK README.md
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
docs/api.md Β· line 112
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
TYPE outdated signature
CHANGED authenticate(token) β authenticate(token, options?)
WAS: authenticate(token) - Validates a JWT
NOW: authenticate(token, options?)
options.strict β Reject tokens missing exp. Default: false.
options.audience β Validate aud claim. Default: not checked.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
docs/configuration.md Β· line 58
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
TYPE renamed env var
CHANGED AUTH_SECRET β AUTH_SIGNING_KEY
Apply all 4 fixes? [Y/n/select]
What it catches
| Code change | What gets flagged |
|---|---|
| Function signature changed | Every doc showing the old signature |
| Parameter added or removed | README examples, API references, docstrings |
| Env var renamed | Every mention of the old name |
| CLI flag renamed | Help text, quickstart guides |
| API endpoint moved | OpenAPI specs, integration guides |
| New public export | Missing documentation |
Supported formats: Markdown, JSDoc/TSDoc, Python docstrings, Go doc comments, OpenAPI/Swagger, reStructuredText.
The important detail
It doesn't rewrite your docs. It makes targeted edits to exactly the lines that are wrong.
Your formatting, your wording, your structure β all untouched. If you say no at the confirmation prompt, nothing changes.
Install
curl -fsSL https://raw.githubusercontent.com/phlx0/living-docs/main/scripts/install.sh | sh
Add to ~/.claude/settings.json:
{ "plugins": ["~/.claude/plugins/living-docs"] }
Then run /living-docs in Claude Code.
CI integration
Block PRs with stale docs:
- name: Check for stale docs
run: |
claude --print "/living-docs --dry-run --since origin/main" \
| grep -q "All docs up to date" || exit 1
Links
- GitHub: https://github.com/phlx0/living-docs
- Install: one curl command above
- Issues / PRs welcome













