Maintenance

GAIA ships commands for doing work and commands for keeping the project in shape. This page covers the second kind. A project’s upkeep (dependencies, the wiki, Claude’s memory) drifts a little with every change, and small, regular passes keep each one cheap to fix. You rarely need to remember them: each one except /gaia-forensics surfaces as a statusline nudge when it is due.

Commands

Command	Nudge	What it does
/update-gaia	🚀	Pulls the latest GAIA release into your project with a three-way merge, verifying the release bundle first.
/update-deps	📦	Resolves security advisories, then updates outdated packages by group, through one quality gate.
/gaia-cleanse	🔎	Cleans up Claude’s memory and the files it loads at startup: what repeats or disagrees with the wiki, what is out of date, and what makes the startup context too large. Asks before changing anything.
/gaia-codify	🔨	Turns a problem the Code Audit Team keeps finding into a guard: an automated check, a skill, or a rule for matching files, with your approval.
/gaia-residue	🧹	Goes through the trade-offs reviewers accepted at merge: dismiss each one, keep it for later, or turn it into a tech-debt issue. Never fixes code.
/gaia-wiki	🧠	Runs wiki sync, consolidate, and lint with fixes, as one commit and one pull request. Takes no arguments.
/gaia-fitness	💪	Checks your Claude setup (skills, commands, agents, rules, hooks, settings, CLAUDE.md files, wiki) against a fixed list of rules, grades it F to A+, and fixes your own files one at a time on a yes.
/gaia-forensics	–	Turns a GAIA command or hook that went wrong into a bug report with secrets removed, and offers to file it. Only reads: it changes nothing in your project.

The statusline

The right side of the statusline names each command above except /gaia-forensics, and also /gaia-debt, when it has work to do, with a short reason, for example 🐛 /gaia-debt (3 issues). A nudge clears once the command has done its work. Nudges show only in the main checkout, where these commands run.

Which one to run

Pick by symptom:

• Claude’s starting context feels heavy, or the memory on your machine has grown large: /gaia-cleanse.
• The audit keeps flagging the same kind of problem: /gaia-codify.
• Trade-offs accepted at merge have piled up in merged pull requests: /gaia-residue.
• The wiki trails the code, or wiki pages overlap: /gaia-wiki.
• The integration feels off, a skill is not triggering, a rule is not loading: /gaia-fitness.
• A GAIA command or hook went wrong: /gaia-forensics.

The boundary between /gaia-cleanse and /gaia-wiki is deliberate. /gaia-cleanse reconciles memory and auto-loaded files against the wiki. Redundancy and broken links inside the wiki belong to /gaia-wiki. Conflicts between two instruction files belong to Claude Code’s own /doctor prompt-audit.

How maintenance commands run

Every maintenance command except /gaia-forensics (/update-gaia, /update-deps, /gaia-cleanse, /gaia-codify, /gaia-residue, /gaia-wiki, /gaia-fitness) follows the same pattern:

1. It starts from the main checkout. Inside a linked worktree it stops and names the main checkout; open Claude Code there and run the command again. The exceptions are /update-deps and /update-gaia, which also accept their own deps/ or update/ worktree, so a re-run continues there.
2. It offers to pull first when your checkout’s GAIA version is behind the remote’s.
3. It does its work on a branch of its own, created just before it first changes a file: a worktree cut from the default branch by default, following your team’s isolation policy. It never writes onto the branch your checkout holds. The branch is named for the command and a timestamp, for example deps/2026-10-20-1432.
4. It commits and opens a draft pull request, reviewed by the Code Audit Team. Whether it then merges on its own, asks you first, or leaves the pull request for you depends on the command: see who merges what.
5. It cleans up the worktree and branch and pulls the default branch. A worktree holding unresolved work is kept, with the commands to remove it.

A run that ends with nothing to publish removes its empty branch and worktree.

Each run ends with a cost line showing what it spent.

/gaia-forensics works differently. It only reads, so it needs no branch or pull request: it saves its report under .gaia/local/forensics/ and, when the problem looks like a GAIA bug, asks before filing it as a GitHub issue. See /gaia-forensics.