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.
