repolens
Audit any repository from the command line and get a health report — README quality, licensing, tests, CI, TODO debt, oversized files and hardcoded secrets.
Pure Python standard library: no dependencies, nothing to install in CI beyond Python itself.
Try it online
Live site: https://repolens-klm1.onrender.com. Paste any public GitHub repository URL and get its examination record, the lines of the chart, a prescription, and an optional AI Examiner to ask about the result.
New to the site? Read the guide to using RepoLens. It walks through every screen, explains how to read the score, covers the Examiner's modes, and lists limits, privacy and troubleshooting.
The hosted site runs on a free instance that sleeps when idle, so the first visit can take up to a minute.
Quick start
git clone https://github.com/<you>/repolens.git
cd repolens
python -m repolens .
repolens report for /home/you/projects/repolens
PASS readme README present and substantial - README.md, 3187 chars
PASS license LICENSE declared - LICENSE
PASS gitignore Ignore file configured - 11 rules
PASS tests Automated tests exist - 2 test files
PASS ci Continuous integration configured - 1 pipeline files
PASS todos Unresolved TODO markers - 10 markers
PASS large-files No oversized files committed - none over 5 MB
PASS secrets No hardcoded secrets - no credential-like literals found
Health 100/100 (8 pass, 0 warn, 0 fail)
Install it as a real command with pip install -e ., then run repolens <path> from anywhere.
Usage
repolens # audit the current directory
repolens ../other-project # audit somewhere else
repolens . --only secrets tests # run selected checks
repolens . --json # machine-readable output
repolens . --strict # exit 1 on warnings too
repolens --list # show available checks
Exit codes: 0 healthy, 1 a check failed (or warned under --strict), 2 bad arguments. That makes it usable as a CI gate:
- run: python -m repolens . --strict
Checks
| id | What it means | Warns | Fails |
|---|
readme | A root README exists and has real content | under 300 characters | missing |
license | Reuse terms are declared | no LICENSE/COPYING file | — |
gitignore | Build noise is excluded from version control | no .gitignore | — |
tests | The project has automated tests | — | no test files found |
ci | A CI pipeline is configured | no GitHub Actions, GitLab CI, Azure Pipelines or Jenkinsfile | — |
todos | Tracked TODO/FIXME/HACK/XXX debt | more than 10 markers | — |
large-files | Binaries and dumps are not committed | any file over 5 MB | — |
secrets | No credential-like literals in tracked text | — | AWS keys, private key blocks, or password/token/api_key assigned a literal value |
Scoring is pass = 1, warn = 0.5, fail = 0, averaged and reported out of 100.
Each result has a short detail summary and an evidence list with the specific locations behind it: path:line (kind) for secrets and path (size) for large-files. The text report prints evidence indented under its check, and --json emits it as an evidence array on every check (empty when there is nothing to point at).
Vendor and build directories (.git, node_modules, .venv, dist, build, __pycache__, …) are skipped everywhere.
Development
python -m unittest discover -s tests -v
python -m repolens .
Browser tests
e2e/ holds Playwright smoke tests for the dashboard. They are dev and CI only; the app itself still has no JavaScript dependencies. The real Python server serves the pages, while GitHub and Gemini responses are mocked, so the suite runs offline at desktop and phone widths:
cd e2e
npm ci
npx playwright install chromium
npx playwright test
Frontend dashboard
The project includes a browser dashboard served by the standard-library web server:
python -m repolens.web --port 8000
Open http://127.0.0.1:8000 and enter a public GitHub repository URL. The server downloads and analyzes its archive locally, showing download, extraction and per-check progress. Downloads allow up to 60 seconds, and each analysis can run for up to 180 seconds. Local folders are audited through the CLI; the dashboard does not automatically load CLI output. Case files (scan history) stay in browser session storage.
The interface is designed around one idea, a repository examined like an eye:
- Acuity chart. The hero is a Bailey–Lovie logMAR chart. The health score maps onto it (100 reads 20/20, 0 reads 20/200), and lines finer than the repository's acuity blur out.
- Control strip. One numbered patch per check, after the Kodak Q-13 colour control patches.
- Resolution-target progress. Progress is shown with USAF-1951 bar triplets.
- Prescription (℞). The remediation plan, with a verify command per line.
- The Examiner. The advisor, presented as a consultation transcript.
The palette is paper and ink plus one signal colour: cobalt, after the slit lamp's cobalt-blue filter, reserved for the primary action and current focus. Status colours were checked with a colour-vision-deficiency validator in both themes and always pair a glyph with a label. Type is Optician Sans (built from Louise Sloan's optotypes, SIL OFL, self-hosted in frontend/fonts), Newsreader and IBM Plex Sans/Mono from Google Fonts. Light, dark and system themes are available.
Archives come from codeload.github.com, which is not subject to the REST API's 60-requests-per-hour limit. An archive must be at most 50 MB compressed, expand to at most 300 MB, and contain at most 20,000 entries.
Deploying (Render)
The repository ships a Render Blueprint for a free Python web service. Nothing needs to be installed.
- In Render, choose New → Blueprint and select this repository.
- When prompted, paste your
GEMINI_API_KEY. It is stored as a Render secret. Leave it blank to deploy with the offline examiner only.
- Deploy. Every push to
main redeploys automatically, and /healthz is the health check.
| Variable | Default | Purpose |
|---|
PORT / HOST | 8000 / 127.0.0.1 | Listening address. Render sets PORT; the blueprint binds 0.0.0.0. Also available as --port / --host. |
GEMINI_API_KEY | unset | Enables the Gemini examiner. |
GEMINI_MODEL | gemini-3.5-flash | Preferred model; the fallback chain still applies. |
REPOLENS_REPORTS_PER_WINDOW | 12 | Examinations per client per 10 minutes (0 disables). |
REPOLENS_QUESTIONS_PER_WINDOW | 40 | Examiner questions per client per 10 minutes (0 disables). Protects your Gemini quota. |
REPOLENS_TRUST_PROXY | off | Use the first X-Forwarded-For hop as the client address. Enable only behind a trusted proxy (the blueprint does). |
Free Render instances sleep after inactivity, so the first request can take up to a minute. Jobs and rate limits are held in memory, so they reset on restart, and the blueprint pins the service to a single instance. If the server restarts mid-examination, the dashboard notices the lost job and re-runs the examination once. A lost examiner answer shows a Retry button.
AI-guided analysis (optional)
The repository advisor sends questions, selected-check context, and recent conversation to the Google Gemini API. It returns a direct answer, recommendations, and a remediation workflow. API access, quotas, and pricing depend on your Google project and model:
-
Create an API key at https://aistudio.google.com/apikey and check the project's model access and quota.
-
Set it as an environment variable before starting the server - never commit it or paste it into chat:
$env:GEMINI_API_KEY = "your-key-here"
python -m repolens.web --port 8000
-
Open Repository advisor, select Gemini, and send a question or choose a prompt. Check details also have an Ask advisor action. Export plan downloads the latest successful response as a Markdown checklist.
On Windows, the server also checks the saved current-user GEMINI_API_KEY environment value when the process environment has no key. This handles VS Code sessions started before the user variable was saved. A nonempty process variable takes precedence; replace it or restart the parent application if it contains an old key. No credential is returned to the browser or added to request URLs.
The configuration indicator only confirms that a key is present, not that Google will accept it. The default model is gemini-3.5-flash. If it is busy, rate limited, retired or too slow, the advisor falls back to gemini-3.5-flash-lite and then gemini-flash-lite-latest, and the answer shows which model replied. Set GEMINI_MODEL to try another model first. Authentication and permission errors stop immediately instead of falling back. AI jobs expire after 120 seconds; cancelling in the browser stops waiting but cannot retract an API request already sent.
The advisor holds a real conversation. The report is sent once as context, earlier turns are replayed as user and model messages, and the check you have open is sent as structured focus. Follow-up questions get a direct answer. A full remediation workflow, with a verification step for each item, appears only when you ask for a review or a plan. Each answer suggests a few follow-up questions.
Select Local guide for deterministic, offline guidance instead of a model request. Gemini requests are explicit: the report and up to six recent conversation messages are sent to Google. Do not enter secrets. Generated guidance is advisory, may be incorrect, and never executes commands or edits a repository.
This feature is entirely optional - every other repolens feature works with zero API keys and zero external services.
Adding a check
The repo ships an agent skill that encodes the whole workflow — check contract, test fixture pattern, docs update and verification steps. In an agent-enabled editor run:
/add-check <check-id>
It resolves to .github/skills/add-check/SKILL.md, which you can also just read and follow by hand. In short: register the function with @check(id, title) in repolens/builtin_checks.py, cover every status it can return in tests/test_checks.py, and add a row to the table above.
Project layout
repolens/
├── repolens/
│ ├── repo.py # cached, ignore-aware filesystem view
│ ├── checks.py # registry, CheckResult, scoring
│ ├── builtin_checks.py # the checks themselves
│ ├── report.py # text and JSON rendering
│ ├── cli.py # argument parsing and exit codes
│ ├── web.py # browser dashboard server and job APIs
│ └── ai.py # optional Gemini-powered analysis and recommendations
├── frontend/ # dependency-free dashboard, case files, 404, exports, self-hosted font
├── tests/
└── .github/
├── skills/add-check/ # agent skill for extending the tool
└── workflows/ci.yml
License
MIT — see LICENSE.
