Home

Overview

Relevant source files

• README.md
• src/repodocs/init.py
• src/repodocs/cli.py

What RepoDocs is

RepoDocs is a local, DeepWiki/cubic.dev-style repository documentation generator: it scans a codebase deterministically, drives a coding-agent CLI backend to plan feature-level wiki pages, and writes Markdown pages where every claim is cited to a specific file and line range. The end product is a self-contained wiki.html that can be opened offline in a browser.

Sources: README.md:L16-L26

The package has zero runtime dependencies (Python stdlib only) and version 0.1.0 is declared in src/repodocs/__init__.py.

Sources: src/repodocs/init.py:L1-L3, README.md:L9-L9

Goals and non-goals

RepoDocs positions itself against hosted DeepWiki/cubic-style tools: it runs entirely on the user's machine, keeps private repos from ever being uploaded, has no runtime dependencies, cites every claim to file:line, and produces an offline wiki.html the user owns, generated via the user's own Claude Code / OMP / Codex login rather than a hosted model.

Sources: README.md:L76-L86

Explicitly, RepoDocs does not host generated wikis, replace source-code review, guarantee output is safe to publish without human review, or manage credentials for the agent CLIs it shells out to.

Sources: README.md:L129-L133

The pipeline: scan → plan → generate → html → publish

The module docstring in src/repodocs/cli.py lays out the pipeline stages directly:

Stage	Purpose
scan	Deterministic inventory of the repo: source files, manifests, README headings, tests, CI, CHANGELOG
plan	An LLM planner turns the inventory into a feature-level page list, written to plan.json
generate	One LLM writer call per planned page, with SHA-256 incremental rebuilds
translate	Translate generated pages to another language (optional)
html	Bundle pages into a self-contained wiki.html viewer
publish	Push the built wiki to a GitHub Pages branch
publish-wiki	Export generated pages to the repo's GitHub Wiki
all	graphify + scan + plan + generate + vendored html, in one command

Sources: src/repodocs/cli.py:L1-L28

flowchart LR
    A[graphify update] --> B[scan]
    B --> C[plan]
    C --> D[generate]
    D --> E[translate optional]
    D --> F[html]
    E --> F
    F --> G[publish / publish-wiki]

Loading

cmd_all in cli.py implements this exact sequence for the repodocs all / repodocs-all entry point: it optionally runs graphify update (unless --no-graph is passed, in which case graphify is required to be on PATH or the command dies), then calls cmd_scan, llm_plan, cmd_generate, and finally build_html(..., vendor=True).

Sources: src/repodocs/cli.py:L234-L260

Command-line surface

main() dispatches on argv[0] to one handler per subcommand: scan, plan, generate, html, translate, publish, publish-wiki, all, setup, plus help/-h/--help and --version. A bare invocation with no arguments prints the module docstring (usage) rather than raising. Two console scripts are installed: repodocs (via cli()) and repodocs-all (via cli_all(), which prepends "all" to sys.argv and dispatches into the same main()).

Sources: src/repodocs/cli.py:L397-L435

Each subcommand handler (e.g. cmd_scan, cmd_plan, cmd_generate_cli, cmd_html, cmd_translate_cli, cmd_publish_cli, cmd_publish_wiki_cli) checks for --help/-h first and prints a dedicated help string (SCAN_HELP, PLAN_HELP, GEN_HELP, etc.) before parsing the repo path and flags via parse_repo_and_flags and get_flag.

Sources: src/repodocs/cli.py:L293-L395

LLM backend configuration

RepoDocs delegates planning and generation to a configurable backend rather than calling any model API directly. REPODOCS_BACKEND selects claude (default), omp, or codex; REPODOCS_MODEL overrides the model id (claude-sonnet-5 is the default for the claude backend); REPODOCS_TIMEOUT (default 600s) bounds each subprocess call; REPODOCS_JOBS (1–16, default 4) controls page-generation parallelism.

Sources: src/repodocs/cli.py:L30-L42, README.md:L87-L96

OMP uses a vendored repo-docs profile installed by repodocs setup; Claude Code and Codex are handed the same vendored output contract explicitly, so the page format and citation rules do not depend on files present in the target repository.

Sources: src/repodocs/cli.py:L36-L38

If the planner is unavailable or returns invalid output, RepoDocs falls back to a deterministic heuristic plan rather than failing.

Sources: src/repodocs/cli.py:L40-L41, README.md:L79-L79

Publishing safety

Both publish (GitHub Pages) and publish-wiki (GitHub Wiki export) stage output in a temporary worktree, scan it for private-key/token/API-key patterns, and require an explicit --allow-public flag for a real push; --dry-run is the recommended first step before either. publish refuses to target main/master/trunk.

Sources: README.md:L113-L119

Quick start

The documented entry point for trying RepoDocs without installing it is uvx --from git+https://github.com/aryrabelo/repodocs repodocs-all ., run from the target repository; the result is opened as repo-docs/wiki.html in a browser. Persistent installation uses uv tool install git+https://github.com/aryrabelo/repodocs.

Sources: README.md:L40-L69