GAIA

Appearance

Quick start: your first ticket ​

You'll learn the whole loop once, end to end: install the CLI, connect a repository, start a conductor, create a ticket, watch an agent work it, and confirm the result.

Before you start ​

  • A GAIA control plane you can reach: its base URL, an OAuth client secret, and a project on it that your repository maps to — from whoever runs the control plane.

  • Node.js ≥ 20.19 and herdr, the terminal workspace the conductor hosts agent sessions in.

  • A coding agent CLI, installed and logged in on this machine — Claude Code by default (the conductor launches claude; other agents are addons, see Choose the coding agent).

  • The GAIA skills, which the agent reads to work a ticket. For Claude Code they come as a plugin from GAIA's own marketplace:

    /plugin marketplace add https://git.key-tec.de/keytec/gaia.git
/plugin install gaia@gaia

  • A repository with a WORKFLOW.md (Author WORKFLOW.md) and an environment its worktree hooks can bring up — the generated engine config assumes a DDEV project; a different stack changes two lines, see step 2.

Budget ten minutes.

1. Install the CLI ​

sh
npm install -g @gaia-ai/gaia
gaia --help

You should see the four commands: conductor, ui, dropsh, deployment. Details: Install the CLI.

2. Connect this machine and your repository ​

Run this once, in the repository root. It onboards the machine (base URL, your short user id, the client secret) and scaffolds the repository's committed engine config in one go:

sh
cd /path/to/your/repo

GAIA_CLIENT_SECRET='…' gaia conductor init \
  --base-url https://gaia.example.com \
  --project my-project \
  --user-id ada \
  --secret-env GAIA_CLIENT_SECRET

Open the generated .gaia/conductor.config.js once. Two lines matter now:

  • states: ['spec', 'diagnose', 'coding', 'review'] — the states this conductor serves. qualification is deliberately not among them: a hand-written ticket waits for a human or an agent to qualify it. Step 5 uses the agent path, so leave this as it is.
  • hooks: { after_create: 'ddev init-worktree', after_done: 'ddev delete -Oy' } — the commands that bring a worktree's environment up and down. Right for a DDEV project; for anything else, replace them with your own or an empty hooks: {}.

Then log in both profiles and check them:

sh
gaia dropsh auth login --provider session
gaia dropsh auth login --provider pm
gaia dropsh auth status

You should see session: valid and pm: valid. Commit .gaia/conductor.config.js. Details: Connect a repository.

3. Start a conductor ​

sh
gaia conductor start
gaia conductor status

start hands the loop to herdr and returns; status prints one line for this checkout's conductor — its machine id, online, the project, and the workspace root. From now on the conductor polls the control plane for tickets that carry it. Details: Run a conductor.

4. Open the cockpit ​

sh
gaia ui

The Dashboard opens: ticket and run activity over the last 24 hours, 7 days and 30 days. Press Tab to reach Projects, move to your project with the arrow keys and press Enter. You are on the project's Dashboard; Tab again shows its Tickets. Details: Using gaia ui.

5. Hand a ticket to the agent ​

Press n. The New ticket popup opens on your project. Type a title and a one-line description for a deliberately small first task — one whose result you can check by eye:

Title: Add a hello page to the docs Description: Create docs/hello-gaia.md with one sentence that says this repository is worked by GAIA. Nothing else changes.

Leave the workflow at gaia_feature, add the work:code label, and leave the Conductor preselected — it is your own machine's conductor, found from this checkout. Then press Ctrl+S, Create with agent.

A ticket-create agent starts in the project's Ticket-Agents tab. It reads your input, asks only for what is missing, creates the ticket, publishes its qualification handoff — the acceptance criteria the work will be held to — and writes the ticket's state to spec. Because the ticket carries your conductor, your conductor claims it at its next poll.

Why not "Create directly"?

Ctrl+D writes the ticket as typed, into qualification — a state the generated conductor does not serve, so it would wait there for a human. Add 'qualification' to states if you want your conductor to qualify tickets itself. Create a ticket compares the paths.

6. Watch the run ​

Open the ticket — Enter in the list, or from any shell:

sh
gaia ui GAIA-1        # your identifier will differ

On the ticket's Runs tab a run appears: claimed, then running, with your machine as its claim. In herdr, a tab named GAIA-1 · spec #<run> holds the agent session. The agent writes the design, the plan and the test plan as comments, then asks you to confirm them — in its tab, which herdr marks blocked until you answer. Confirm, and it writes coding. That state write ends the run; the conductor claims the ticket again for coding, and a fresh run and tab appear.

The agent pauses for you at three points, each in its own tab: to confirm the plan at spec, to confirm the result and choose review at coding, and to confirm the verdict at review. Details: Run a ticket: from claim to done.

7. Done ​

When you confirm an OK review, the agent writes done. docs/hello-gaia.md exists on the ticket's branch, the merge request the coding step opened is linked on the ticket, the Dashboard's counts move, and the ticket leaves the default list (which hides closed tickets). The worktree the runs used is torn down by the conductor's cleanup — or right now with:

sh
gaia conductor reap

That was the loop: a state write at each step, a run per state, one board that is always the truth.

Next ​