Gitopsy — Dissect any codebase in seconds

One command. Instant codebase intelligence.

Gitopsy analyzes any repository and produces a self-contained HTML report covering architecture, tech debt, onboarding, dependencies, conventions, APIs, security surface, and setup — everything you need to understand an unfamiliar codebase.

Install

pip install gitopsy

Usage

gitopsy .                          # Analyze current directory
gitopsy /path/to/repo              # Analyze any repo
gitopsy --output report.html .     # Custom output path
gitopsy --analyzers arch,debt .    # Run specific analyzers
gitopsy --json .                   # Output raw JSON
gitopsy --badge .                  # Also write a grade SVG badge
gitopsy --save-json .              # Save JSON snapshot alongside HTML

Subcommands

# Generate a grade badge SVG
gitopsy badge .
gitopsy badge /path/to/repo --output my-badge.svg

# Compare two JSON snapshots
gitopsy --save-json .              # capture snapshot.json
# ... make changes, then re-analyze ...
gitopsy --save-json --output new.html .
gitopsy diff gitopsy-report.json new.json --output diff-report.html

What's in the report?

GitHub Action

- uses: UJameel/gitopsy@v1
  with:
    path: '.'
    output: 'gitopsy-report.html'

Full example workflow:

name: Gitopsy Analysis
on: [push]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - uses: UJameel/gitopsy@v1
        with:
          path: '.'
          output: 'gitopsy-report.html'
          upload-artifact: 'true'

The action outputs report-path and overall-grade for use in downstream steps.

Python API

from gitopsy.orchestrator import analyze
from gitopsy.report.renderer import render
from gitopsy.report.badge import generate_badge

report = analyze("/path/to/repo")
render(report, "/tmp/report.html")

# Access structured data
print(report.architecture.framework)   # "flask"
print(report.tech_debt.grade)          # "B"
print(report.tech_debt.overall_score)  # 72

# Generate a badge
svg = generate_badge(report.tech_debt.grade, report.tech_debt.overall_score)

As a Claude Code skill

The skills/gitopsy/ directory ships a Claude Code skill. Copy it to your ~/.claude/skills/ directory and run /gitopsy from any project.

Example reports

Live example reports generated by Gitopsy on popular open-source projects:

• Flask
• FastAPI
• Gitopsy itself

Design principles

• Offline-first — zero mandatory API calls
• Fast — <30s on a 10,000-file repo
• Self-contained — single HTML file, no external deps to view
• Git-optional — works on any directory
• No AI required — all analysis is deterministic

Development

git clone https://github.com/UJameel/gitopsy
cd gitopsy
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for how to add new analyzers.

License

MIT — see LICENSE.