llmdoc: persistent engineering context for coding agents

The problem llmdoc targets: agents rediscovering architecture every session

A coding agent starting a session on an unfamiliar repository has to rebuild a mental model from source. That works, but it is repeated work, and it produces different answers on different days. The README frames the project around three claims: preserve decisions, constraints and cross-module contracts that source code does not explain cheaply; retrieve only the context a task needs and then verify exact facts against the live repository; and recheck knowledge semantically as code evolves rather than accumulating stale implementation notes. The intended user is a team running a coding agent inside a real repository, not someone looking for generated API reference. The distinction matters because llmdoc/ is described as storing durable engineering meaning, not a copy of the repository. If your pain is that nobody wrote down why a module boundary exists, this is aimed at you. If your pain is that your README is out of date, it is not.

The retrieval and verification loop behind llmdoc/

The README gives a four-stage flow: stable knowledge in llmdoc/ feeds task-scoped retrieval, retrieval feeds source verification, verification feeds semantic maintenance, and maintenance feeds back into the knowledge store. The important part is the middle. An agent first retrieves the smallest useful knowledge set, then uses source and tests for current facts, and only later verifies affected knowledge. A code change creates a review obligation rather than an automatic documentation rewrite. That is a deliberate refusal to auto-generate prose from diffs, and it is the design choice most likely to divide readers. The project splits responsibilities into two layers: agent workflows own judgment and safe closeout and are invoked through the host's command or skill interface, while the runtime CLI owns retrieval and deterministic mechanics and is called directly or from a workflow. The four workflows are explicitly not equivalent CLI commands. init creates a small V3 knowledge surface when none exists, update semantically verifies affected knowledge and can record unchanged documents as verified without inventing prose changes, prune reduces duplicate or cheaply reconstructable knowledge with the CLI supplying only a read-only report, and upgrade migrates legacy or V2 knowledge and runs only when the user explicitly asks for it. Every explicit workflow reports exactly one result state: success, no_change, dry_run, incomplete, or failed.

Routing a task to the right llmdoc command

The README defines a routing gate to apply before broad exploration and again when entering a new subsystem. A concept, contract, term or where-is-X question goes to search <query>. Context for concrete source files goes to context --files <path...>. A cold start or unclear scope goes to tree. A known topic or kind goes to index --topic <topic> or index --kind <kind>. Bodies that have already been identified go to show <path...>. These are alternatives, not a fixed sequence, and once llmdoc narrows the working set, native tools handle exact source text, line numbers, test behavior, counts and Git state. One detail worth noting for anyone wiring this into a script: context --files evaluates every input independently and reports unmappedFiles, and a non-empty impacted set never hides unmapped siblings. status and delta assess validity and impact and are explicitly not retrieval steps.

Installing llmdoc for Claude Code or Codex

Requirements are Node.js 18 or newer and a Git repository. For Claude Code, the README gives two commands: /plugin marketplace add TokenRollAI/llmdoc, then /plugin install llmdoc@llmdoc-plugin. If the install summary says Run /reload-plugins to activate., run that; if the reload warns about rereading the conversation, rerun it as /reload-plugins --force. Then initialize with /llmdoc:init. For Codex, add the marketplace with codex plugin marketplace add TokenRollAI/llmdoc, start codex, run /plugins, open the llmdoc-plugin marketplace and install llmdoc. The README advises reviewing the plugin and its hooks before enabling them, then starting a new Codex session and asking it to use the llmdoc:init skill. If the repository already has llmdoc/, no plugin is needed: npx -y @tokenroll/llmdoc tree and npx -y @tokenroll/llmdoc search "revision" work directly. The README is firm that @tokenroll/llmdoc is external tooling, must not be added to the consumer project's package.json or lockfile, and that the unrelated bare name npx llmdoc must never be used. For reproducible runs it recommends pinning: npx -y @tokenroll/llmdoc@<version> <command>. Other documented commands include tree --docs, search with --limit, context --files, show with multiple document paths, and serve for local browsing. Plugin lifecycle hooks invoke the same scoped CLI through an npm package alias so a same-name local or file: dependency without a built bin cannot shadow the hook runtime.

