# GAIA React: A Claude-Native Foundation That Treats AI as a Managed Engineer

> GAIA React is a starter kit and workflow layer that enforces coding standards, automated tests, and code-review audits on every Claude-generated change. It is for teams whose AI output is outpacing their human review process, but its strict tooling and opinionated defaults are not for everyone.

**gaia-react/gaia** — The Claude-native foundation you build your whole app on. React frontend handled, your backend builds on top. Strict tooling, pre-commit gates, code-review audit before every merge.

- Repository: https://github.com/gaia-react/gaia
- Website: https://gaiareact.com/
- Stars: 25 · Forks: 4
- Language: Shell
- License: MIT
- Published: 2026-08-24 · Updated: 2026-08-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/gaia-react-gaia

## What GAIA React Actually Solves

GAIA React addresses the problem of AI-generated code outpacing human review. The README describes the target user as engineering teams whose AI output is outpacing their review process and leads who want to standardize how Claude works across the org. The core claim is that most setups treat Claude as a tool you hold, bolting a CLAUDE.md onto the root and hoping the model figures out the rest. GAIA treats Claude as an engineer you manage. That shift means every convention is enforced in code, every shortcut is blocked at the source, and every merge is audited before it lands. The specific pain points it names are trust, token economics, and compounding tech debt. Trust is about predictability: without enforceable conventions, Claude reverts to its training distribution, which the README calls an average of every codebase on the internet. Token economics is about context bloat from sprawling instructions that accumulate into redundancies. Tech debt is about dependencies falling behind and the wiki drifting from the code. GAIA's answer is to make the codebase itself the standard and to run maintenance continuously.

## The Mechanism: Enforced Rules, Not Hopes

The mechanism is a combination of static rules, pre-commit gates, and a code-review audit. The README lists 1,450 lint rules, strict TypeScript, Prettier, and Knip for dead-code detection. These run on every file Claude touches. The quality gate before commit requires typecheck, lint, tests, and build to all pass. Not 'mostly clean,' as the README stresses. The rules encode conventions directly instead of hoping Claude infers them from the repo. That includes blocking debt-accumulating patterns like untyped exports, untested components, hardcoded strings, and a11y gaps. The pre-commit hooks are part of the tooling that the create-gaia CLI sets up. There is also a filesystem deny list that blocks reads of .env, secrets, credential files, .pem, and .key files. A tool allow list scopes Bash and Edit surfaces. Pre-tool-use hooks reject dangerous commands such as destructive git on main and watch-mode pnpm. The design is to stop bad patterns at the source rather than fix them after the fact.

## How the Claude Workflow Is Structured

The workflow is built around a spec-first process. The /gaia-spec command authors an immutable SPEC artifact through what the README calls Socratic discovery. Before any source code is written, the SPEC's user acceptance tests (UATs) render as red-state Playwright e2e specs. The implementer's first job is turning those red tests green. This is a test-driven development loop that GAIA enforces as one of its own principles, alongside Karpathy's four coding principles: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. The tdd skill drives a red-green-refactor loop tailored for Vitest, React Testing Library, Storybook composeStory, and MSW. The spec-kit lifecycle hooks include a constitution check, self-review, immutability lint, Playwright UAT auto-write, and wiki-promote. The README says the PO writes acceptance criteria in plain English, and the test harness is generated. That is a strong claim: it means the human writes the criteria, and the tests come out of the spec.

## Getting It Running: Commands and Requirements

The quick start is a single command: npx create-gaia@latest my-app. The README explicitly warns not to clone or fork the repository, because the CLI strips GAIA branding and release tooling and points everything at the correct repo. A clone leaves all of that in place and pointed at the wrong repo. The CLI sets up the project, then you run /gaia-init to finish the last-mile setup. That command configures the project title, package name, docs title, CODEOWNERS, and localized site titles. It installs dependencies via pnpm, bootstrapped through corepack. It configures i18n, prompting for your language set and scaffolding matching language files. It installs Claude skills, plugins, and MCP servers: React Doctor, Playwright CLI, typescript-lsp, claude-obsidian, and Serena (an LSP-backed symbol search). It also initializes spec-kit with the bundled GAIA extension and preset. Requirements are Node.js >= 22.22.0, with nvm recommended, and macOS or Linux. On Windows, you need WSL2 because the hooks and CLI need bash and POSIX file paths. uv is required for the Serena MCP server, but GAIA installs it during setup if you don't have it.

## The Code-Review Audit: A Manager Agent That Blocks Merges

The most distinctive feature is the code-review audit before every merge. A manager agent scans the branch diff for security issues like XSS, SSRF, IDOR, secret exposure, timing attacks, and dependency vulnerabilities. It also checks performance, architecture, code smells, and antipatterns. Three specialists run in parallel: React Patterns & Accessibility, TypeScript & Architecture, and Translation. Alongside them, react-doctor and knip run, but their output is advisory and never blocks. The findings are tiered as Critical, Important, and Suggestions. The merge blocks until no Critical or Important issues remain. The audit runs locally by default, and in CI once you enable GAIA CI. The README mentions extension files in .claude/agents/code-review-audit/ that inject library-specific rules at runtime. This is a heavy process. It means every merge has a multi-agent review, which is a significant token cost. The README does not disclose what that cost is, so teams need to budget for it. The blocking behavior is a trade-off: it ensures quality but can slow down delivery if the audit produces false positives or if the specialists are too strict.

