GAIA React
Claude is raw power. GAIA is order and focus.
The foundation that keeps Claude-shipped code production-grade as your team scales. The React frontend is handled. You build the rest of your app on top. Every convention enforced in code. Every shortcut blocked at the source. Every merge audited before it lands.
Quick Start · What Breaks Claude · Trust · Token Economics · Tech Debt · Tech Stack · Claude Workflow · 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). uv is required for the Serena MCP server; GAIA installs it during setup if you don't already have it.
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. Bootstraps pnpm via
corepack, runs pnpm install.
- Configures i18n. Prompts for your language set, scaffolds the matching language files, updates the component and Storybook wiring.
- Installs Claude skills, plugins, and MCP servers. React Doctor, Playwright CLI,
typescript-lsp, claude-obsidian, and Serena (LSP-backed symbol search and editing).
- Initializes spec-kit with the bundled GAIA extension and preset, so
/gaia-spec and the spec-kit lifecycle hooks (constitution check, self-review, immutability lint, Playwright UAT auto-write, wiki-promote) are wired before your first feature.
You end up with a clean app shell and a fully-configured Claude workflow.
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 embeds Karpathy's four coding principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) plus two of GAIA's own: Always Use TDD 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. 1,450 lint rules, strict TypeScript, Prettier, and Knip enforce style, correctness, and dead-code detection on every file Claude touches. No negotiation, no drift.
- Bundled skills wired in for write-time quality.
typescript, 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, React Testing Library, Storybook composeStory, and MSW.
- Specs that turn into tests, automatically.
/gaia-spec authors an immutable SPEC artifact through Socratic discovery. Before any source code is written, the SPEC's UATs render as red-state Playwright e2e specs. The implementer's first job is turning red green. The PO writes acceptance criteria in plain English, and the test harness is generated.
- Code-review audit before every merge. A manager agent scans the branch diff for security (XSS, SSRF, IDOR, secret exposure, timing attacks, dependency vulns), performance, architecture, code smells, and antipatterns. Three specialists (React Patterns & Accessibility, TypeScript & Architecture, Translation) run in parallel alongside
react-doctor and knip (whose output is advisory and never blocks), with extension files in .claude/agents/code-review-audit/ injecting library-specific rules at runtime. Findings are tiered Critical, Important, and Suggestions. The merge blocks until no Critical or Important issues remain. Runs locally by default, and in CI once you enable GAIA CI.
- Quality gate before commit. Typecheck, lint, tests, and build must all pass. Not "mostly clean." Actually clean.
- Guardrails against destructive moves. A filesystem deny list blocks reads of , , , , and . A tool allow list scopes Bash and Edit surfaces. Pre-tool-use hooks reject dangerous commands at the source: destructive git on , watch-mode , edits, , writes to env/secret/lockfile files, and in tsconfig. All in , wired through .
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.
- Five 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. Session hooks fire wiki sync when it drifts from HEAD; SPEC outcomes drain in at PR merge; a redundancy and staleness pass runs whenever it grows.
/gaia-wiki drives the full chain (sync, consolidate, lint) on demand, each step in a fresh subagent context. Open wiki/ in Obsidian for graph view, backlinks, and search; the claude-obsidian plugin adds /wiki-ingest, /wiki-query, /wiki-lint, /autoresearch, and /save.
- Hot cache (session):
wiki/hot.md, what Claude touched recently; primed at session start, fast and evictable.
- Handoff (cross-session): compact session state written by
/gaia-handoff, restored by /gaia-pickup. No re-briefing Claude from scratch.
- Agent memory (per-agent): each subagent's scratchpad, persisted between runs.
- User memory (global): your preferences, style, and defaults, carried across projects.
- Periodic knowledge audit.
/gaia-audit sweeps memory, wiki, and autoloaded files for duplication, conflicting instructions, 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.
- Symbol-aware code intelligence over grep. Serena MCP gives Claude LSP-backed symbol search, references, and types. A symbol query returns the one definition, not every line that mentions the name.
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. An autonomous Dependabot: discovers every outdated package, audits version overrides, applies codemods and breaking-change migrations for major bumps, resolves conflicts between simultaneous upgrades, then runs the quality gate before reporting done. No prompts./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. A statusline indicator shows how much is waiting.- GAIA CI, opt-in, set up by
/setup-gaia. A GitHub Actions bot that runs maintenance against your Claude Code Pro/Max subscription or Anthropic API key, capped at $5 per run. Patch and minor dependency bumps get an auto-PR that auto-merges on green CI; major bumps and high or critical pnpm audit findings route to review-required PRs; app-code changes open a labeled wiki-sync PR (a run that rewrites more than 25% of the wiki holds for review); stale branches get cleaned up. If post-merge CI fails, the bot opens one revert PR. A second failure escalates to a priority issue and the bot stops.
Tech Stack
Every piece of GAIA's tech stack is pre-configured and wired into the Claude layer.
- 1,450 lint rules via ESLint, Prettier, and Stylelint that catch the patterns Claude drifts into first: complexity creep, architectural shortcuts, mismatched filenames, broken CSS. Knip detects unused files, exports, and dependencies.
- Pre-commit hooks (Husky + lint-staged): typecheck, lint, and test before CI.
- Testing via Vitest + React Testing Library for unit and integration, Playwright for E2E, and Chromatic for visual regression, all sharing one MSW mock layer.
- Storybook with React Router + i18n + dark mode + MSW integration.
- Internationalization via remix-i18next with working examples.
- Form components with validation using Conform + Zod.
- Dark mode end-to-end. Context, session, CSS, and Storybook all in sync.
- API mocking with Mock Service Worker and msw/data: working handlers for tests and Storybook.
- Toast notifications with remix-toast and Sonner.
- Built with React Router 8, Tailwind, and react-icons.
GAIA also wires agentic-design patterns into the project structure rather than the prompt, so they run the same way every session and every model variant: stop hooks, a blocking pre-merge audit, multi-agent review, spec-driven development, a committed knowledge base, a filesystem deny list, and more. The features page walks through all twelve, grouped as workflow control, context engineering, and tooling and safety.
Claude Workflow
GAIA ships a complete, opinionated Claude Code workflow. Everything is wired in .claude/ and visible in the repo.
Commands
Rules, Hooks, Skills
- Path-scoped rules cover TypeScript, React, Tailwind, testing, i18n, accessibility, and state management. They live in
.claude/rules/; ask Claude about any of them.
- Hooks guard the quality gate and keep the wiki fresh. They live in
.claude/hooks/.
- Bundled skills (
typescript, react-code, tailwind, tdd, playwright-cli, skeleton-loaders, eslint-fixes, a11y-fixes) autoload for matching tasks. Scaffolding skills (new-component, new-hook, new-route, new-service) fire on natural-language asks.
- MCP servers. Serena gives Claude LSP-backed code intelligence: symbol lookups, references, and types instead of grepping the codebase.
Working in a GAIA Project
GAIA is driven through Claude. Ask for what you need.
Build things:
- "Add a new route for settings." → triggers
/new-route, applies routing + i18n + test rules.
- "Add German as a supported language." → Claude walks the i18n setup.
- "Add a zip-code field to the address form with validation." → Claude uses the form patterns from the wiki.
Ask about the codebase:
- "How does dark mode wire through?" → Claude fetches the wiki page on demand.
- "What state patterns do we use?" → one-page lookup, no context bloat.
- "Explain the form-submit flow." → direct answer from the wiki.
Test: Ask Claude to run, add, or debug tests. Vitest, Storybook + Chromatic, and Playwright are wired up.
Deploy: GAIA isn't prescriptive about hosting. Ask Claude to set up deployment for your target (Vercel, Cloudflare, Fly, AWS, a bare Node host, a Docker container, anywhere React Router runs). Claude wires up the build, environment variables, and any CI/CD you need.
Extend: Rules, hooks, skills, and commands live in .claude/. Ask Claude to add, modify, or explain any of them.
History
The GAIA Flash Framework was Flash's most popular framework. Its killer feature was automation. It collapsed repetitive Flash plumbing into a few declarative patterns so engineers could focus on the product, and was used on over 100,000 sites at every major digital agency worldwide.
GAIA React carries that automation philosophy into the AI-native era. Where the original automated Flash boilerplate, GAIA automates the Claude workflow (conventions, rules, hooks, gates, wiki) so you can ship features end-to-end without wiring the scaffolding every time.
