Build1 publisher2 min readPublished
Atomic task claims on disk let several agents document one repo without a human dispatcher
repowiki is an MIT-licensed CLI on PyPI that plans, claims, validates and packages the pages of a repository wiki. It makes no model calls at all, so the reading and writing stay with whichever agent you drive it with.
The Engineer · Build desk

What happened
- repowiki, published on PyPI under the MIT licence, runs the deterministic parts of building a repository wiki through five CLI commands: plan, next --claim, check, finalize and site.
- The CLI makes no model API calls and no network calls, and pyyaml is its only runtime dependency, so no API keys are needed and the code stays on the machine.
- The task catalog, claims and heartbeats sit on disk, which the post says lets multiple agents, processes or people work the same repository at once and resume after an interruption.
- The post lists three failures of pointing an agent at a big repo: the directory tree will not fit one session, crashes reset progress to zero, and nobody coordinates parallel work but you.
- It rejects cloud wiki services such as DeepWiki because the code has to leave the machine, which the author calls an instant veto for companies with confidentiality requirements.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- capability Coordination stops being a person's job: workers pull tasks from the file system, so adding a second agent means starting a second process.
- decision A team that cannot send source offsite has two options. Run a local orchestrator with the wiki in the working tree, or accept per-use billing and output that never reaches code review.
- constraint Drift stays a scheduling problem for humans, because determinism fixes who writes which page and not when the pages get rebuilt.
The command to read closely is `next --claim`. A worker claims the next task from the catalog atomically, so two agents started in two terminals do not take the same page, according to the author's post [4]. No model is involved in that step: it needs a lock, a file, and somebody to have thought about what happens when a process dies mid-page. Heartbeat files in a work directory are one of the older tricks in job scheduling.
`check` sorts defects into two piles. Anchors, line numbers, H1 headings and paths are auto-repaired, and only semantic defects go back to the agent [5]. Templates force a section skeleton before any of that [10]. I would automate that class of error first. A line number goes stale on the next commit whether the prose was good or not, and buying another model call to correct an integer is poor value.
None of this lowers the model bill. Every token spent reading code and writing pages is billed by whichever agent CLI you point at the repo, because the tool itself does no inference [18]. What you stop paying for is the second pass over a repo you already documented once and then lost to a dead session, the failure the post puts second on its list [11].
"The agent supplies the intelligence; repowiki supplies the reliability," the author wrote [15]. He calls the result "a build system that generates a structured wiki for any repository" [16]. He also rejected the IDE route: built-ins bill in credits, keep the wiki in the tool's own directory where CI cannot see it, and Qoder Repo Wiki caps a project at 10,000 files [14]. That 10,000-file figure is the only size number in the post. It bounds a competitor's ingestion limit and predicts nothing about how repowiki's planner behaves on a tree that large. For the comparison to carry, you would want page counts and `check` rejection rates from a repo of tens of thousands of files, which the post does not report.
The pipeline ends at `site`, which packages a self-contained offline HTML file of about 5 MB [7], after `finalize` assembles the overview page and an llms.txt index [6]. Refreshing the wiki after the code moves means running `plan` again, and scheduling that is left to the team. The fourth problem the post names is docs that nobody trusts three months later [12]. Wiki state lives inside the repository tree [8], so a page that has drifted turns up in a diff. The post's complaint about cloud-hosted wikis is that they sit outside git with no version history to review [13].
What to watch
- Whether a later release adds incremental re-planning after commits, and what it keys on: file hashes, git diff, or a manual plan run.
- Whether anyone publishes run data from a repo of tens of thousands of files: pages produced, tokens spent, and the share of pages check rejects.
- How the claim protocol handles a worker that dies holding a claim, since heartbeats are on disk but the reclaim rule is not described.