GAIA React

Claude as your lead engineer. GAIA is the React Router template that makes Claude trustworthy enough to own features end-to-end, token-efficient enough to do it at scale, and grounded enough in the stack to answer how-do-I questions without re-reading the codebase.

Built on React Router, Tailwind v4, Vitest, Playwright, Chromatic, Storybook, i18n, Conform + Zod forms, dark mode, MSW, and 20+ ESLint plugins. Every piece is pre-configured and documented for Claude in a way that keeps per-request costs down and output quality up.

Who it's for

• Solo developers shipping Claude-built projects
• Product teams standardizing how Claude works across the org
• Agencies that want a templated starting point for client work

If Claude writes most of your code, GAIA is the substrate that makes it trustworthy.

Quick Start

Make sure you have Node.js >= 22.19.0 installed, preferably via nvm.

npx create-gaia my-app

This pulls the latest tagged release (scrubbed of dev notes), sets up .gaia/VERSION for later /gaia-update runs, and git inits your project. Then open Claude Code in the project and run /gaia-init to configure i18n, strip GAIA branding, and install Claude plugins.

Documentation

The two problems GAIA solves

Most templates 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 two 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. With GAIA, Claude writes code that follows best practices on day one — and 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 — an invisible cost that compounds every session. GAIA keeps token usage minimal by design.

How GAIA makes Claude trustworthy

• Best practices are baked in, not pattern-matched. Rules encode the conventions directly instead of hoping Claude infers them from whatever's already in the repo.
• Guardrails against technical debt. Rules block debt-accumulating patterns from being written in the first place — untyped exports, untested components, hardcoded strings, a11y gaps.
• Test-driven development via the bundled tdd skill. Red-green-refactor loop, tests before code — tailored for Vitest, React Testing Library, Storybook composeStory, and MSW.
• Code-review audit before every merge. A Claude subagent scans the branch diff for security, performance, code smells, and antipatterns — and blocks the merge until the issues are fixed and committed.
• Quality gate before commit — typecheck, lint, tests, and build must all pass. Not "mostly clean" — actually clean.

How GAIA keeps Claude token-efficient

• Rules are scoped to activate only when needed. Claude loads the ones that match what it's editing — nothing else.
• Obsidian wiki, fetched on demand. Project knowledge lives as focused, linked Markdown pages. Claude opens the one page it needs — "How does dark mode wire through?" — instead of preloading the whole manual.
• Wiki behavior tailored to GAIA. Session hooks keep Obsidian's workflow (ingest cadence, cache discipline, link hygiene) aligned with the project's conventions.
• Periodic knowledge audit sweeps memory, wiki, and autoloaded files for duplication, conflicts, and stale instructions before they start costing tokens.
• Session continuity. /handoff + /pickup replace re-briefing Claude from scratch at every session start.

What Claude rides on (the foundation)

GAIA bundles the traditional stack Claude's output rests on. Every piece is pre-configured and wired into the Claude layer.

• 20+ ESLint plugins with Prettier and Stylelint for consistent code from the first commit
• Pre-commit hooks (Husky + lint-staged) — typecheck, lint, and test before CI
• Four testing layers sharing one mock layer — Vitest + React Testing Library for unit/integration, Playwright for E2E, Chromatic for visual regression
• i18n in 2 languages 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
• Storybook with React Router + i18n + dark mode + MSW integration
• API mocking with Mock Service Worker and msw/data, working handlers for tests and Storybook
• Toast notifications with remix-toast and Sonner
• Built on React Router 7, Tailwind v4, and FontAwesome icons

How GAIA Compares

Opinionated starter templates solve different slices of the "day-zero engineering setup" problem. GAIA focuses on making Claude a first-class collaborator.

Foundation

Claude-native

Only GAIA comes with Claude tooling built-in. It includes path-scoped rules, enforcement hooks, useful commands and skills, a code-review audit agent, and Obsidian wiki integration.

Agentic Design

Agentic design is the discipline of building AI systems that act autonomously toward goals rather than passively responding to prompts. The canonical patterns — Reflection, ReAct, Planning, and Multi-Agent collaboration — are all first-class in GAIA.

Principles including Autonomy, Tool Use, Memory & Context, and Exception Handling & Recovery are each enforced structurally. Scoped rules bound Claude's decision space; ESLint, Vitest, Playwright, and MSW are Claude's tool layer; the Obsidian wiki and /handoff + /pickup provide persistent memory; and the quality gate plus code-review audit are mandatory checkpoints before commits and merges.

One-Command Initialization

The template ships clean. /init finishes the last-mile setup:

• Configures your project — prompts for a title, sets the package name, docs title, CODEOWNERS, and localized site titles
• Installs dependencies — bootstraps pnpm via corepack and runs pnpm install for you
• Configures i18n — prompts for your language set, scaffolds the matching language files, and updates the component and Storybook wiring
• Installs Claude skills and plugins — React Doctor, Playwright CLI, typescript-lsp, and claude-obsidian

After /init finishes, you have a clean app shell and a fully-configured Claude workflow ready to use.

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. Ask Claude about any of them — they're in .claude/rules/.
• Hooks guard the quality gate and keep the wiki fresh. Ask Claude what they do.
• Bundled skills (typescript, react-code, tailwind, skeleton-loaders, tdd, playwright-cli) autoload for matching tasks.

Code review before merge

Every merge runs through a code-review pass against the branch diff — security, performance, code smells, antipatterns — and blocks until the issues are fixed and committed.

Wiki

GAIA ships with an Obsidian wiki knowledge base — architecture, modules, dependencies, decisions, flows, concepts — committed to git and shared across the team. The claude-obsidian plugin (installed by /init) adds /wiki-ingest, /wiki-query, /wiki-lint, /autoresearch, and /save for working with the vault. Open wiki/ in Obsidian for graph view, backlinks, and search.

Development

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.

Extend:

• Rules, hooks, skills, and commands live in .claude/. Ask Claude to add, modify, or explain any of them.

Testing

Ask Claude to run, add, or debug tests — Vitest, Storybook + Chromatic, and Playwright are all wired up.

Deployment

GAIA isn't prescriptive about hosting. Ask Claude to set up your deployment for the target you want — Vercel, Cloudflare, Fly, AWS, a bare Node host, a Docker container, anywhere React Router can run. Claude will wire up the build, environment variables, and any CI/CD you need.

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, this template automates the Claude workflow — conventions, rules, hooks, gates, wiki — so you can ship features end-to-end without wiring the scaffolding every time.