vitals

Vitals

Your codebase has a health score. You just can't see it yet.

Vitals is a Claude Code plugin that finds the files most likely to cause your next outage, explains why they're dangerous, and tells you exactly what to fix first.

It's not a linter. It's not a static analysis tool. It reads your code, thinks about it, and gives you a diagnosis — like a doctor, not a thermometer.

/vitals:scan

Overall Health: 5.4 / 10.0  ██████████░░░░░░░░░░

HOTSPOTS — Ranked by ROI (core > test, central > leaf)

File                                   Health  Role  Complexity  Churn  Links
───────────────────────────────────────────────────────────────────────────
src/proxy/server.py                      2.3  core   100        49/90d    63
src/transforms/content_router.py         2.8  core    98        17/90d    35
src/transforms/smart_crusher.py          2.8  core   100        16/90d    12

TOP RECOMMENDATION
  src/proxy/server.py is your #1 priority: 7,137 lines, health 2.3 (alert zone),
  49 changes in 90 days, co-changes with 63 other files.
  This file handles routing, caching, rate limiting, cost tracking, AND metrics
  in a single class. Extract each concern into its own module.

Install

In Claude Code, run:

/plugin marketplace add chopratejas/vitals
/plugin install vitals@vitals

Then:

/vitals:scan
/vitals:scan src/auth          # scope to a directory
/vitals:scan --top 20          # show more hotspots

No API keys. No configuration. No external dependencies. Just Python 3 and a codebase.

What It Does

Phase 1: Quantitative Triage (Python)

A fast metrics scan identifies WHERE to look:

• Hotspot Detection — Files ranked by churn x complexity x centrality. Not just "what's complex" but "what's complex AND changing frequently AND connected to everything else."
• Co-Change Coupling — Files that always change together, revealing hidden architectural dependencies.
• Knowledge Risk — Bus factor analysis. Which files have only one contributor? What happens when they leave?
• ROI Ranking — Core production code with high centrality ranks above tests and leaf utilities. Because fixing a central engine has 10x the impact of fixing an isolated helper.

Phase 2: Deep Analysis (Claude)

Claude reads the top hotspot files and diagnoses root causes:

• Not "high complexity" but "this function handles validation, transformation, AND persistence in one 200-line loop"
• Not "strong coupling" but "these files share a global config dict — introduce dependency injection"
• Not "low health score" but "only one person contributes because the code is so tangled others avoid it"

The metrics tell Claude where to look. Claude tells you what's actually wrong.

Phase 3: Silent Provenance Capture (Background)

From the moment you install, Vitals silently tracks every AI-generated edit:

• Which files are being modified by AI
• How frequently each file is touched
• The ratio of AI-generated to human-authored changes

This data accumulates over time. After a week of use, /vitals:scan shows AI-specific insights — which files are churning under AI edits, which modules are being regenerated instead of maintained.

How It Works

Developer runs /vitals:scan
         │
         ▼
    ┌─────────────────────────────────────┐
    │  Phase 1: Python metrics script     │
    │  ├─ git log → churn analysis        │
    │  ├─ indentation → complexity gate   │
    │  ├─ co-change → coupling detection  │
    │  ├─ shortlog → knowledge risk       │
    │  └─ Output: structured JSON         │
    └──────────────┬──────────────────────┘
                   │
                   ▼
    ┌─────────────────────────────────────┐
    │  Phase 2: Claude reads hotspots     │
    │  ├─ Reads top 3 core files          │
    │  ├─ Diagnoses root causes           │
    │  ├─ Assesses blast radius           │
    │  └─ Prescribes specific fixes       │
    └──────────────┬──────────────────────┘
                   │
                   ▼
    ┌─────────────────────────────────────┐
    │  Report: ROI-ranked action plan     │
    │  ├─ Core hotspots with diagnosis    │
    │  ├─ Coupling issues explained       │
    │  ├─ Knowledge risk assessment       │
    │  └─ "Fix this first" ranked list    │
    └─────────────────────────────────────┘

Meanwhile, in the background:
    PostToolUse hook → captures every AI edit → .vitals/store.db

Design Principles

Zero dependencies. No pip install. No npm. No API keys. The entire plugin is Python stdlib + git. If you have Python 3 and a terminal, it works.

Zero regex. Complexity is measured by indentation depth, not language-specific keyword patterns. This works for Python, Java, Scala, Go, TypeScript, Rust — any language with indentation. The nesting gate (depth <= 2 = not code) filters lock files, configs, and data files without maintaining a brittle extension list.