get_health

get_health gives your agent the Code Health layer directly: a 1–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):

Targeted mode (targets given): per-file score, the per-dimension defect_score / maintainability_score / performance_score, the marker findings (type, severity, line span, reason, and a dimension), and the score breakdown by category.

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.
• 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()                                              # dashboard: KPIs + worst 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.