## Limitations and When It Is the Wrong Tool

GAIA React is not a lightweight starter. The strict tooling is the point, but it comes with constraints. First, the platform requirement: macOS or Linux only, with WSL2 on Windows. That excludes developers on native Windows. Second, the Node.js version requirement is high: >= 22.22.0. Teams on older LTS versions will need to upgrade before they can use the CLI. Third, the token economics are a double-edged sword. The README claims GAIA keeps token usage minimal by design, but the spec process and the code-review audit with three parallel specialists are token-heavy operations. The README does not provide numbers, so the claim of minimal tokens is unverified. Fourth, the workflow is opinionated. It mandates TDD, and it blocks merges on Critical or Important findings. If your team does not want to write tests first or if you prefer a more flexible review process, GAIA will fight you. Fifth, the README is truncated, so the full list of guardrails and the exact behavior of the deny list are not fully visible. That means some operational details are unknown. For a solo developer who just wants a React shell, GAIA is overkill. For a team that does not have a strong review culture, the audit might be a bottleneck rather than a safety net.

## Alternative Approaches: Enforced vs. Advisory

The most direct alternative is the bolt-on approach the README criticizes: adding a CLAUDE.md to a standard React starter and letting Claude infer conventions from the repo. That approach is advisory, not enforced. It relies on the model's ability to follow instructions and on human review to catch violations. GAIA's difference is that it makes the conventions mechanical through lint rules, pre-commit hooks, and a merge-blocking audit. Another alternative is a generic AI-assisted development workflow with tools like GitHub Copilot and a CI pipeline that runs lint and tests. That pipeline is similar to GAIA's quality gate, but it does not include the spec-kit lifecycle or the manager agent audit. The key difference is the audit's scope: it scans for security and architecture issues, not just style and correctness. A team could replicate parts of GAIA with a CLAUDE.md, a set of ESLint configs, and a CI script, but they would have to assemble and maintain those pieces themselves. GAIA packages them into a single foundation, which is the value proposition. The trade-off is that you inherit GAIA's opinions, and you have to trust that the bundled rules match your project's needs.

## Maintenance, Upgrades, and License

The project is under the MIT license, which is permissive and allows commercial use, modification, and distribution. The repository is actively maintained, with recent releases including v1.6.1, v1.6.0, and v1.5.0 in June 2026. The README does not describe a specific upgrade path, but the CLI-based setup suggests that upgrades might involve re-running create-gaia or pulling new versions of the CLI. The README also mentions that GAIA runs maintenance continuously to prevent tech debt, which implies the project itself has automated dependency checks. However, the exact mechanism is not detailed in the provided material. The maintenance cost for a user is likely tied to the tooling: you need to keep Node.js, pnpm, uv, and the Claude skills up to date. The skills and MCP servers are external dependencies, so their updates are outside GAIA's control. The code-review audit runs locally by default, which means it consumes your local resources and tokens. Enabling GAIA CI would move that to CI, but the README does not specify the CI configuration details. The license implications are straightforward under MIT, but you should verify the licenses of the bundled skills and MCP servers, as they are separate projects.

## Conclusion

Adopt GAIA React if you are an engineering lead standardizing Claude workflows across a team and you can commit to its strict gates: 1,450 lint rules, mandatory TDD, and a merge-blocking audit. Do not adopt it if you want a lightweight starter or if you cannot run Node.js >= 22.22.0 on macOS or Linux (or WSL2), because the hooks and CLI are POSIX-only. Before adopting, verify that your team can tolerate the token cost of the Socratic spec process and that you are willing to let the manager agent block merges on Critical or Important findings. The real value is the enforced discipline, not the React shell, so treat the shell as replaceable and judge GAIA on its workflow alone.

## FAQ

### Who is Gaia owned by, in relation to the gaia React foundation?

Those questions are about a different Gaia. gaia-react/gaia is a React workflow for Claude Code, MIT licensed, authored by Steven Sacks, with the project site at gaiareact.com. It is a project template rather than a hosted product.

### What is the Gaia 2.0 theory, and does this repository cover it?

Nothing on record concerns a theory. This repository is a React foundation for Claude Code with strict tooling, pre-commit gates, and a code-review audit before every merge, started from npx create-gaia@latest my-app.

### Is Gaia a free app, and is there a paid tier?

No pricing appears anywhere on record. What is documented is the license, MIT, and the runtime requirements: Node.js 22.22.0 or newer, macOS or Linux, WSL2 on Windows, and uv for the Serena MCP server.

### What is Gaia in AI, and what does it actually enforce?

It is a foundation for AI-assisted development rather than a model. It enforces 1,450 lint rules, strict TypeScript, Prettier, and Knip, and blocks a merge until no Critical or Important audit findings remain, with Suggestions left advisory.

## Sources

- [Official documentation](https://gaiareact.com/)
- [Official README](https://github.com/gaia-react/gaia#readme)
- [Project repository](https://github.com/gaia-react/gaia)
- [Release notes](https://github.com/gaia-react/gaia/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gaia-react-gaia