installation

Installation & Setup

Relevant source files

• README.md
• pyproject.toml

Overview

RepoDocs is distributed as a Python package named repodocs, built with the hatchling backend and requiring Python 3.10+. The project declares dependencies = [], i.e. the core package has zero runtime dependencies beyond the Python standard library.

Sources: pyproject.toml:L1-L12

Two console scripts are registered as entry points: repodocs (repodocs.cli:cli) and repodocs-all (repodocs.cli:cli_all). An optional test extra pulls in pytest>=8.

Sources: pyproject.toml:L17-L22

Quick start (no install)

The fastest path runs the full pipeline directly from the git repository using uvx, requiring no clone and no persistent install:

cd /path/to/project
uvx --from repodocs repodocs-all .

This opens repo-docs/wiki.html when complete. Prerequisites are Python 3.10+, uv, and graphify (uv tool install graphifyy) — or the --no-graph flag to skip graphify. uv itself is installed with curl -LsSf https://astral.sh/uv/install.sh | sh.

Sources: README.md:L41-L53

Persistent tool install

To keep repodocs and repodocs-all permanently on PATH:

uv tool install repodocs
uv tool update-shell
repodocs --version

Sources: README.md:L62-L70

Setup on a new machine

Everything runs locally and is split into two independent parts: the core pipeline (zero runtime dependencies, sufficient to generate a wiki) and an optional diagram tool (adds Bun + Playwright).

Sources: README.md:L77-L82

Core pipeline (required)

Step	Requirement	Command / action
1	Python 3.10+	python3 --version
2	uv	curl -LsSf https://astral.sh/uv/install.sh | sh
3	A backend CLI, logged in	one of Claude Code / OMP / Codex — see below
4	graphify (optional but recommended)	uv tool install graphifyy, or pass --no-graph
5	Internet access	needed for the backend API, graphify, and git

For the backend CLI step:

• Claude Code (default): install claude, run it once, and /login.
• OMP: export REPODOCS_BACKEND=omp, then repodocs setup and omp --profile=repo-docs /login.
• Codex: export REPODOCS_BACKEND=codex, then codex login.

Once set up, run from any repo: uvx --from repodocs repodocs-all . (or clone the repository and run uv run repodocs-all /path/to/project). Output lands in repo-docs/wiki.html.

Sources: README.md:L77-L101

Optional: diagram posters (tools/)

GitHub's mermaid renderer intermittently fails to load in wikis. tools/diagram_poster.ts pre-renders a diagram to a pastel PNG as an alternative. This tool is not part of the zero-dependency core; it requires:

1. Bun — curl -fsSL https://bun.sh/install | bash
2. playwright — cd tools && bun install
3. A Chromium browser — bunx playwright install chromium (downloads ~150 MB the first time)

Rendering: bun tools/diagram_poster.ts tools/example-architecture.yaml --png writes tools/example-architecture.png. The input YAML combines a mermaid block with an editorial shell and can be edited per diagram. To use the output in a GitHub wiki, commit the PNG into the <repo>.wiki.git repository and reference it with ![alt](name.png).

Sources: README.md:L103-L117

Backend selection

REPODOCS_BACKEND selects between claude (default), omp, or codex; REPODOCS_MODEL overrides the model. Each backend runs read-only (read/grep/glob only) with no session persistence. The Claude Code default model is claude-sonnet-5.

Sources: README.md:L130-L138

Upgrading

uv tool upgrade repodocs                                   # if installed as a tool
# or reinstall from git:
uv tool install --force repodocs

Sources: README.md:L164-L170

Build packaging notes

The wheel and sdist build targets both re-include src/repodocs/repo-docs-profile/AGENTS.md via an artifacts override, because it would otherwise be excluded by the unanchored AGENTS.md .gitignore rule; without this, a wheel built from the sdist is missing the vendored file and backend_contract() fails.

Sources: pyproject.toml:L31-L41

Development setup

Checks are run with uv run --extra test pytest -q, which installs the test optional-dependency group (pytest>=8).

Sources: README.md:L178-L181, pyproject.toml:L21-L22