🩺 RepoDoctor

A read-only health check for your repository — leaked secrets, code quality and project structure, in one command.

made by daamles

RepoDoctor scans a project and tells you what you would rather find before git push does: API keys sitting in source files, forgotten FIXME notes, oversized files and code that has grown hard to review. It works from the terminal, in CI, and as an MCP server so Claude can analyse your repositories for you.

╭─ RepoDoctor v0.1.0 ──────────────────────╮
│ Target  demo-shop                        │
│ Mode    read-only · .gitignore respected │
╰──────────────────────── made by daamles ─╯

Findings
 Level   Rule                     Location              Message
 ─────────────────────────────────────────────────────────────────────────────────────
 ERROR   RD005 hardcoded-secret   app/main.py:3         Possible AWS access key ID: AK********LK
 ERROR   RD005 hardcoded-secret   public/payment.js:1   Possible Stripe live key: sk_l********Xa9S
 WARN    RD004 long-file          app/legacy.py         File has 1200 lines (limit 1000); consider…
 WARN    RD002 todo-comment       includes/db.php:3     FIXME: query built by string concatenation…
 INFO    RD002 todo-comment       app/main.py:7         TODO: validate the cart before charging

• Scanned 7 files (1.2 MB) in 0.02s · 1 dir pruned · 2 files ignored by .gitignore
✖ 3 errors · 4 warnings · 3 info

Full examples: terminal output · Markdown report · JSON report

Why RepoDoctor

• Safe by design. It never executes, imports or modifies the code it scans.

• Finds real problems. Committed credentials are the most damaging mistake in public repositories; RepoDoctor catches them and masks every value in its output, so its own reports are safe to share.

• Low noise. Respects .gitignore, skips binaries and minified bundles, filters placeholders like your_api_key_here, and only reports work markers that are actually in comments.

• Fits your workflow. Rich terminal report, JSON for tooling, Markdown for pull requests, exit codes for CI, and MCP tools for AI assistants.

• Small. Two runtime dependencies (Typer, Rich); MCP support is optional.

Related MCP server: github-analyzer-mcp

Safety guarantees

These are part of the contract and are covered by tests:

Installation

Requires Python 3.11 or newer.

# From GitHub
pip install "git+https://github.com/daamles/repodoctor.git"

# With MCP server support
pip install "repodoctor[mcp] @ git+https://github.com/daamles/repodoctor.git"

From a local clone (recommended for development):

git clone https://github.com/daamles/repodoctor.git
cd repodoctor
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Usage

repodoctor scan .                         # scan the current directory
repodoctor scan path/to/project --top 10  # list the 10 largest files
repodoctor scan . -o report.md            # also write a Markdown report
repodoctor scan . -f json > report.json   # JSON to stdout (pipe-friendly)
repodoctor rules                          # list all rules

scan options

Exit codes

Use it in GitHub Actions

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
- run: pip install "git+https://github.com/daamles/repodoctor.git"
- run: repodoctor scan . --fail-on error --output repodoctor-report.md

Rules

Line-based rules apply to Python, PHP and JavaScript and skip minified files (*.min.js). In other text files such as Markdown, work markers are reported anywhere on the line.

Secret detection

Known formats are reported as errors:

• AWS access key IDs, GitHub tokens (classic and fine-grained), Stripe live keys, Slack tokens, Google API keys, OpenAI and Anthropic API keys

• Private key blocks (BEGIN … PRIVATE KEY)

• Passwords embedded in database URLs (PostgreSQL, MySQL, MongoDB, Redis, …)

Less certain matches are reported as warnings: JSON Web Tokens, and generic assignments such as password = "…" or 'api_key' => '…'. Generic values must look random (Shannon entropy ≥ 3.0) and must not be placeholders (example, changeme, your_…, <…>, ${…}, ********, …). Unquoted KEY=value lines are only considered in .env, .ini, .cfg, .conf and .properties files.

If RepoDoctor reports a real secret: rotate it first, then remove it from the code and from Git history. Deleting the line is not enough once it has been pushed.

Suppressing findings

EXAMPLE_KEY = "..."  # repodoctor: ignore

• repodoctor: ignore anywhere on a line hides findings on that line.

• repodoctor: ignore-file in the first five lines skips the whole file. Generated Markdown reports include this marker, so committing a report does not make the next scan report it again.

Use it from Claude (MCP)

RepoDoctor ships a read-only Model Context Protocol server. Install the extra, then point your MCP client at repodoctor mcp:

pip install "repodoctor[mcp] @ git+https://github.com/daamles/repodoctor.git"
repodoctor mcp --root ~/projects          # stdio server; --root is repeatable

Claude Desktop — add this to claude_desktop_config.json (on Windows use the full path to repodoctor.exe inside your virtual environment):

{
  "mcpServers": {
    "repodoctor": {
      "command": "repodoctor",
      "args": ["mcp", "--root", "/path/to/your/projects"]
    }
  }
}

Claude Code — register it from your project directory (see the Claude Code MCP documentation):

claude mcp add repodoctor -- repodoctor mcp --root .

Then ask things like "Scan this repository and explain the most serious findings" or "Are there any secrets under src/?".

Every tool is annotated readOnlyHint: true. Paths are resolved against the first --root, and anything outside the allowed roots is refused, so an AI client cannot use RepoDoctor to read arbitrary directories.

How it works

cli.py ──────────┐                       ┌── ui.py          (Rich terminal output)
mcp_server.py ───┼─> scanner.analyze() ──┼── reporters/     (JSON, Markdown)
service.py ──────┘        │              └── formatting.py
                          ├── walker.py    which files: .gitignore, pruning, no symlinks
                          │     └── ignore.py   dependency-free gitignore matcher
                          └── checks/      what is wrong: one class per rule
                                ├── base.py     FileContext reads each file once via reader.py
                                ├── size.py · todos.py · lines.py · secrets.py

• walker.py decides which files to look at; checks/ decides what is wrong with them. Both feed a plain ScanResult dataclass.

• reader.py is the only module that opens source files: size-capped, binary files rejected, decoding never fails.

• The CLI and the MCP server are thin layers over the same analyze() call.

• Adding a rule means writing one Check subclass and registering it in checks/__init__.py.

Development

pip install -e ".[dev]"
pytest                          # 200+ tests
ruff check . && ruff format --check .
repodoctor scan . --fail-on warning   # RepoDoctor checks itself in CI
python examples/make_demo.py    # regenerate the example outputs

Test data never contains a complete fake credential: values in tests/fakes.py are assembled at runtime, so neither RepoDoctor nor GitHub push protection flags this repository.

Roadmap

• Configuration through [tool.repodoctor] in pyproject.toml

• SARIF output for GitHub code scanning

• More languages and secret formats

• Git history scanning for secrets that were removed but never rotated

License

MIT © 2026 daamles