/gaia fitness

/gaia fitness checks the health of your project’s Claude integration and repairs what it safely can. One invocation, no flags: calling /gaia fitness is the statement of intent to be fit. It runs three phases in sequence: triage, heal, verify, and reports a per-category and overall grade from F up to A+.

It checks the Claude surface (hooks, skill/command/agent frontmatter, rule files, CLAUDE.md, .claude/settings.json, GAIA itself, and wiki structure), not your application code. For app code review before merge, use the code-review-audit agent. For knowledge-store bloat and duplication, use /gaia audit.

When to use it

Run /gaia fitness after editing under .claude/, such as modifying or adding new commands, skills, agents, hooks, etc.

You can also call it after pulling a GAIA update with /update-gaia if you made any customizations to GAIA, or periodically as a routine check.

How to invoke

/gaia fitness

No flags. No arguments.

What gets checked

Triage dispatches seven category checks in parallel. Each produces a set of findings, each finding tagged with a severity (info, warning, error):

Category	What it checks
Hook integrity	.claude/hooks/* scripts and their wiring in settings.json.
Skill / command / agent frontmatter	.claude/skills/**, .claude/commands/**, .claude/agents/** frontmatter completeness and validity.
Rule hygiene	.claude/rules/*.md scope, paths: frontmatter, size.
CLAUDE.md hygiene	Root and nested CLAUDE.md files: size, structure, duplication.
Settings hygiene	.claude/settings.json: permission pairs, redundancy, malformed entries.
GAIA-install fitness	Whether the GAIA install is intact and consistent.
Wiki fitness	Wiki structure: state file, manifest, orphans, dead repo-relative paths.

The checks are recall-oriented and over-flag on purpose. Before grading, /gaia fitness adjudicates each finding against the actual repo and drops the false positives (an unfamiliar-but-valid hook event, a permission pair that only looks redundant, and so on). What survives gets graded.

Grading

Each category gets a letter grade. A+ means zero findings. From there the grade keys off the worst severity present, then the count at that severity:

• All findings at info: stays in the A band (A, then A- as the count grows).
• A warning is the worst severity: B band.
• An error is the worst severity: C band, dropping through D as errors pile up.
• A structurally broken category: F.

The overall grade is the floor of the seven category grades. The integration is only as fit as its weakest surface.

An A should be considered a clean bill of health.

The three phases

Triage. Run the seven checks, adjudicate the findings, compute the grades. Each surviving finding is then classified as fixable (a mechanical edit a fixer can apply confidently without product context: a missing frontmatter field, a bad path, a .gitignore line) or unfixable (needs product context or invasive restructuring: splitting an oversized CLAUDE.md, rewriting a rule’s scope, reworking hook logic).

Heal. Fixable findings get repaired by lane-aware fixers running in parallel, one lane per surface area (.claude/ surface and CLAUDE.md; .claude/settings.json; .gitignore; .gaia/manifest.json). Healing runs inside a bounded loop, three cycles by default. After each cycle the affected checks re-run; if a finding survives a fix attempt unchanged, the loop stops chasing it and marks it unresolved. A fixer that judges a repair too invasive to apply without product context leaves it alone and surfaces it in the report with a recommended approach. Nothing is ever committed. The working tree is left for you to review.

Verify. After each heal cycle the affected category checks re-run and the grades recompute. If the overall grade reaches A+, the loop exits clean.

Branch behavior

Where the fixes land depends on which branch you are on when you run it:

• On the default branch (main), with at least one fixable finding: /gaia fitness creates and switches to a new branch named chore/gaia-fitness-<timestamp> before applying anything, so main stays untouched.
• On any other branch, with at least one fixable finding: it heals in place on your current branch.
• No fixable findings (including a clean A+ run): no branch is created, HEAD stays put, nothing changes.

Unsafe repo state

Before any heal-phase change, /gaia fitness checks whether the repo is safe to mutate. If HEAD is detached, or a rebase, merge, cherry-pick, or bisect is in progress, it switches to a triage-only path: it runs the checks, prints the grades, tells you heal was skipped and why, gives the resolution steps (for example, git rebase --abort or git checkout <branch>), and stops. No working-tree change, no branch.

After the run

/gaia fitness prints a findings list grouped by the seven categories, one line per finding:

- [severity] `file:line` — remediation

Unresolved or unfixable findings are included alongside their recommended approach. The findings list is followed by the grades table and the overall grade. A clean run skips the findings list and prints only the grades.

Then, depending on what happened:

• A branch was created. Review with git diff main, commit when satisfied, or discard with git checkout main && git branch -D chore/gaia-fitness-<timestamp>.
• Healed in place. Review with git diff, commit when satisfied, or discard with git checkout -- ..
• Triage-only. Re-run /gaia fitness after you have resolved the unsafe state.
• Zero findings. Nothing to do.

Related

/gaia fitness checks the Claude integration surface. For knowledge-store duplication and autoload budgets, use /gaia audit. For wiki-internal redundancy and broken wikilinks, use /gaia wiki. For your application code on a branch before merge, use the code-review-audit agent.