autoreadme-ai 0.1.0

Generate and maintain README files for Python repositories from static analysis.

AutoReadme

Generate and maintain a README for your Python repo from static analysis — no source code ever leaves your machine.

uvx --from 'autoreadme-ai' autoreadme .

AutoReadme walks your repo with the stdlib ast module, extracts structured metadata (signatures, docstrings, project config, CLI parsers), and sends only that metadata to an LLM to write prose. The payload schema has no field for function bodies, so source code transmission isn't prevented by policy — it's prevented by the shape of the data.

Installation

uv tool install autoreadme-ai[anthropic,openai]

Install the tool as a command-line application using uv. The extras include optional dependencies for Anthropic and OpenAI providers. For one-shot usage without persistent installation, use uvx autoreadme-ai[all]. You can also install with pipx install autoreadme-ai[all] or pip install autoreadme-ai.

Quick start

export ANTHROPIC_API_KEY=sk-...
autoreadme .

That's the whole flow: extract → pre-flight token check → single LLM call → colored diff → approve (Y/n/d/q) → write with .bak backup.

Preview without writing:

autoreadme --dry-run

Inspect exactly what would be sent to the LLM (no network call):

autoreadme --show-payload

How it protects your code

Three layers:

1. Schema. RepoMetadata, FileMetadata, FunctionSignature etc. have no body / source / raw field. There is no code path that can attach one.
2. Pre-flight disclosure. Before every LLM call, stderr shows exactly how many KB are about to leave your machine and where they're going:

   → Sending 14KB of structured metadata to anthropic (claude-sonnet-4-...).
     No source code included.
   

3. --show-payload. Dumps the full JSON to stdout and exits without making the call. Diff it, grep it, paste it into an issue.

Secret files (.env*, *.key, *.pem, credentials.*) are unconditionally excluded from extraction regardless of config.

Staying in sync

Generated sections are wrapped in HTML comment markers:

<!-- autoreadme:install:start -->
(generated content)
<!-- autoreadme:install:end -->

## Docker Setup
(your content — never touched)

On subsequent runs, only content between markers is replaced. Manual sections between, before, or after markers are preserved verbatim.

Providers

Provider	Default model	Env var
anthropic	claude-sonnet-4-20250514	ANTHROPIC_API_KEY
openai	gpt-4o	OPENAI_API_KEY
ollama	llama3.1	OLLAMA_HOST

If no --provider is set, AutoReadme picks the one whose env var is populated. Override the model with --model or .autoreadme.toml.

Config file

Drop .autoreadme.toml at your repo root:

[llm]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

[extract]
exclude = ["tests/**", "docs/**"]

Resolution precedence: CLI flags > .autoreadme.toml > env vars > defaults.

GitHub Action

- uses: atharvakadam/autoreadme-ai@v1
  with:
    provider: anthropic
    api-key: ${{ secrets.ANTHROPIC_API_KEY }}

The action runs with --force (non-interactive). Pair it with a PR-opening step if you want review before merge.

CLI Reference

autoreadme [PATH] [OPTIONS]

Arguments:

• PATH - Path to the repo root (default: .)

Options:

• --provider - LLM provider: anthropic | openai | ollama
• --model - Model override
• --dry-run - Write result to stdout instead of disk
• --force - Apply without interactive approval
• --show-payload - Dump JSON payload to stdout and exit
• --verbose - Verbose log output
• --output - Output path (default:
• --version - Print version and exit

Exit codes: 0 success · 1 user rejected diff · 2 config/usage/non-TTY · 3 extraction failed · 4 LLM failed.

Scope

v0.1 is deliberately narrow. No monorepo handling, no section-level approval, no custom prompt templates, no non-Python languages, no telemetry. See SPEC.md §15 for the full non-goals list and §16 for the v0.2 plan.

Contributing

See CONTRIBUTING.md. TL;DR: uv sync --all-extras, then uv run pytest / uv run ruff check / uv run mypy src/ before opening a PR.

License

MIT — see LICENSE.