https://github.com/metraton/gaia
GAIA-Ops — General Agentic Integration Architecture. Multi-agent DevOps system that classifies every operation by risk, routes work to specialist agents, and blocks irreversible commands automatically.
https://github.com/metraton/gaia
ai-agents claude-code devops gaia-ops orchestration security
Last synced: 8 days ago
JSON representation
GAIA-Ops — General Agentic Integration Architecture. Multi-agent DevOps system that classifies every operation by risk, routes work to specialist agents, and blocks irreversible commands automatically.
- Host: GitHub
- URL: https://github.com/metraton/gaia
- Owner: metraton
- License: mit
- Created: 2025-11-10T22:26:17.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-06-06T20:14:04.000Z (14 days ago)
- Last Synced: 2026-06-06T22:09:16.802Z (13 days ago)
- Topics: ai-agents, claude-code, devops, gaia-ops, orchestration, security
- Language: Python
- Size: 6.07 MB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Gaia
> **G**eneral **A**gentic **I**ntegration **A**rchitecture
[](https://www.npmjs.com/package/@jaguilar87/gaia)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
## 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 `agent_contract_handoff`. The `SubagentStop` hook fires, validates the contract, records metrics, and writes to episodic memory.
```
UserPromptSubmit -> routing -> PreToolUse -> agent -> PostToolUse -> SubagentStop
| | | | | |
identity surface- security agent_contract_handoff 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/`). 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** - platform-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 via `settings.json` agent 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 -c` wrappers that bypass regex patterns
- **Approval gates** for T3 operations via native `ask` dialog
- **Git commit validation** with Conventional Commits
- **32 skills** - Injected procedural knowledge modules for agents (protocol, domain, workflow)
- **Episodic memory** - `gaia memory` CLI 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)
```bash
# 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)
```bash
npm install @jaguilar87/gaia
```
The `npm install` postinstall script bootstraps the database, creates `.claude/`, writes symlinks, and registers the plugin. Run `gaia doctor` afterward to verify.
### Quick Start (npm)
```bash
# Install and bootstrap (postinstall does the rest)
npm install @jaguilar87/gaia
# Or install globally
npm install -g @jaguilar87/gaia
```
The postinstall hook does everything automatically. To scan your project stack after install:
```bash
gaia scan
```
`gaia install` (run by postinstall) will:
1. Bootstrap the DB (`~/.gaia/gaia.db`) with the current schema
2. Create `.claude/` directory with symlinks to this package
3. Merge hooks and permissions into `settings.local.json` (preserves existing user config)
4. Write `plugin-registry.json`
`gaia scan` (run separately, on-demand) will:
1. Auto-detect your project structure (GitOps, Terraform, AppServices, stack)
2. Write scan results to `~/.gaia/gaia.db` (DB is canonical; no `project-context.json` file is generated)
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:
| File | Content | Strategy |
|------|---------|----------|
| `settings.json` | Hooks only (9 hook types) | Overwritten from template on each update |
| `settings.local.json` | Permissions (allow + deny rules) | Union merge — never removes user config |
This ensures your personal customizations (MCP servers, extra permissions) survive updates.
### Manual Installation
```bash
npm install @jaguilar87/gaia
```
Then create symlinks:
```bash
mkdir -p .claude && cd .claude
ln -s ../node_modules/@jaguilar87/gaia/agents agents
ln -s ../node_modules/@jaguilar87/gaia/tools tools
ln -s ../node_modules/@jaguilar87/gaia/hooks hooks
ln -s ../node_modules/@jaguilar87/gaia/commands commands
ln -s ../node_modules/@jaguilar87/gaia/config config
ln -s ../node_modules/@jaguilar87/gaia/templates templates
ln -s ../node_modules/@jaguilar87/gaia/skills skills
```
## Usage
Once installed, the agent system is ready:
```bash
claude
```
The orchestrator identity is defined in `agents/gaia-orchestrator.md` and activated via `settings.json` agent config. Skills are loaded on-demand.
Skill loading and overall installation health are checked via:
```bash
gaia doctor
```
## Security
Gaia enforces a 6-layer security pipeline:
| Layer | Mechanism | Bypassable? |
|-------|-----------|-------------|
| Indirect execution detection | `bash -c`, `eval`, `python -c` wrappers | No (hook-level) |
| Blocked commands (regex) | 85+ regex patterns | No (symlink to npm package) |
| Blocked commands (semantic) | 70+ ordered-token rules | No (symlink to npm package) |
| Cloud pipe validator | Credential piping detection | No (hook-level) |
| Mutative verb detection | `ask` dialog for state-changing ops | User approves via native dialog |
| Settings deny rules | 147 deny rules in `settings.local.json` | Self-healing (restored each session) |
## Project Structure
```
gaia-dev/
├── agents/ # Agent definitions (8 agents) — specialist identities + tool grants
├── skills/ # Skill modules (32 skills) — injected procedural knowledge
├── hooks/ # Claude Code hooks — the event-driven pipeline
├── config/ # Configuration — routing, contracts, rules, git standards
├── commands/ # Slash commands — /gaia, /scan-project
├── build/ # Plugin manifests — hook + agent registration for Claude Code
├── bin/ # Single `gaia` CLI; subcommands discovered from bin/cli/
├── tests/ # Test suite — 3-layer pyramid (pytest, LLM eval, e2e)
└── tools/ # Context provisioning tools
```
## API
```javascript
import { getAgentPath, getToolPath, getConfigPath } from '@jaguilar87/gaia';
const agentPath = getAgentPath('gitops-operator');
const toolPath = getToolPath('context_provider.py');
```
## Versioning
This package follows [Semantic Versioning](https://semver.org/):
- **MAJOR:** Breaking changes
- **MINOR:** New features
- **PATCH:** Bug fixes
See [CHANGELOG.md](./CHANGELOG.md) for version history.
## Documentation
- [INSTALL.md](./INSTALL.md) - Installation guide
- [agents/](./agents/) - Agent definitions and lifecycle
- [skills/](./skills/) - Skill modules and assignment matrix
- [hooks/](./hooks/) - Hook pipeline and security architecture
- [config/](./config/) - Configuration (contracts, git standards, surface routing)
- [commands/](./commands/) - Slash commands
- [build/](./build/) - Plugin manifests
- [bin/](./bin/) - CLI utilities
- [tests/](./tests/) - Test suite
## Requirements
- **Node.js:** >=18.0.0
- **Python:** >=3.9
- **Claude Code:** Latest version
- **Git:** >=2.30
## Project Context Management
Gaia uses `~/.gaia/gaia.db` (SQLite) as the canonical store for project context. Run `gaia scan` inside a workspace to detect and record the project stack, GitOps layout, Terraform layout, and other structural facts. Context is scoped per-workspace and survives reinstalls. View it with:
```bash
gaia context show
```
## Support
- **Issues:** [GitHub Issues](https://github.com/metraton/gaia/issues)
- **Repository:** [github.com/metraton/gaia](https://github.com/metraton/gaia)
- **Author:** Jorge Aguilar
## License
MIT License - See [LICENSE](./LICENSE) for details.