RepoLens

See into any repository—security, reliability, and architecture—before you ship.

RepoLens is an open-source CLI that runs structured code reviews against projects you care about: on your machine, or cloned from GitHub, Bitbucket, Hugging Face, or any Git URL. It follows a clear P1 → P2 → P3 pass (security → bugs/reliability/performance → architecture/quality) and writes audit-friendly reports with impact, remediation steps, and code-example fixes for Critical/High findings.

Status: Alpha 0.1.0a1 on PyPI as repolens-audit (CLI: repolens) — Phases 0–7 complete
Local CLI · remotes · optional scanners · explain + diagrams · GitHub Action · opt-in local learning · enterprise CI recipes
Install: pip install "repolens-audit[scanners]==0.1.0a1" · or from a clone: pip install -e ".[dev]"
Docs: phases · FAQ · rules · install extras · CI / Action · remotes · scanners · local learning · publishing

Why RepoLens?

RepoLens is not a replacement for Semgrep, CodeQL, Dependabot, Snyk, or your test suite. Those stay in CI. RepoLens adds a consistent, human-readable due-diligence layer you can run anywhere.

Modes

What gets checked? See docs/rules.md — plain guide to rules, why they exist, and how to turn them on/off.

Languages & tools

• CLI: Python 3.11+
• Reviews: language-agnostic, with first-class focus on JS/TS, Python, Go, JVM, C#, Ruby, PHP, Rust, Swift (+ IaC/config)
• AI: Bring your own cloud key (Anthropic, OpenAI, DeepSeek), run a local model (e.g. Ollama), or rely on automatic local fallback (--fallback)
• CVE / SAST / secrets: optional plugins (OSV, Semgrep, gitleaks)—not in the slim default install
• Local learning: opt-in on-disk FTS index (repolens learn), informed consent first
• CI: official GitHub Action (action.yml) — see docs/ci.md

Full answers: docs/faq.md · docs/design/ai-keys-scanners-and-local-learning.md.
Setup (cloud / Ollama / scanners): docs/setup-ai-and-scanners.md.
Try it (local + GitHub / Bitbucket / HF / git URL): docs/try-on-your-repo.md.
Interactive helper: ./scripts/repolens-guided.sh (see try-on-your-repo).

Quick start

# Preferred: PyPI alpha (CLI entry point is still `repolens`)
pip install "repolens-audit[scanners]==0.1.0a1"

# From a clone (contributors / dogfood)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Install extras ([dev], [scanners], …)

These are optional parts of the RepoLens package (defined in this repo’s pyproject.toml). They are not settings inside the apps you review.

Full detail: docs/install-extras.md.

# From a clone
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# First-run: cloud key, local Ollama, or none
# Ollama: uses a model from `ollama list` (or pass --model NAME)
repolens init --provider ollama   # or openai | anthropic | deepseek | none

# Inventory + report skeleton (no model call)
repolens review --path ./my-app --dry-run

# Optional scanners (secrets / SAST / CVE)
repolens plugins install all
repolens review --path ./my-app --scanners-only

# Opt-in local learning (stays on disk)
repolens learn build --path ./my-app --accept-local-learning

# Full local review (requires configured provider + key/Ollama)
# Progress lines + LLM heartbeats by default; add -v for more detail
# Deep coverage (multi-pass + heuristics) is on by default; use --no-deep for single-shot
repolens review --path ./my-app --verbose
# After first run: warm packs + recommended timeout
repolens adaptive status --path ./my-app
repolens sentinel --path ./my-app

Sources (local + remotes)

# Local folder
repolens review --path ./my-app --dry-run

# GitHub / Bitbucket / Hugging Face / any git URL
repolens review --github owner/repo --ref main --dry-run
repolens review --bitbucket workspace/repo --ref main --dry-run
repolens review --hf org/model --dry-run
repolens review --hf datasets/org/dataset-name --dry-run
repolens review --git-url https://github.com/owner/repo.git --ref main --dry-run

Private remotes: GITHUB_TOKEN / BITBUCKET_TOKEN / HF_TOKEN (or gh auth login).
Full examples: docs/try-on-your-repo.md · docs/remote-sources.md · docs/scanners.md.

GitHub Actions

- uses: actions/checkout@v4
- uses: vksvicky/RepoLens@main
  with:
    path: .
    run: auto          # scanners always; LLM if API key secret is set
    # or: run: dry-run
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}  # optional

Details: docs/ci.md.

Playbooks also work with any LLM chat: docs/using-playbooks.md.

Reports

In the terminal

Summaries show confidence %, severity counts, and top findings.

Saved Markdown (default artifact)

reports/gate_review_report_{mode}_YYYY-MM-DD_HHMM.md

mode is review, sentinel, or architecture. Each Critical/High finding includes explanation, impact, recommended fix, and a code example. Reports include an Automated scanners section when scanners run.

PDF

pandoc reports/gate_review_report_review_YYYY-MM-DD_HHMM.md -o reports/gate_review_report_review_YYYY-MM-DD_HHMM.pdf
# or: Print → Save as PDF from a Markdown preview

Playbooks & rules

Rules (what is checked, why, enable/disable): docs/rules.md.
Playbook files: playbooks/README.md. Contributions: docs/CONTRIBUTING.md.

Repository layout

RepoLens/
├── README.md                 # This page
├── LICENSE                   # MIT
├── action.yml                # GitHub Action (composite)
├── pyproject.toml            # Python package
├── src/repolens/             # CLI, pipeline, scanners, learning
├── tests/                    # pytest suite
├── playbooks/                # Review instruction sources
├── examples/monorepo/        # Sample project config
├── docs/                     # Guides, FAQ, ADR, design, phases
└── .github/workflows/        # CI, publish, Action example

Naming conventions: docs/README.md.

Roadmap

Tracker: docs/phases.md · Design: docs/design/ · ADR: docs/adr/01_analysis_runtime_architecture.md.

Contributing

• docs/CONTRIBUTING.md
• docs/CODE_OF_CONDUCT.md
• docs/SECURITY.md for vulnerability reports
• docs/SUPPORT.md

Disclaimer (AI / LLM output)

RepoLens findings and suggestions may be produced or assisted by AI/LLMs, heuristics, and optional scanners. They can be wrong or incomplete. You are responsible for verifying results before you act. Authors accept no liability for harm from reliance on AI/LLM or tool-assisted output. Reports are not a certification or professional audit engagement. Full text appears in every Markdown report under Disclaimer, and in the FAQ.

License

MIT — use it, fork it, adapt the playbooks for your org. Software is provided as is (see the licence).