get_health

get_health gives your agent the Code Health layer directly: a 1 to 10 score per file across three signals (defect risk, maintainability, performance), the marker findings behind it, repo-level KPIs, refactoring targets, and trend alerts. Zero LLM calls; it reads precomputed metrics.

When to call#

• Self-check before a PR. Read the same signals a code-health merge-gate judges the change on. Pass the files you touched and confirm you are not regressing the worst files.
• Before a refactor. Find the lowest-scoring files and the specific markers dragging them down.
• Triage. Dashboard mode returns the repo's worst files ranked, plus the "does the score find the bugs?" stat so the agent knows the score is trustworthy on this repo before acting on it.

Parameters#

Returns#

Dashboard mode (no targets) leads with a directive, then repo-level KPIs:

There is no kpis.hotspot_health on the dashboard KPIs; the hotspot-only NLOC-weighted average only exists inside the opt-in trend block, as current_hotspot_health / previous_hotspot_health (see below).

Targeted mode (targets given) returns mode, targets, metrics (one row per file: file_path, score, maintainability_score, performance_score, weighted_deficit, complexity/coverage stats, and the dominant-finding lead), metrics_total, findings (type, severity, line span, reason, and a dimension), and findings_total. Depending on what matched, it also carries unresolved, known_modules (after an unresolved module: target), trends (per-file score history, silent when a file has fewer than 2 snapshots), and modules (when the target list includes a module: target). There is no per-file "score breakdown by category" field, and no defect_score field: it was set from the same value as score on every row, so score is the one to read. The field to rank files on is neither score nor maintainability_score / performance_score, but weighted_deficit.

Opt-in enrichments#

• biomarkers returns the full (uncapped) findings set in dashboard mode. Pair with a dimension name, e.g. include=["biomarkers", "performance"], to narrow to one pillar.
• trend adds a trend block: current_hotspot_health / previous_hotspot_health (the NLOC-weighted average over hotspot files only), current_average_health / previous_average_health, hotspot_delta, average_delta, alerts, and recent (up to 10 past snapshots).
• accuracy adds a defect_accuracy block: of the K least-healthy files, how many were recently bug-fixed vs the repo-wide base rate (precision@K + lift), with a per-K table and the flagged files. null on repos with too little history to be honest.
• signals adds a signals object on each targeted metric: prior-defect count, change scatter, 90-day churn, primary / recent owner, and graph in / out degree. Honest null per field when the underlying row is absent.
• churn_complexity adds churn_complexity points (one per recently-changed file: 90-day commits, max CCN, NLOC, score, churn percentile).
• dimension filter narrows findings to one pillar; pair with "biomarkers" for the full set, e.g. include=["biomarkers", "performance"].

Example#

get_health(only=["directive"])                            # cheapest useful call: what to fix first
get_health()                                              # directive, kpis, gap_analysis, worst + high-leverage files
get_health(include=["accuracy", "churn_complexity"])      # is the score trustworthy + danger zone
get_health(include=["biomarkers", "performance"])         # only performance-pillar findings
get_health(targets=["src/api/server.py"], include=["signals"])  # self-check one file
get_health(targets=["module:src.api"], include=["trend", "refactoring"])

Things worth knowing#

• Deterministic and offline. The markers run off tree-sitter + git data with calibrated weights: no model calls, reproducible scores.
• Three signals, never blended. score is the defect-calibrated headline; maintainability and performance are co-equal companion views with their own per-file scores and dimension-tagged findings.
• Coverage is opt-in. The coverage markers (untested_hotspot, coverage_gap, coverage_gradient) only fire once you've ingested a report via repowise coverage add.
• Module targets (module:foo) expand to every file under the module, so one call covers a whole package.
• Refactoring plans carry an id. include=["refactoring"] returns each plan with a suggestion_id. Pass that id to generate_refactoring_code to get refactored code and a unified diff for that one plan.