/gaia-init

/gaia-init runs automatically during npx create-gaia. It renames the project to your title, sets up language support and how routes load data, removes GAIA’s own branding, sets up CODEOWNERS and your environment file, registers Claude tools and plugins, verifies the build, and commits the result. You get a project that compiles, lints, and tests cleanly.

/gaia-init runs only at the root of a project created by npx create-gaia, and stops with a message anywhere else.

The flow

1. Dependencies

Ensures pnpm (opens in a new tab) is available and new enough. GAIA requires pnpm 12 or later (the version pinned in package.json packageManager). If pnpm is missing, init enables it with corepack enable pnpm, or installs it globally with npm when Corepack isn’t available. If an older major version is on your PATH (for example 11.x), init asks you to confirm the upgrade first. It stops if an older pnpm still comes first on your PATH after the upgrade.
Runs pnpm install in the new project.
Installs Chromium (opens in a new tab), the browser the story and hook tests run in. pnpm install installs no browsers, so without this step the build check in step 4 fails. Init installs only Chromium, without the system libraries some Linux machines also need, so it never asks for your password. It finishes at once when Chromium is already installed.

If either install fails, the run stops and shows the error with the command to retry. Fix the cause and resume (see Resuming after a failure). To install the browsers and the system libraries they need, run pnpm install:browsers yourself in a terminal. On Linux it asks for your sudo password, which Claude cannot type.

Init does not update your dependencies. The project starts on the exact package versions GAIA’s own tests ran against. When packages fall behind or have security advisories, the statusline shows /update-deps, and you run it when you are ready.

2. Questions about your project

Before it asks about your project, /gaia-init asks how you want to answer the setup questions:

Interactive (recommended): GAIA asks each question and waits for your answer.
Automatic: GAIA picks the recommended default for every question. It shows you the full list of chosen values and then carries on without stopping. You can interrupt it, and you can change any setting afterward.

Every question is a menu with the recommended option first. In interactive mode it asks:

Primary language. The main language for your app’s UI. The first option is the language you have been typing in. The second is always a different real language: English when you type in another language, otherwise your system locale’s language, or Spanish. Type any other language, by name (French, Japanese) or code (fr, ja), through the menu’s Other answer.
Additional languages. Keep only the primary language with translation support (i18n) still set up (recommended, so you can add languages later with no rework), add more languages now, or remove i18n entirely. Removing it is hard to undo, so pick it only if you are sure the app will only ever use one language.
GitHub username for CODEOWNERS. GAIA reads your handle from the GitHub CLI (opens in a new tab) you are logged in to (gh api user) and offers it first. Choose Set it later to write a placeholder that /setup-gaia offers to replace before its first push, or type a different handle. If detection fails, GAIA asks you to type your handle rather than guessing.
Project title. Your folder name in title case (for example my-cool-app becomes My Cool App), or the folder name as it is. Type your own title through Other. The slug (the kebab-case name used in package names and paths) comes from the title, so it is never asked separately. To set both, type Title / slug.
Backend field casing. How your backend names JSON fields. camelCase (recommended) passes keys through unchanged. snake_case makes the services convert keys: snake_case in requests and responses, camelCase in your code (create({isSnakeCaseEnabled: true})). Not sure is treated as camelCase.
TanStack Query (opens in a new tab). Off by default: route loaders handle data and nothing extra is installed. Yes installs TanStack Query and sets up its provider and Storybook (opens in a new tab) decorator.

You can change either data answer later by asking Claude:

My backend uses snake_case field names. Switch the data layer to convert them.

Turn on TanStack Query for this project.

The language, title, and identity questions are re-asked until you answer; GAIA never guesses them. The two data questions are asked again once, then fall back to their default.

3. Branding, naming, data layer, and i18n

With your answers, /gaia-init:

Removes GAIA’s branding: it writes a new README.md for your project and puts your title on the Storybook sidebar
Sets up i18n for the languages you chose. GAIA ships English translation files, so init creates starter files for every other language you picked, including your primary language when it is not English
Sets up route data loading for your casing answer, and the TanStack Query provider if you chose to install it
Renames the project to your title and slug
Adds the statusline to the project’s .claude/settings.json

If you removed i18n, it removes all of it cleanly.

To add a language after init, ask Claude. It follows the same steps init uses, which stay in the project for this:

