gaia

GAIA

Claude is raw power. GAIA is order and focus.

A serious harness for Claude Code. It keeps Claude-shipped code production-grade as your team scales. The React frontend is handled. You build the rest of your app on top. Claude can't commit code that fails lint, type checks or the unit tests it affects, can't skip those checks with --no-verify, and can't merge a source change until the Code Audit Team clears it.

Quick Start · What Breaks Claude · Trust · Token Economics · Tech Debt · Tech Stack · Claude Workflow · Feedback · History

Who It's For

• Engineering teams whose AI output is outpacing their review process
• Engineering leads standardizing how Claude works across the org
• Teams adopting AI-assisted development who want production-grade defaults from the first commit
• Individuals building apps with Claude

Quick Start

npx create-gaia@latest my-app

One command. GAIA handles the rest, then /gaia-init finishes the last-mile setup (below).

Note Start projects with npx create-gaia@latest my-app rather than cloning or forking. The CLI sets up your project for you, strips the GAIA branding and release tooling, etc. A clone leaves all of that in place and pointed at the wrong repo.

Requirements: Node.js >= 22.22.0 (nvm recommended). macOS or Linux; on Windows, run inside WSL2 (the hooks and CLI need bash and POSIX file paths, and native Windows isn't exercised in CI).

Learn more about GAIA →

Then: /gaia-init

GAIA ships clean. /gaia-init does the last-mile setup:

• Configures the project. Title, package name, docs title, CODEOWNERS, localized site titles.
• Installs dependencies. Installs or updates pnpm with npm, runs pnpm install.
• Configures i18n. Prompts for your language set, scaffolds the matching language files, updates the component and Storybook wiring.
• Installs the React Doctor skill. React Doctor, first, so it is ready in the same session.

When it finishes, it continues straight into /setup-gaia in the same Claude session, which installs Playwright CLI and the typescript-lsp plugin, provisions the GitHub repository (for a repo admin, branch protection with the GAIA-Audit required check and squash-only merges) and asks the per-machine sandbox and statusline choices; it ends without a restart, suggesting /clear to start your first feature with a fresh context. /setup-gaia runs only the steps a clone still owes, so any developer can re-run it safely.

You end up with a clean app shell and a fully-configured Claude workflow.

Repository layout

GAIA is a monorepo. The harness (.claude/, .gaia/, .githooks/, .github/, wiki/) lives at the repo root and the React app lives in apps/web/. Launch Claude at the root for harness workflows (audits, merges, releases, /gaia-* commands); a launch inside apps/web/ supports frontend work through commit. Upgrading a 1.6.1 project? Open Claude Code in the 1.6.1 project and ask it to fetch, verify and follow the bundled 2.0.0 migration note, as the first line of the v2.0.0 release describes.

What Breaks Claude on Real Projects

Most setups treat Claude as a tool you hold: bolt a CLAUDE.md onto the root and hope the model figures out the rest. GAIA treats Claude as an engineer you manage. That shift exposes three failure modes the bolt-on approach papers over.

Trust. You can't manage an engineer you can't predict. Without enforceable conventions, Claude reverts to its training distribution: an average of every codebase on the internet, bad code and all. GAIA's codebase is what you actually want Claude matching, and the rules make sure it can't ship code that doesn't.

Token economics. Context bloat isn't just CLAUDE.md sprawl. Instructions get dropped into global memory, forgotten, and accumulate into redundancies and conflicts that compound every session. GAIA keeps token usage minimal by design.

Compounding tech debt. Dependencies fall behind, vulnerabilities sit unpatched, dead code piles up, and the wiki drifts from the code while you ship features. Left alone, the project rots in the background. GAIA runs maintenance continuously so it doesn't.

How GAIA Makes Claude Trustworthy

• Coding principles, enforced. GAIA keeps four coding principles current models still need, all its own: Simplicity First, Surgical Changes, Test What Matters, and Always Verify Your Work.
• Best practices baked in, debt blocked at the source. Rules encode the conventions directly instead of hoping Claude infers them from whatever's already in the repo, and block debt-accumulating patterns from being written at all: untyped exports, untested components, hardcoded strings, a11y gaps.
• Consistently clean code. Over 1,200 lint rules, strict TypeScript, Prettier, and Knip enforce style, correctness, and dead-code detection across every file Claude touches, and every commit message follows Conventional Commits.
• Bundled skills wired in for write-time quality. react-code, tailwind, tdd, playwright-cli, skeleton-loaders, eslint-fixes, and a11y-fixes load on demand when Claude edits matching files or a tool reports a fixable violation. The tdd skill drives a red-green-refactor loop tailored for Vitest, Storybook story tests, and MSW.
• Specs that turn into tests. /gaia-spec authors an immutable SPEC artifact through Socratic discovery. The SPEC names the feature's critical user flows in plain language, and /gaia-plan builds the feature first, then writes one test per flow in a closing phase once the code exists. The PO states the flows and the tests follow from them.
• Code Audit Team before every merge. Each member of the Code Audit Team owns the files its roster entry claims, and a diff dispatches only the members whose files it touches. The default member, which covers the web app and any workspace member no specialist shares, reviews for security (XSS, SSRF, IDOR, secret exposure, timing attacks, vulnerable dependencies), performance, architecture, and defects that lint and types miss, with line-level rule specialists, react-doctor, and knip running alongside it and extension files in apps/web/.claude/agents/code-audit-frontend/ injecting library-specific rules at runtime. A proven-small change since a member's last full review can route to a cheaper light review. Findings are tiered Critical, Major, and Minor, and the self-running audit loop fixes them round by round in a subagent, so your session holds only a short report. The merge blocks until every dispatched member clears. Runs locally.
• Quality gate before commit. Typecheck, lint, unit and Storybook tests, Playwright E2E, a dev-server smoke test, and the production build must all pass. Not "mostly clean." Actually clean.
• Guardrails against destructive moves. A read guard hook and the sandbox's filesystem deny list block reads of .env files, key and certificate files, credential-named files (TypeScript source excepted), and anything under a secrets/ directory. A tool allow list scopes Bash and Edit surfaces. Pre-tool-use hooks reject dangerous commands at the source: destructive git on main, eslint.config edits, rm -rf, and writes to env/secret files. All in .claude/hooks/, wired through .claude/settings.json, whose permissions deny list also blocks edits to pnpm-lock.yaml.

How GAIA Keeps Claude Token-Efficient

• Rules scoped to activate only when needed. Claude loads the ones that match what it's editing. Nothing else.
• Tiers of memory, each scoped and self-maintaining. Claude stops relearning the codebase every session:
  • Wiki (repo): architecture, modules, decisions, flows, concepts as focused, linked Markdown committed to git and shared across the team. Claude opens the one page it needs ("How does dark mode wire through?") instead of preloading the whole manual. A statusline nudge flags when the wiki trails HEAD; a SPEC's outcomes promote into wiki pages before its PR merges; a consolidate pass catches redundancy and contradiction as SPECs accumulate. /gaia-wiki runs sync, consolidate, and lint on demand, each step's heavy reading in a fresh subagent context, and lands them as one commit. Open wiki/ in Obsidian for graph view, backlinks, and search. GAIA owns log.md and index.md: gaia wiki log-prepend writes log.md and /gaia-wiki maintains index.md.
  • Agent memory (per-agent): what a subagent you give persistent memory keeps between runs, inventoried by /gaia-cleanse with the rest.
  • User memory (global): your preferences, style, and defaults, carried across projects.
• Periodic knowledge cleanse. /gaia-cleanse sweeps memory and autoloaded files (CLAUDE.md, rules) for duplication with the wiki, contradictions with it, and stale content before they start costing tokens.
• Task orchestration in clean subagent contexts. /gaia-plan spawns each phase as a focused subagent with only the context it needs. No accumulated history, no stale assumptions. Spec discovery (/gaia-spec) runs in its own context too, separate from implementation; the immutable SPEC artifact is the handoff, not accumulated context.

How GAIA Keeps Tech Debt From Compounding

The quality gate keeps each commit clean and Knip keeps dead code out (see Tech Stack). The rest runs over the life of the project:

• /update-deps. Dependency remediation: discovers every outdated package and open security advisory, audits version overrides, applies codemods and breaking-change migrations for major bumps, resolves conflicts between simultaneous upgrades, fixes advisories by the least invasive method that clears them (or dismisses the alert when you accept one), then runs the quality gate before reporting done. Dependabot only supplies the alerts.
• /update-gaia. Pulls the latest GAIA release into the project without clobbering your work: a three-way merge per file (your version, the release baseline, the new release) governed by ownership classes in .gaia/manifest.json, prompting only where your changes and GAIA's collide. Both updates surface as passive statusline indicators at session start.
• /gaia-debt. The pre-merge audit may discover tech-debt outside the scope of what it's reviewing. Rather than let it slip, GAIA logs it as a tracked issue, and /gaia-debt works through that backlog one item at a time, most important first, and offers an optional batch of small unrelated issues when two or more unrelated issues or groups fit at offer time. A statusline indicator shows how much is waiting.

Tech Stack