Startup preload and the llmdoc.config.json contract

Repositories using the lifecycle hooks can add an optional llmdoc.config.json at the llmdoc workspace root, which in a Git repository is the nearest Git root that owns llmdoc/. The schema is llmdoc.config/v1 with a $schema pointer at llmdoc.tokenroll.ai. Two keys are documented. remindSkill controls SessionStart operating guidance (load the llmdoc skill, use the CLI retrieval gate, delegate to the llmdoc roles); it defaults to true and can be set to false to opt out. preload lists exact document IDs with an optional llmdoc/ prefix, and cold SessionStart inserts their bodies directly in the listed order with no character or token budget. A final completion marker confirms the host supplied the full preload; without it, the missing body should be retrieved with show. Compact re-entry lists configured document IDs but does not inject full bodies again, continuing from LLMDOC_STATE instead. validate reports malformed config, missing paths and path escapes, and deduplicates normalized aliases of the same document with a warning. Lifecycle hooks stay fail-open: unreadable schema or JSON falls back to the default reminder, while a valid remindSkill choice survives preload-only errors. mv rewrites matching preload paths transactionally, and prune --report lists preload references that must be updated before a manual merge or deletion. Without the file, SessionStart emits its state plus default guidance and preloads nothing.

Where llmdoc is the wrong tool

The no-budget preload is the sharpest constraint in the material. Because cold SessionStart inserts listed document bodies with no character or token budget, a long preload list spends context before the agent has read the task. The docs offer no trimming mechanism beyond choosing shorter documents. The second limitation is the licence. The repository metadata supplied here has no licence field, and the README does not name one, so anyone embedding llmdoc in a commercial workflow should treat licensing as unresolved until they check the repository directly. Third, the workflow split is narrow by design. update can record unchanged documents as verified without writing prose, which means the knowledge surface will not grow on its own; if your team expects documentation to accrete from code changes, this is the wrong model. Fourth, the plugin path assumes a host with hooks and a marketplace. There is a CLI-only path for an existing llmdoc/ workspace, but init, update and prune are described as workflows invoked through the host's command or skill interface, so a plain terminal user without Claude Code or Codex is working with the retrieval half of the tool. Finally, the README states that fixed CLI interface text is English, including help, diagnostics, hook messages and the local Viewer, while Chinese queries and repository document content remain supported. Teams expecting a localized interface should plan around that.

How llmdoc differs from generated documentation and from memory files

The nearest alternative is the pattern of a hand-maintained agent instruction file, or documentation generated from source by a doc tool. Both differ from llmdoc in the same direction: they either produce a single flat file that every session reads in full, or they regenerate prose from code. llmdoc instead stores knowledge as addressable documents under llmdoc/ with a retrieval layer in front of them, so the agent pulls search results, file-scoped context, or a specific body rather than the whole store. The verification step is the other separation. A generated doc pipeline treats the code as the source of truth and overwrites; llmdoc treats the code as the place to check facts and treats the knowledge document as something a human or agent must re-verify, with unchanged documents recorded as verified rather than rewritten. That is more discipline than generation, and less automation. The trade is explicit: you keep decisions that source cannot express, and you accept that keeping them current is a review obligation rather than a build step.

Editorial conclusion

Adopt llmdoc if your repository already carries decisions that source code does not explain cheaply and your team runs Claude Code or Codex with hooks enabled. Do not adopt it as a general documentation generator, and do not run upgrade unless someone explicitly asks for a V2 migration. Before installing, check three things: the licence, since the repository metadata has no licence field; the exact version you will pin with npx -y @tokenroll/llmdoc@<version>; and whether llmdoc.config.json preload entries match real document IDs, which validate will report as missing paths.

Official sources

1. Issues
2. README
3. Releases
4. TokenRollAI/llmdoc on GitHub