gitopsy 0.1.0

Dissect any codebase in seconds

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?

Tab	What it tells you
Architecture	Project type, framework, entry points, dependency graph
Tech Debt	Score (A-F), hotspots, top 5 recommendations
Onboarding	Summary, key files, setup steps, contributors, gotchas
Dependencies	All deps with versions, licenses, outdated flags
Conventions	Naming, formatting, import style, consistency score
APIs	All HTTP routes, CLI commands, public exports
Security	Secrets, SQL injection, CORS, auth patterns, risk level
Setup	Prerequisites, install steps, env vars, run commands

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.