README
Gaia
General Agentic Integration Architecture
Cómo leer este repo
Gaia is event-driven. Every capability in the codebase is attached to a moment in the Claude Code lifecycle — a prompt arriving, a tool being called, an agent completing. Reading the folder structure without that lens makes it look like a collection of files. Reading it with that lens, everything clicks into place.
The flow is this: a user sends a prompt, the UserPromptSubmit hook fires and injects the orchestrator's identity and a routing recommendation. The orchestrator picks a specialist agent and dispatches it. Before that agent's first tool call lands, the PreToolUse hook intercepts it — injecting context, validating permissions, blocking dangerous commands. The agent does its work and returns a json:contract. The SubagentStop hook fires, validates the contract, records metrics, and writes to episodic memory.
UserPromptSubmit -> routing -> PreToolUse -> agent -> PostToolUse -> SubagentStop
| | | | | |
identity surface- security json:contract audit log metrics +
injection routing.json gate + memory
context
injection
That pipeline is the spine. Everything else in this repo is either a component of that pipeline (hooks/, agents/, skills/, config/) or infrastructure that supports it (build/, bin/, tests/, templates/). Start with the folder that matches the behavior you want to understand, and its README will tell you where it fits in the flow.
Overview
Gaia is a multi-agent orchestration system for DevOps automation. It ships two sub-plugins — gaia-ops (full orchestrator) and gaia-security (security-only) — with security-first command classification, specialized AI agents, and plugin-based distribution. Currently integrates with Claude Code.
Features
- Multi-cloud support - GCP, AWS, Azure
- 8 agents - terraform-architect, gitops-operator, cloud-troubleshooter, developer, gaia-planner, gaia-operator, gaia-orchestrator, gaia-system (meta-agent)
- Contracts as SSOT - Cloud-agnostic base contracts with per-cloud extensions (GCP, AWS)
- Dynamic identity - Orchestrator identity defined in
agents/gaia-orchestrator.md, activated viasettings.jsonagent config; skills loaded on-demand - Dual-barrier security - Settings deny rules (Claude Code native) + hook-level blocking (inalterable via symlink)
- Indirect execution detection - Catches
bash -c,eval,python -cwrappers that bypass regex patterns - Approval gates for T3 operations via native
askdialog - Git commit validation with Conventional Commits
- 32 skills - Injected procedural knowledge modules for agents (protocol, domain, workflow)
- Episodic memory -
gaia memoryCLI with FTS5 search, episode inspection, and session context orientation - Context evals - pytest-driven agent evaluation (5 graders, 3 backends, 10 scenarios, baseline + drift detection)
- Plugin + npm - Distributable as Claude Code native plugin or npm package
- Enterprise ready - Managed settings template for organization-wide deployment
Installation
Via Claude Code Plugin (recommended)
# Add the marketplace
/plugin marketplace add metraton/gaia
# Install the full system (includes security)
/plugin install gaia-ops
# Or install security only
/plugin install gaia-security # Security hooks only
Via npm (advanced setup)
npm install @jaguilar87/gaia
npx gaia-scan
Quick Start (npm)
# Run directly with npx
npx gaia-scan
# Or install globally
npm install -g @jaguilar87/gaia
gaia-scan
This will:
- Auto-detect your project structure (GitOps, Terraform, AppServices)
- Create
.claude/directory with symlinks to this package - Generate
project-context.json - Create
settings.jsonwith hooks only (no permissions in settings.json) - Merge deny rules + allow permissions into
settings.local.json(preserves existing user config)
No CLAUDE.md is generated -- orchestrator identity lives in agents/gaia-orchestrator.md and is activated via settings.json: { "agent": "gaia-orchestrator" }.
Settings Architecture
Gaia separates hooks from permissions: