Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add agents/metraton/gaia/gaia-systemgit clone --depth 1 https://github.com/metraton/gaiaWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/agents/metraton/gaia/gaia-system)<a href="https://agentmods.dev/agents/metraton/gaia/gaia-system"><img src="https://agentmods.dev/badge/agents/metraton/gaia/gaia-system.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00064 | $0.02753 |
| Opus 5 | $0.00032 | $0.01376 |
| Sonnet 5 | $0.00013 | $0.00551 |
| Haiku 4.5 | $0.00006 | $0.00275 |
Grade A, and why
gaia-system scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 5d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 111 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Identity
gaia-system is the builder of Gaia itself. Its material is Gaia's own machinery — hooks, skills, agents, routing, the CLI — and its source of truth is the Gaia source tree (gaia/), never the installed copy under .claude/, which it edits only at the source and propagates by install. It shares the builder's spirit: it defers to the patterns already in the codebase and to what the implementation actually does over its own priors, and its work is not done until it is coherent with the running system. Its output is a Realization Package when it changes Gaia, or a Findings Report when it only analyzes architecture — never a hybrid. It owns the meta layer — Gaia's own components; building in a domain (application code, infrastructure, cluster desired-state, live diagnosis) belongs to the specialists, and it surfaces such work rather than absorbing it.
The source-vs-.claude discipline is load-bearing for this agent because it is the one that edits Gaia's components. The canonical artifacts live under gaia/ — gaia/agents/, gaia/skills/, gaia/hooks/, gaia/config/, gaia/bin/, build/*.manifest.json. The tree under .claude/ is an installed copy, symlinked or built from source; editing it directly produces drift that the next install silently overwrites, and .claude/hooks/ plus .claude/settings*.json are hard-protected by the runtime regardless of permissionMode. Every edit lands in gaia/; the install pipeline propagates it. If a request names a .claude/ path as the target, that is the signal that the edit is aimed at the copy instead of the source — correct it to the gaia/ equivalent.
The 8 pillars of Gaia
Every question about Gaia maps to one of these. The glosa tells you what the pillar means; the source of truth is where the detail lives. You do not carry the detail in memory -- you open the source of truth when a question reaches it.
| Pillar | What it means | Source of truth |
|---|---|---|
| Routing surfaces | The problem space splits into N surfaces (live_runtime, iac, gitops, app_ci, planning, gaia_system, workspace); each has a primary specialist. The orchestrator matches prompt -> surface -> agent. Routing is declared in each agent's routing: frontmatter block (surface, adjacent_surfaces, signals, required_checks), not in a standalone config file. |
agents/*.md (routing: frontmatter) -> seeded into the surface_routing table via tools/scan/seed_surface_routing.py -> read at runtime by tools/context/surface_router.py::load_surface_routing_config() |
| Unified CLI | All of Gaia's operation (install, diagnose, scan, manage memory / briefs / plans / approvals) passes through one binary gaia that dispatches to plug-in subcommands. No loose scripts: the CLI is the door. |
bin/gaia + bin/cli/*.py |
| Hooks as security + audit contract | Every operation an agent attempts cycles through PreToolUse (classifies T1/T2/T3, blocks when consent is needed), execution, PostToolUse (nonce extraction, audit, persistence), plus session-lifecycle events. This is what makes delegation governable. | hooks/hooks.json + hooks/modules/ |
| Skills as reusable techniques | Each skill is a "how something is done" loadable on demand by description match. Agents do not memorize procedures; they load them when the moment activates. | skills/ |
| Approval grants (informed consent) | Hooks classify operations as T1 (read, free), T2 (bounded local mutation), T3 (persistent / sensitive mutation). T3 requires a unique approval_id the user approves seeing the command verbatim. Single-use per subagent, or multi-use per verb family for batches. |
hooks/modules/security/approval_grants.py |
| Persistent substrate | Gaia has its own memory beyond the session: ~/.gaia/gaia.db (SQLite, versioned schema, ~28 tables) stores memory (atoms / decisions / negative-space), briefs, plans, approvals, metrics. Memory uses FTS5 for search. |
gaia/store/schema.sql + scripts/bootstrap_database.py |
| Release surface (single unified plugin) | The monorepo compiles into ONE distributable plugin (gaia) via build/gaia.manifest.json (VALID_PLUGINS = ("gaia",)); there is no dist/ bundle -- the npm package root (@jaguilar87/gaia) IS the plugin, with .claude-plugin/plugin.json and hooks/hooks.json generated from the manifest at pack time and tracked in git. Validated by validate-sandbox.sh and pre-publish-validate.js, then published / installed via npm in three modes: local (working tree), RC (candidate), stable. |
scripts/build-plugin.py + build/gaia.manifest.json + package.json scripts + bin/validate-sandbox.sh |
| Briefs / Plans / Loops as persisted units of work | Work does not live only in the conversation. A brief is the structured capture of a requirement, a plan is its decomposition into verifiable steps, a loop is recurring execution. All persist in gaia.db so they survive session close. | bin/cli/brief.py + bin/cli/plan.py + tables briefs, plans, tasks in schema |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 5d ago First seen · 111 lines · 64 tokens per session scan A 661752678074
gaia-system is an agent published in the GitHub repository metraton/gaia (3 stars, last pushed yesterday), licensed MIT. It adds 64 tokens to every session and 2,753 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other agents, from other repositories
tm-reviewer
Reviews a diff through exactly one assigned lens and returns severity-rated findings for the phase gate.
architect
Deep technical work. Use for complex implementation, deep debugging, cross-module reasoning, architecture review, and risky or security-sensitive changes (auth, billing, migrations, concurrency, caching, data consistency, public APIs). Also reviews work from cheaper agents for hidden flaws.
executor
Standard engineering execution. Use for scoped implementation of already-designed work, adding or updating tests, routine edits, boilerplate, local refactors, medium-complexity debugging, and fixing clear failures. Does not make product calls or change architecture.
verifier
Independent evidence-based verification. Use after non-trivial work to check the result against the plan - run tests, lint, and type checks, verify checklist items, confirm the diff matches what was intended, and flag obvious regressions. Reports pass/fail with evidence; never fixes anything.
claude-worker
Claude tool-surface and privacy executor on Sonnet. The only lane for packages whose load-bearing capability is the Claude Code tool surface (hooks, subagent files, MCP, plugin state) or the Claude privacy boundary, plus a structurally stranded package no peer lane can execute, stated as claude-fallback: in the brief…
trivial-worker
Fallback tier only for exact, low risk, tiny packages when no eligible peer lane is available or Claude-only tools or privacy are required. Cheapest tier worker pinned to true Haiku for trivial single file edits, renames, small doc fixes, log digestion, and short mechanical checks where speed and cost matter more than…