configuration

Now I have everything needed to write the page.

Environment Configuration

Relevant source files

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

Overview

RepoDocs dispatches every LLM call — planning, page generation, translation — through a single configured backend CLI. Four environment variables control which backend runs, which model it uses, how long a subprocess is allowed to run, and how many pages are generated concurrently. src/repodocs/backend.py reads all four directly from os.environ at call time; there is no config file.

Sources: src/repodocs/backend.py:L1-L32, src/repodocs/cli.py:L32-L40

Variable reference

Variable	Default	Valid values	Effect
REPODOCS_BACKEND	claude	omp, claude, codex	Selects the LLM CLI dispatched by run_llm
REPODOCS_MODEL	unset	any model id	Overrides the model passed to the selected backend
REPODOCS_TIMEOUT	600	seconds (int)	Per-subprocess timeout for each LLM call
REPODOCS_JOBS	4	1-16	Worker count for parallel page generation/translation

Sources: src/repodocs/cli.py:L32-L36, src/repodocs/backend.py:L26-L50, src/repodocs/backend.py:L120-L205

REPODOCS_BACKEND

backend_name() reads REPODOCS_BACKEND, strips and lowercases it, and defaults to "claude" when unset. It validates the value against BACKENDS = {"omp", "claude", "codex"} and raises ValueError for anything else; require_backend() wraps this and calls die() on invalid input, exiting with status 2.

def backend_name() -> str:
    name = os.environ.get("REPODOCS_BACKEND", "claude").strip().lower()
    if name not in BACKENDS:
        raise ValueError(...)
    return name

Each value maps to a distinct code path in run_llm:

• omp — invokes the omp CLI with --profile=repo-docs, the vendored isolation.yml config, --tools=read,grep,glob, and --approval-mode=write. Requires repodocs setup to have installed the profile first.
• claude — invokes claude -p --safe-mode --no-session-persistence --permission-mode dontAsk --tools Read,Grep,Glob, piping the prompt via stdin with cwd=repo.
• codex — invokes codex exec --ephemeral --sandbox read-only inside a temp dir with a symlinked read-only view of the repo, plus a one-time stderr warning that the sandbox restricts writes but not reads.

Sources: src/repodocs/backend.py:L14-L32, src/repodocs/backend.py:L120-L179, src/repodocs/cli.py:L185-L190

REPODOCS_MODEL

effective_model() gives REPODOCS_MODEL unconditional priority: if set, its value is passed straight through regardless of backend. Otherwise, only the claude backend gets an implicit default — DEFAULT_CLAUDE_MODEL = "claude-sonnet-5" — while omp and codex fall back to None, letting their own CLI defaults apply.

def effective_model(backend: str | None = None) -> str | None:
    explicit = os.environ.get("REPODOCS_MODEL")
    if explicit:
        return explicit
    if backend is None:
        backend = backend_name()
    return DEFAULT_CLAUDE_MODEL if backend == "claude" else None

llm_label() uses this to render a human-readable string like claude/claude-sonnet-5 or omp default model for status output.

Sources: src/repodocs/backend.py:L17-L18, src/repodocs/backend.py:L42-L50, src/repodocs/backend.py:L78-L81

REPODOCS_TIMEOUT

run_llm reads REPODOCS_TIMEOUT as an integer, defaulting to 600 seconds, and passes it as the timeout= argument to every subprocess.run call for all three backends. On expiry the caller (e.g. generate.py, translate.py) reports a per-page timeout and suggests raising this variable rather than the pipeline failing outright.

timeout = int(os.environ.get("REPODOCS_TIMEOUT", "600"))

Sources: src/repodocs/backend.py:L120-L150

REPODOCS_JOBS

jobs_count() parses REPODOCS_JOBS as an integer (defaulting to 4, and also falling back to 4 on a ValueError from a non-numeric value), then clamps the result to the inclusive range 1..16 with max(1, min(16, n)). parallel_llm uses this as max_workers for a ThreadPoolExecutor that fans run_llm calls out over (key, prompt) items; setting REPODOCS_JOBS=1 forces effectively serial execution.

def jobs_count() -> int:
    try:
        n = int(os.environ.get("REPODOCS_JOBS", "4"))
    except ValueError:
        n = 4
    return max(1, min(16, n))

Sources: src/repodocs/backend.py:L182-L205

Usage summary

README.md documents the same four variables for end users, describing REPODOCS_BACKEND/REPODOCS_MODEL under "Choose an LLM backend" and REPODOCS_JOBS/REPODOCS_TIMEOUT under "Pipeline commands"; the CLI's own module docstring (surfaced by repodocs help) repeats the same defaults inline.

Sources: README.md:L130-L154, src/repodocs/cli.py:L32-L40