Add <language> to the app.

Removing i18n later deletes those steps too, since adding a language would then first need i18n rebuilt.

4. Project files and build check

Creates .github/CODEOWNERS with your GitHub handle as the repo-wide owner. When it has no real handle, it writes the placeholder REPLACE-WITH-YOUR-GITHUB-HANDLE, and GitHub warns about the unknown owner. /setup-gaia offers to replace it before its first push, with the GitHub login you are signed in to. To set it sooner, ask Claude:
```
Set my GitHub handle in CODEOWNERS. My handle is <your-handle>.
```
Copies frontend/.env.example to frontend/.env. The app’s environment file lives in the frontend/ package; Playwright (opens in a new tab) reads the same file.
Runs the full quality gate from the repository root, pnpm typecheck && pnpm lint && pnpm test:ci && pnpm build (the root scripts run the frontend package), and stops if anything fails. This is the same Quality Gate every later change must pass, so it proves the new project compiles, lints, and tests cleanly. It is the main reason init takes a few minutes.

5. Claude tooling

/gaia-init sets up the outside tools and plugins GAIA uses. GAIA’s skills and rules already ship with the project. You don’t run any of this by hand; it is listed for reference. /setup-gaia runs the same steps on every other machine.

Tools. Installed on each machine, not tracked in the repo:

React Doctor (opens in a new tab): installs the react-doctor skill under frontend/.claude/skills/, so it only loads in sessions that work on the app.
Playwright CLI (opens in a new tab) binary: npm install -g @playwright/cli@latest. The playwright-cli skill that ships with GAIA uses it, and /update-deps reports when it falls behind.

Plugins. The TypeScript language server plugin (typescript-lsp), so Claude can jump to definitions and see type errors.

After installing, /gaia-init checks each one and reports [ok] or [FAIL] for each. A failure stops the run so you can retry before continuing.

6. Team settings

/gaia-init applies GAIA’s two team defaults without asking:

Git isolation policy: always use worktrees. Every /gaia-plan, /gaia-debt, and ad-hoc task works in its own git worktree, so tasks run in parallel without touching each other. See Work lifecycle.
Sandbox recommendation: not recommended, written to .gaia/project.json. Claude Code’s sandbox works with GAIA once you allow the commands it blocks, so it is opt-in. See Sandbox decision.

The file is committed and shared with your team, and /update-gaia never overwrites it. A repo admin changes either setting later with /setup-gaia --reconfigure.

7. Commit

/gaia-init commits its own changes as one commit on the current branch, chore: initialize project with /gaia-init. /setup-gaia pushes only what is committed, and every later branch or worktree starts from the last commit. Committing makes sure nothing init wrote is left behind. If the commit fails, init says so and tells you to review git status and commit before running /setup-gaia.

After gaia-init completes

Init marks this machine’s setup as done and deletes its own one-time setup files. Then it prints:

<Project Title> is ready for development. Exit Claude, then from your terminal:

cd <project-folder-name>

Then start Claude again, and run /setup-gaia. After your first push, /setup-gaia registers the GAIA-Audit required check.

The statusline shows /update-deps when packages are outdated or have security advisories; run it when you are ready.

If .github/CODEOWNERS still holds the placeholder owner, the message opens with a note that /setup-gaia offers to set your handle before its first push (see step 4).

Exit Claude and relaunch from inside the project folder. New plugins and skills only load in a new session.

From there you are ready to build. Run pnpm dev to start the app locally, or ask Claude to run it. When you are ready for GitHub, run /setup-gaia; it creates the GitHub repo for you (or uses one you already created). Onboarding, as you build shows what GAIA does as your first commits and pull requests land.

Resuming after a failure

/gaia-init records its progress as it goes. If a step fails partway through, Claude shows the error, names the cause, and recovers the run itself:

A cause inside the project: Claude fixes it and resumes.
A cause only you can fix, such as a credential, a system package, or a disk or network problem: Claude says what to change and asks whether it is fixed. Choose Fixed, resume and Claude picks up from the failed step. Choose Stop here to finish later.

Init’s scripted steps that already finished are skipped, and the rest run again with the answers you already gave. A failed install or build check is run again by Claude itself. If you stopped, ask Claude to resume when you are ready, before init has finished:

Resume /gaia-init from the step that failed.