Why repoglance?

You clone an unfamiliar repo. What is this thing? How big? What's the messy part? Where's the unfinished work? cloc gives you a wall of numbers. tokei is fast but bare. repoglance answers the human questions in one glance:

repoglance .

Seen in the wild

repoglance run against well-known projects (click to view the full report):

Install

pip install repoglance

Or run without installing:

pipx run repoglance .

Usage

repoglance                       # analyze current directory
repoglance path/to/repo          # analyze another repo
repoglance --json                # machine-readable output for scripts / CI
repoglance --csv                 # per-file CSV
repoglance --sarif               # SARIF for GitHub code scanning
repoglance --svg report.svg      # export a vector report
repoglance --html report.html    # export a browser report
repoglance --badge badge.svg     # export an embeddable badge
repoglance --since origin/main   # only files changed since a revision
repoglance --baseline base.json                         # snapshot now
repoglance --compare base.json --fail-on-regression     # fail on new complexity
repoglance --ci --fail-under 70 --max-complexity 25     # gate a build
repoglance --include "src/**" --exclude "**/*_pb2.py"   # glob filters
repoglance --no-git --jobs 8

JSON output

Pipe structured data anywhere — dashboards, CI gates, badges:

repoglance --json | jq '.languages.Python.code'

What it measures

Binary files, node_modules, .venv, build dirs and friends are skipped automatically.

More than a counter

repoglance isn't just another cloc. Tools like tokei, cloc and scc answer "how many lines?". repoglance answers "what should I look at?" — and gives you artifacts you can put in a PR or a README.

Share it: badges & reports

Generate a self-contained SVG badge — no shields.io round-trip, no tracking:

repoglance --badge assets/badge.svg

Export the full report as a standalone file to drop in a PR or wiki:

repoglance --svg report.svg      # vector, pixel-perfect
repoglance --html report.html    # opens in any browser

Guard your codebase in CI

Fail the build when complexity or TODO debt crosses a line:

repoglance --ci --max-complexity 25 --max-todos 100

# .github/workflows/quality.yml
- run: pip install repoglance
- run: repoglance --ci --max-complexity 25

Exit code 0 = clean, 2 = a threshold was exceeded.

Integrations

GitHub Action — comment on every PR

Drop repoglance into any repo. It posts a sticky report comment on pull requests and can gate the build:

# .github/workflows/repoglance.yml
name: repoglance
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SRJ-ai/repoglance@main
        with:
          fail-under: "70"       # optional health gate
          max-complexity: "25"   # optional complexity gate

The report also lands in the workflow's job summary every run.

pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/SRJ-ai/repoglance
    rev: v0.2.2
    hooks:
      - id: repoglance
        args: ["--ci", "--fail-under", "70"]

Self-updating badge

Commit a shields endpoint file and point a dynamic badge at it — the badge refreshes itself, no service to run:

repoglance --badge-json .repoglance-badge.json   # commit this file

![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repoglance/main/.repoglance-badge.json)

Markdown anywhere

repoglance --md   # paste into a PR, wiki, or Slack

Configuration file

Set defaults once via .repoglance.toml or a [tool.repoglance] table in pyproject.toml (CLI flags always win):

[tool.repoglance]
exclude = ["**/*_pb2.py", "vendor/**"]
max_complexity = 25
fail_under = 70

Docker & GitLab

docker run --rm -v "$PWD:/repo" repoglance /repo

A ready-to-copy GitLab CI job lives in integrations/gitlab-ci.yml.

Design goals

• Fast — a single pass, no external services.
• Honest — no network, no telemetry, no surprise writes.
• Pretty — powered by rich.
• Scriptable — everything the report shows is available as --json.

Contributing

Adding a language is a one-line change in languages.py. PRs welcome — see CONTRIBUTING.md.

License

MIT © repoglance contributors