Quickstart
Create a config, run gdhealth health, and read your first report.
1. Install
cargo install --path .Requires Rust 1.85+. See Installation for details.
2. Create a gdhealth.toml at your project root
The minimal config below discovers all .gd files and applies default thresholds:
[discovery]
include = ["**/*.gd"]
exclude = ["addons/**", ".godot/**", "reports/**"]For a full config with groups, thresholds, and policy rules, see Configuration.
3. Run the health command
gdhealth health --root .This writes the full report bundle to reports/code-health/:
reports/code-health/
├── summary.txt ← human-readable overview
├── health.json ← machine-readable aggregate (the gdsuite integration surface)
├── graph.json ← full dependency graph
├── graph.dot ← GraphViz format for visualization tools
├── metrics.json ← file and function metrics
└── policy.json ← policy findings with severity4. Read the summary
cat reports/code-health/summary.txtYou'll see something like:
root: .
files: 126
edges: 142
cycles: 1
cross-group dependencies: 79
policy findings: 91
parser warnings: 22
top files:
- player.gd (hotspot: 204, lines: 717, funcs: 36, incoming: 0, outgoing: 1, cycles: 0)
- ai/mob_ai_controller.gd (hotspot: 169, lines: 568, funcs: 33, incoming: 8, outgoing: 0, cycles: 0)
top functions:
- levels/main_level/terrain_grid.gd::_cast_light (hotspot: 72, lines: 90, cyclomatic: 19, nesting: 4, params: 0)
policy findings:
- [critical] function_lines_threshold: ...5. Inspect health.json for automation
cat reports/code-health/health.jsonThe JSON has a stable schema suitable for scripting, CI dashboards, or aggregation by gdsuite:
{
"tool_name": "gdhealth",
"schema_version": 1,
"summary": { "file_count": 126, "edge_count": 142, "policy_finding_count": 91 },
"top_files": [...],
"top_functions": [...],
"cycles": [...],
"policy_findings": [...],
"cross_group_dependencies": [...]
}See Interpreting Reports to understand what each field means and when to act on it.
Next steps
- Configuration — set up groups, thresholds, and policy rules
- CLI Reference — all flags and output formats
- CI Recipe — use
--fail-onto block on critical findings