{"id":50781784,"url":"https://github.com/metraton/gaia","last_synced_at":"2026-06-12T04:01:25.727Z","repository":{"id":323577666,"uuid":"1093825963","full_name":"metraton/gaia","owner":"metraton","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-06T20:14:04.000Z","size":6362,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T22:09:16.802Z","etag":null,"topics":["ai-agents","claude-code","devops","gaia-ops","orchestration","security"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metraton.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-10T22:26:17.000Z","updated_at":"2026-06-06T20:14:02.000Z","dependencies_parsed_at":"2025-12-06T10:10:50.024Z","dependency_job_id":"280a97eb-c0de-4b98-a143-a64ca83a4b00","html_url":"https://github.com/metraton/gaia","commit_stats":null,"previous_names":["metraton/gaia-ops","metraton/gaia"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/metraton/gaia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metraton%2Fgaia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metraton%2Fgaia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metraton%2Fgaia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metraton%2Fgaia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metraton","download_url":"https://codeload.github.com/metraton/gaia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metraton%2Fgaia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34228097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","devops","gaia-ops","orchestration","security"],"created_at":"2026-06-12T04:00:49.055Z","updated_at":"2026-06-12T04:01:25.715Z","avatar_url":"https://github.com/metraton.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gaia\n\n\u003e **G**eneral **A**gentic **I**ntegration **A**rchitecture\n\n[![npm version](https://badge.fury.io/js/@jaguilar87%2Fgaia.svg)](https://www.npmjs.com/package/@jaguilar87/gaia)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/@jaguilar87/gaia.svg)](https://nodejs.org)\n\n## Cómo leer este repo\n\nGaia 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.\n\nThe 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.\n\n```\nUserPromptSubmit  -\u003e  routing  -\u003e  PreToolUse  -\u003e  agent  -\u003e  PostToolUse  -\u003e  SubagentStop\n      |                  |               |              |             |               |\n  identity           surface-        security       agent_contract_handoff  audit log     metrics +\n  injection          routing.json    gate +                                      memory\n                                     context\n                                     injection\n```\n\nThat 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.\n\n## Overview\n\n**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.\n\n### Features\n\n- **Multi-cloud support** - GCP, AWS, Azure\n- **8 agents** - platform-architect, gitops-operator, cloud-troubleshooter, developer, gaia-planner, gaia-operator, gaia-orchestrator, gaia-system (meta-agent)\n- **Contracts as SSOT** - Cloud-agnostic base contracts with per-cloud extensions (GCP, AWS)\n- **Dynamic identity** - Orchestrator identity defined in `agents/gaia-orchestrator.md`, activated via `settings.json` agent config; skills loaded on-demand\n- **Dual-barrier security** - Settings deny rules (Claude Code native) + hook-level blocking (inalterable via symlink)\n- **Indirect execution detection** - Catches `bash -c`, `eval`, `python -c` wrappers that bypass regex patterns\n- **Approval gates** for T3 operations via native `ask` dialog\n- **Git commit validation** with Conventional Commits\n- **32 skills** - Injected procedural knowledge modules for agents (protocol, domain, workflow)\n- **Episodic memory** - `gaia memory` CLI with FTS5 search, episode inspection, and session context orientation\n- **Context evals** - pytest-driven agent evaluation (5 graders, 3 backends, 10 scenarios, baseline + drift detection)\n- **Plugin + npm** - Distributable as Claude Code native plugin or npm package\n- **Enterprise ready** - Managed settings template for organization-wide deployment\n\n## Installation\n\n### Via Claude Code Plugin (recommended)\n```bash\n# Add the marketplace\n/plugin marketplace add metraton/gaia\n\n# Install the full system (includes security)\n/plugin install gaia-ops\n\n# Or install security only\n/plugin install gaia-security    # Security hooks only\n```\n\n### Via npm (advanced setup)\n```bash\nnpm install @jaguilar87/gaia\n```\n\nThe `npm install` postinstall script bootstraps the database, creates `.claude/`, writes symlinks, and registers the plugin. Run `gaia doctor` afterward to verify.\n\n### Quick Start (npm)\n\n```bash\n# Install and bootstrap (postinstall does the rest)\nnpm install @jaguilar87/gaia\n\n# Or install globally\nnpm install -g @jaguilar87/gaia\n```\n\nThe postinstall hook does everything automatically. To scan your project stack after install:\n```bash\ngaia scan\n```\n\n`gaia install` (run by postinstall) will:\n1. Bootstrap the DB (`~/.gaia/gaia.db`) with the current schema\n2. Create `.claude/` directory with symlinks to this package\n3. Merge hooks and permissions into `settings.local.json` (preserves existing user config)\n4. Write `plugin-registry.json`\n\n`gaia scan` (run separately, on-demand) will:\n1. Auto-detect your project structure (GitOps, Terraform, AppServices, stack)\n2. Write scan results to `~/.gaia/gaia.db` (DB is canonical; no `project-context.json` file is generated)\n\nNo `CLAUDE.md` is generated -- orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { \"agent\": \"gaia-orchestrator\" }`.\n\n### Settings Architecture\n\nGaia separates hooks from permissions:\n\n| File | Content | Strategy |\n|------|---------|----------|\n| `settings.json` | Hooks only (9 hook types) | Overwritten from template on each update |\n| `settings.local.json` | Permissions (allow + deny rules) | Union merge — never removes user config |\n\nThis ensures your personal customizations (MCP servers, extra permissions) survive updates.\n\n### Manual Installation\n\n```bash\nnpm install @jaguilar87/gaia\n```\n\nThen create symlinks:\n\n```bash\nmkdir -p .claude \u0026\u0026 cd .claude\nln -s ../node_modules/@jaguilar87/gaia/agents agents\nln -s ../node_modules/@jaguilar87/gaia/tools tools\nln -s ../node_modules/@jaguilar87/gaia/hooks hooks\nln -s ../node_modules/@jaguilar87/gaia/commands commands\nln -s ../node_modules/@jaguilar87/gaia/config config\nln -s ../node_modules/@jaguilar87/gaia/templates templates\nln -s ../node_modules/@jaguilar87/gaia/skills skills\n```\n\n## Usage\n\nOnce installed, the agent system is ready:\n\n```bash\nclaude\n```\n\nThe orchestrator identity is defined in `agents/gaia-orchestrator.md` and activated via `settings.json` agent config. Skills are loaded on-demand.\n\nSkill loading and overall installation health are checked via:\n\n```bash\ngaia doctor\n```\n\n## Security\n\nGaia enforces a 6-layer security pipeline:\n\n| Layer | Mechanism | Bypassable? |\n|-------|-----------|-------------|\n| Indirect execution detection | `bash -c`, `eval`, `python -c` wrappers | No (hook-level) |\n| Blocked commands (regex) | 85+ regex patterns | No (symlink to npm package) |\n| Blocked commands (semantic) | 70+ ordered-token rules | No (symlink to npm package) |\n| Cloud pipe validator | Credential piping detection | No (hook-level) |\n| Mutative verb detection | `ask` dialog for state-changing ops | User approves via native dialog |\n| Settings deny rules | 147 deny rules in `settings.local.json` | Self-healing (restored each session) |\n\n## Project Structure\n\n```\ngaia-dev/\n├── agents/              # Agent definitions (8 agents) — specialist identities + tool grants\n├── skills/              # Skill modules (32 skills) — injected procedural knowledge\n├── hooks/               # Claude Code hooks — the event-driven pipeline\n├── config/              # Configuration — routing, contracts, rules, git standards\n├── commands/            # Slash commands — /gaia, /scan-project\n├── build/               # Plugin manifests — hook + agent registration for Claude Code\n├── bin/                 # Single `gaia` CLI; subcommands discovered from bin/cli/\n├── tests/               # Test suite — 3-layer pyramid (pytest, LLM eval, e2e)\n└── tools/               # Context provisioning tools\n```\n\n## API\n\n```javascript\nimport { getAgentPath, getToolPath, getConfigPath } from '@jaguilar87/gaia';\n\nconst agentPath = getAgentPath('gitops-operator');\nconst toolPath = getToolPath('context_provider.py');\n```\n\n## Versioning\n\nThis package follows [Semantic Versioning](https://semver.org/):\n\n- **MAJOR:** Breaking changes\n- **MINOR:** New features\n- **PATCH:** Bug fixes\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n## Documentation\n\n- [INSTALL.md](./INSTALL.md) - Installation guide\n- [agents/](./agents/) - Agent definitions and lifecycle\n- [skills/](./skills/) - Skill modules and assignment matrix\n- [hooks/](./hooks/) - Hook pipeline and security architecture\n- [config/](./config/) - Configuration (contracts, git standards, surface routing)\n- [commands/](./commands/) - Slash commands\n- [build/](./build/) - Plugin manifests\n- [bin/](./bin/) - CLI utilities\n- [tests/](./tests/) - Test suite\n\n## Requirements\n\n- **Node.js:** \u003e=18.0.0\n- **Python:** \u003e=3.9\n- **Claude Code:** Latest version\n- **Git:** \u003e=2.30\n\n## Project Context Management\n\nGaia 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:\n\n```bash\ngaia context show\n```\n\n## Support\n\n- **Issues:** [GitHub Issues](https://github.com/metraton/gaia/issues)\n- **Repository:** [github.com/metraton/gaia](https://github.com/metraton/gaia)\n- **Author:** Jorge Aguilar \u003cjorge.aguilar88@gmail.com\u003e\n\n## License\n\nMIT License - See [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetraton%2Fgaia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetraton%2Fgaia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetraton%2Fgaia/lists"}