@gaia-ai/gaia

The GAIA conductor + client CLI, published as a single self-contained npm package. Install it globally and run gaia anywhere — no repo clone, no local build (no pnpm, no tsc).

Install

npm install -g @gaia-ai/gaia

The unscoped name gaia is taken on npm, so the package is scoped @gaia-ai/gaia. The executable stays gaia (via the bin entry), so every command is just gaia ….

gaia --help

What it does

gaia is the conductor node and client for a GAIA network: it registers with a Drupal control plane, claims tickets over JSON:API, and runs agents through spawn plugins (Claude, Codex, herdr, and a deterministic fake for tests). Point it at a control plane with a conductor.config.js (scaffold one with gaia init).

gaia ui deep links

gaia ui is the interactive terminal cockpit, and it takes an optional target so you open the thing you are working on directly:

gaia ui GAIA-221                  # a ticket by identifier (case-insensitive)
gaia ui project:gaia              # a project; also ticket:<uuid> · run:<uuid>
gaia ui --here                    # this branch's ticket, else this repo's project
gaia ui GAIA-221 --view teaser    # a compact block instead of the tabbed detail

At most one target source (the positional, --ticket, --project, --run, --here); two exit non-zero naming both. --here reads the current branch for a ticket identifier and otherwise resolves this repo's git remote against the projects that claim it — several claimants open a picker. gaia ui --help lists every form.

Plugins

The four spawn plugins ship inside this package — nothing extra to install. Import them from the @gaia-ai/gaia/plugins entry in your conductor.config.js:

import {
  drupalRemote,
  herdrWorkspace,
  claudeAgent,
  herdrExecutor,
} from '@gaia-ai/gaia/plugins';

Plugin authors can build against the API surface at @gaia-ai/gaia/plugin.

Releasing (maintainers)

Publishing is automated: push a git tag matching v*.*.* on main and CI runs the publish job (npm publish --access public). The published version is the tag. Requirements:

• an NPM_TOKEN masked CI/CD variable with publish rights to the @gaia-ai scope;
• the @gaia-ai npm org/scope claimed (fallback @keytec/gaia).

To reproduce the published artifact locally:

pnpm run prepare:publish   # stage conductor/publish/ + each plugins/*/publish/
pnpm run verify:package    # pack the staged set, install it in a temp dir, smoke-test

License

MIT — see LICENSE.