ai-doc-gen: five concurrent analysis agents that write your README and your CLAUDE.md

The problem it targets: documentation that goes stale between releases

Documentation drifts because writing it is a separate task from changing code. The README describes an architecture that was refactored two quarters ago, CLAUDE.md and .cursor/rules/ get written once by whoever set up the AI assistant, and new engineers read all of it before touching the repository. ai-doc-gen attacks this by making documentation a derived artifact: the repository is the input, and README.md plus the AI assistant configuration files are outputs that can be regenerated. The intended user is a team maintaining many repositories, not a solo developer with one project. The GitLab cronjob mode makes that explicit: it discovers recently active projects, runs analysis against them, and opens merge requests with the results, with --max-days-since-last-commit controlling how far back the discovery window reaches. That is a fleet-level tool. The README also positions it for developer onboarding, which is the same problem seen from the reader's side.

Five analysis agents, concurrent execution, and what lands in .ai/docs/

The pipeline has two stages. In the first, five specialized agents run concurrently and each writes a reusable analysis document into .ai/docs/: code structure, data flow, dependencies, request flow, and APIs. These are the intermediate artifacts, and they are the part worth inspecting, because every generated file downstream is a transformation of them. In the second stage, generation agents turn those analyses into README.md and into CLAUDE.md, AGENTS.md and .cursor/rules/*.mdc. Concurrency is bounded by a worker pool: analyzer.max_workers caps concurrent analyzer agents, and 0 means auto-detect CPU count. The same limit is reachable from the CLI as --max-workers. Individual analyses can be switched off, which matters for cost and for accuracy: --exclude-code-structure and --exclude-data-flow are documented examples, and the configuration file exposes the same toggles. Because the analyses are separate agents rather than one prompt, a repository whose request flow is trivial can skip that agent entirely instead of paying for a model to guess at it.

Getting it running: uv, .env, .ai/config.yaml, and three commands

The documented path assumes Python 3.13, Git, and API access to an OpenAI-compatible provider. Clone the repository, then either install uv and run uv sync or install with pip install -e . The README recommends uv. Configuration is layered, and the precedence is stated plainly: Pydantic defaults, then .ai/config.yaml, then CLI flags. In practice that means copying two files: cp .env.sample .env for API keys and base URLs, and cp config_example.yaml .ai/config.yaml for behaviour. The tool looks for .ai/config.yaml or .ai/config.yml in the repository, so a per-repository config is the normal arrangement. Three commands cover the main work: uv run src/main.py analyze --repo-path ., uv run src/main.py generate readme --repo-path ., and uv run src/main.py generate ai-rules --repo-path .. The package also installs an ai-doc-gen console script exposing the same CLI, so the uv run prefix is a convenience rather than a requirement. Generation has its own flags: --exclude-architecture and --exclude-c4-model for README sections, --use-existing-readme to feed the current README in as context, and for AI rules --skip-existing-claude-md, --skip-existing-agents-md, --skip-existing-cursor-rules, --detail-level, --max-claude-lines and --max-agents-lines. A Dockerfile and a Helm chart under k8s/helm/ exist for containerized and scheduled Kubernetes CronJob deployments.

The Claude Code plugin path asks for no API key at all

The repository doubles as a Claude Code plugin, and this is the lowest-friction entry point because it requires no Python setup and no API keys. Two commands install it from inside Claude Code: /plugin marketplace add divar-ir/ai-doc-gen and /plugin install ai-doc-gen@divar. That exposes three skills, analyze-codebase, generate-readme and generate-ai-rules, which Claude Code invokes directly. The trade-off is control. The Python CLI gives you per-agent model and endpoint settings, an exclusion list, a worker count and a config file. The plugin path gives you the skills and whatever the host assistant decides to do with them. If your reason for using the tool is that you want a local model or a specific gateway handling one analysis and a different model handling another, the plugin route is not the one you want. If your reason is that you want a README draft now without provisioning anything, it is.

Where it breaks: hallucinated APIs, cost, and the wrong-repository case

The tool generates prose about code using a language model. Nothing in the README claims it validates generated statements against the source, and there is no described verification pass between the analysis documents and the generated README. So the failure mode to plan for is a confidently described function, endpoint or data flow that does not exist, produced because the model filled a gap the analysis left open. The mitigations the project does offer are structural rather than factual: you can exclude an analysis you know the model handles badly, and you can inspect .ai/docs/ before generating anything. The GitLab cronjob mode makes this sharper, because it opens merge requests across discovered projects without a human in the loop at generation time. Cost is the second constraint. Five concurrent agents plus generation agents means one run is many model calls, and concurrency controls throughput, not spend. Finally, this is the wrong tool for a repository where the documentation is the product, such as a public SDK whose reference pages must be exactly right. A generator that drafts is not a generator that certifies.

Compared with CI-integrated doc generators such as Sphinx or MkDocs

Sphinx and MkDocs solve an adjacent problem with a different mechanism. They render documentation from source files that a human writes, so the output is only as current as the last commit to the docs directory, and their build is deterministic: the same input produces the same HTML. ai-doc-gen writes the source text itself, which removes the writing step but introduces model variance, since the same repository analyzed twice can yield different prose. The two approaches compose rather than compete. If your team already has a docs directory and a build pipeline, ai-doc-gen is a way to seed that directory, not a replacement for the renderer. If you have no docs directory and no appetite for creating one, ai-doc-gen's output is Markdown in the repository root, which is the simpler artifact. The relevant question is whether you want a deterministic build over human-written text or a probabilistic draft over machine-read code. Those are different guarantees, and only the first one is a guarantee.

Maintenance cost, licence, and what the release history does not tell you

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive and imposes no copyleft obligation on your repository; it also means no warranty, so correctness of generated documentation is your problem, not the maintainers'. On maintenance, the honest position is that the material does not support an assessment. No releases were retrieved, so there is no changelog to read for breaking changes in the CLI flags or the .ai/config.yaml schema, and no version to pin against. The last push date is recent, which indicates activity, but activity is not the same as a stable interface. The practical consequence is that you should treat the CLI surface as moving. Pin whatever you install, whether that is a commit hash from the clone or a version from the package index, and re-read .ai/config.yaml against config_example.yaml after any upgrade, because the layered precedence means a renamed key fails silently back to the Pydantic default rather than erroring.

Editorial conclusion

Adopt ai-doc-gen if you already pay for an OpenAI-compatible endpoint and want a first draft of README.md, CLAUDE.md, AGENTS.md and .cursor/rules/ produced from the same five analyses, especially if your repositories live in GitLab and you want merge requests opened for you. Do not adopt it if you need guaranteed accuracy on public API documentation or if you cannot send source code to an external model. Before rolling it out, run uv run src/main.py analyze --repo-path . on one repository and read .ai/docs/ yourself: if the structure and API analysis are wrong there, the generated README will be wrong in the same way, and the cronjob mode will replicate that error across every project it discovers.

Official sources

1. divar-ir/ai-doc-gen on GitHub
2. Issues
3. License: MIT
4. README