/gaia-wiki
The wiki at wiki/ exists for Claude, not for human reading (though Claude uses it to answer questions about the project).
Why the wiki exists
Section titled “Why the wiki exists”The wiki keeps an up-to-date, organized description of the project that Claude reads when it needs it, instead of working out the same facts from the source code on every request. Working them out again each time wastes tokens; the wiki saves them.
Without it, every session that needs to reason about a service, a hook contract, or a past architectural decision pays for it twice: once when the source was written, and again when Claude reads the source to answer a question. The wiki records the important facts once and stays current as commits land. Claude reads the wiki for orientation and goes to the source only when it needs more detail.
The wiki is an Obsidian vault, so you can open it in Obsidian (opens in a new tab) if you want to. No plugin is required.
When to use it
Section titled “When to use it”Some work updates the wiki as it goes. When a plan’s pull request is ready to merge, Claude can promote a summary of what shipped into the wiki on the same branch, and Claude may update a page during other work when it learns something lasting. Nothing makes every change do so, though, so the wiki can fall behind your code. /gaia-wiki is the backstop: it catches up whatever the rest of your work missed. Often sync finds little or nothing to add, and consolidate and lint still check the wiki’s health.
When the wiki is 20 or more relevant commits behind your code, the statusline shows:
🧠 /gaia-wiki (N commits)Run /gaia-wiki then. It is a skill, so plain-language asks like “sync the wiki” or “run wiki maintenance” work too.
/gaia-wikiIt takes no arguments and runs the three stages. Anything you pass prints a one-line notice and is ignored.
It runs like every maintenance command: from the main checkout, in a worktree of its own cut from the default branch.
What one run does
Section titled “What one run does”- Sync brings the wiki up to date with the commits since its last sync.
- Consolidate finds redundancy and contradictions across wiki pages and asks you about each one.
- Lint checks the wiki’s health and fixes what it finds.
- One commit with all three stages’ edits, titled
wiki: <date> <time> UTC. - One pull request with that title, marked as outside the code audit’s scope and set to merge automatically.
- Claude waits for the merge, removes the worktree and branch, pulls the default branch, and clears the statusline nudge.
When sync stops partway (a first run, a rewritten history it cannot recover from, an interruption), consolidate and lint are skipped, and whatever sync completed still lands. A cancelled run commits nothing.
The run ends with a cost line, which includes the time it waits for the merge.
The three stages
Section titled “The three stages”Sync goes through every commit since the last one the wiki checked, up to HEAD, decides which ones matter to the wiki, and updates the affected pages. Commits that change nothing the wiki describes are skipped, and only commits that led to a wiki change are logged. Changes to services and hooks are written to their pages under wiki/modules/.
When the wiki is more than 30 commits behind, sync asks first. You can choose to sync only the most recent 20 and treat everything older as done.
Sync decides which commits matter by which files they change. By default it treats files under frontend/app/ as your source code. If your code also lives elsewhere (for example a backend package), ask Claude:
Make /gaia-wiki treat changes under backend/src as source code too.Claude records this under gaia.wikiClassify in the root package.json, which /update-gaia leaves alone.
Consolidate
Section titled “Consolidate”Consolidate looks for four kinds of finding, most important first:
- Supersession: two pages in the same area cover the same subject, and the newer one should take in the older one.
- Reversed decisions: a decision page whose body reverses an older decision page.
- Near-duplicate page names: names in the same area that differ by at most two characters (ignoring case, and treating
_as-). - Subject-orphaned pages: pages nothing links to, that match no concept or module page, and that have not changed in 90 days.
Each finding is one question:
- Apply (recommended): merge or retire the page. Links to an archived page are rewritten.
- Keep both: note on the main page that you have seen it, so it is not raised again.
- Skip: leave it for the next run.
The report overwrites one file each run, wiki/meta/consolidate-report.md (wiki/meta/ is created on the first run).
Lint runs every check from scratch and overwrites one report, wiki/meta/lint-report.md (wiki/meta/ is created on the first run):
| Check | Finds |
|---|---|
| Wiki drift | How many commits the wiki trails HEAD. |
| Dead paths | Repository paths in backticks in wiki text that no longer exist. |
| Narrative ID drift | SPEC and UAT numbers in prose where they should not appear. |
| Orphan pages | Pages no other page links to. |
| Frontmatter gaps | Pages missing type or status. |
| Empty sections | Headings with no content before the next heading. |
| Broken wikilinks | Wikilinks that resolve to no page. |
Lint then fixes what it found. Simple fixes (a missing frontmatter field, an index entry for an orphan page, a path to a file that was renamed) apply without asking. Fixes that need judgment ask you. Every finding ends up fixed, filed as a tech-debt issue, or left alone because you chose to.
Cleanup at session start
Section titled “Cleanup at session start”At every session start, a hook cleans up after earlier wiki runs. It deletes local wiki branches whose work is already merged. When it finds one, it runs one git fetch with a time limit and fast-forwards your default branch if it is checked out and has no uncommitted changes. So a run that ended before its merge landed never leaves your default branch out of date.
Two environment variables tune that fetch. GAIA_WIKI_FETCH_TIMEOUT_SECONDS (default 5) sets its time limit in seconds, from 1 to 30; 0 turns the fetch off, and with it the deletion of merged wiki branches. GAIA_WIKI_FETCH_MINIMUM_INTERVAL_MINUTES (default 60) sets the shortest gap between fetches, at least 5 minutes; 0 removes the gap, so the hook may fetch at every session start. The hook reads them when a session starts. Ask Claude to add one to the env block of .claude/settings.local.json (your machine only, never committed), then restart Claude Code:
Set GAIA_WIKI_FETCH_TIMEOUT_SECONDS to 15 in the env block of .claude/settings.local.json.You can export it in your shell profile instead; restart Claude Code either way.
What ships in the wiki
Section titled “What ships in the wiki”GAIA ships wiki pages describing what it installs: concepts, decisions, and modules. They describe GAIA’s conventions as your project’s own. Ask Claude about any GAIA convention; it answers from these pages. Sections you add to a GAIA-shipped page are kept when /update-gaia merges a new release.
Related
Section titled “Related”/gaia-cleanse handles memory and auto-loaded files that duplicate or contradict the wiki. /gaia-wiki handles redundancy and broken links inside the wiki itself.