Claude is raw power. GAIA is order and focus.
The React workflow that keeps Claude-shipped code production-grade as your team scales. Every convention enforced in code. Every shortcut blocked at the source. Every merge audited before it lands.
- Engineering teams whose AI output is outpacing their review process
- Engineering leads standardizing how Claude works across the org
- Solo developers and agencies who want production-grade defaults from day one
Make sure you have Node.js >= 22.19.0 installed, preferably via nvm, and uv (required for the Serena MCP server — install with curl -LsSf https://astral.sh/uv/install.sh | sh).
npx create-gaia@latest my-appOne simple command. GAIA takes care of the rest.
Most setups treat Claude as a tool you hold. They 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.
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.
Context bloat isn't just CLAUDE.md sprawl. Instructions get dropped into global memory, forgotten, and accumulate into redundancies and conflicts. That invisible cost compounds every session. GAIA keeps token usage minimal by design.
- Coding principles. GAIA's coding rules embed 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. 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.
- Consistently clean code. 20+ ESLint plugins, strict TypeScript, and Prettier enforce style and correctness on every file Claude touches. No negotiation, no drift.
- Test-driven development via the bundled
tddskill. Red-green-refactor loop, tests before code, tailored for Vitest, React Testing Library, StorybookcomposeStory, and MSW. - Code-review audit before every merge. A Claude subagent scans the branch diff for security, performance, code smells, and antipatterns. It 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.
- 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.
/gaia handoff+/gaia pickupreplace re-briefing Claude from scratch at every session start.
Every piece of GAIA's tech stack is pre-configured and wired into the Claude layer.
- 1,592 lint rules across 20+ ESLint plugins, Prettier, and Stylelint, including 85 Stylelint rules that catch the patterns Claude drifts into first: complexity creep, architectural shortcuts, mismatched filenames, broken CSS
- 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
- 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.
- 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 with React Router 7, Tailwind, and react-icons
GAIA wires the patterns into the project itself, not the prompt. Reflection, orchestration, planning, tool-use, retrieval, evaluation. They run the same way every session, every engineer, every model variant, because the project is shaped that way, not because the prompt asked nicely. The six below have the clearest file-level evidence. The features page covers the rest.
| Pattern | How GAIA implements it |
|---|---|
| The Stop Hook | Pre-tool-use hooks intercept dangerous commands at the source. block-main-destructive-git.sh rejects commits and force-pushes against main; block-bare-test.sh blocks watch-mode pnpm test; block-eslint-config-edit.sh forces fixing source instead of silencing rules; pr-merge-audit-check.sh runs before gh pr merge; block-rm-rf.sh blocks destructive file removal; block-env-write.sh and block-secrets-write.sh block writes to env and credential files; block-lockfile-edit.sh blocks direct lockfile edits. All in .claude/hooks/, wired through .claude/settings.json. |
| Resource-Aware Optimization | Model tier follows task complexity. /gaia audit runs Stage 1 (research) and Stage 2 (mechanical apply) on Sonnet (.claude/skills/gaia/references/audit.md). /gaia plan defaults Opus for planning; the code-review audit declares model: sonnet in .claude/agents/code-review-audit.md. |
| Session Isolation | Sub-agents run in fresh contexts via the Agent tool. /gaia plan writes per-task docs into .gaia/local/plans/{slug}/, each self-contained for a fresh-context sub-agent, and offers a git-worktree branch for filesystem-level isolation. /gaia audit splits research and apply across two isolated stages. |
| Routing | Path-scoped rules auto-load only when Claude is editing matching files. .claude/rules/i18n.md activates on app/pages/**/* and app/components/**/*; .claude/rules/api-service.md activates on app/services/**/*. Conditional Bash hooks in .claude/settings.json route commands to specific scripts based on command shape. |
| Multi-Agent Collaboration | code-review-audit is a manager agent that dispatches React Patterns, TypeScript and Architecture, and Translation specialists in parallel from a single tool-call message, plus react-doctor. Extension files in .claude/agents/code-review-audit/*.md inject library-specific rules into the right subagent at runtime. |
| Guardrails & Safety | Filesystem deny list in .claude/settings.json covers Read(.env), Read(**/secrets/*), Read(**/*credential*), Read(**/*.pem), Read(**/*.key). Tool allow list scopes Bash and Edit surfaces. Block hooks reject debt-accumulating patterns at the source. The audit's security dimension covers XSS, SSRF, IDOR, secret exposure, timing attacks, and dependency vulns. |
GAIA ships clean. /gaia-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
corepackand runspnpm installfor 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, andclaude-obsidian.
After /gaia-init finishes, you have a clean app shell and a fully-configured Claude workflow ready to use.
GAIA ships a complete, opinionated Claude Code workflow. Everything is wired in .claude/ and visible in the repo.
| Command | What it does |
|---|---|
/gaia plan | Plan a complex feature. Claude structures the work, you approve, then an orchestrator drives focused subagents through execution |
/gaia audit | Audit memory, wiki, and autoloaded files for duplication, conflicting instructions, and bloat |
/gaia handoff | Generate a comprehensive session handoff document so you can clear the context with confidence that nothing will get lost |
/gaia pickup | Restore context from handoff and continue work |
- 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,eslint-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.
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.
GAIA keeps package dependencies and GAIA itself up to date. At session start, a background check runs; when updates are available, Claude will ask if you want to update now or later.
GAIA will update outdated packages, handle breaking-change migrations, and run the quality gate to make sure everything still works as expected.
When GAIA itself is updated, it will pull the latest version and perform three-way merges on affected files so any customizations or natural drift over the lifetime of a project survive.
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 /gaia-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.
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.
Ask Claude to run, add, or debug tests. Vitest, Storybook + Chromatic, and Playwright are all wired up.
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.
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.