{"id":48085251,"url":"https://github.com/agentopology/agentopology","last_synced_at":"2026-04-20T01:00:55.196Z","repository":{"id":345547119,"uuid":"1179312783","full_name":"agentopology/agentopology","owner":"agentopology","description":"The Terraform for AI agents. Define your team once, deploy to Claude Code, OpenClaw, Cursor, Codex, Gemini, Copilot, Kiro. Declarative language (.at files) + Claude Code skill + interactive visualizer.","archived":false,"fork":false,"pushed_at":"2026-03-29T07:33:37.000Z","size":1112,"stargazers_count":66,"open_issues_count":1,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-29T10:30:39.457Z","etag":null,"topics":["ai-agents","claude-code","cursor","declarative","developer-tools","mcp","multi-agent","open-source","openclaw","orchestration","terraform","typescript"],"latest_commit_sha":null,"homepage":"https://agentopology.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentopology.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2026-03-11T22:51:18.000Z","updated_at":"2026-03-29T07:33:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentopology/agentopology","commit_stats":null,"previous_names":["agentopology/agentopology"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agentopology/agentopology","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentopology%2Fagentopology","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentopology%2Fagentopology/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentopology%2Fagentopology/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentopology%2Fagentopology/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentopology","download_url":"https://codeload.github.com/agentopology/agentopology/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentopology%2Fagentopology/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32028547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"ssl_error","status_checked_at":"2026-04-20T00:17:31.068Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","cursor","declarative","developer-tools","mcp","multi-agent","open-source","openclaw","orchestration","terraform","typescript"],"created_at":"2026-04-04T15:14:13.317Z","updated_at":"2026-04-20T01:00:55.188Z","avatar_url":"https://github.com/agentopology.png","language":"TypeScript","funding_links":[],"categories":["Ecosystem"],"sub_categories":["Quick Setup with cc-safe-setup"],"readme":"\u003ch1 align=\"center\"\u003eAgenTopology\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe Terraform for AI agents.\u003c/strong\u003e\u003cbr/\u003e\n  Define your agent team once. Deploy to any platform.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://agentopology.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/website-agentopology.com-purple\" alt=\"website\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/agentopology\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/agentopology\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue\" alt=\"license\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eClaude Code\u003c/strong\u003e · \u003cstrong\u003eOpenClaw\u003c/strong\u003e · \u003cstrong\u003eCodex\u003c/strong\u003e · \u003cstrong\u003eCursor\u003c/strong\u003e · \u003cstrong\u003eGemini CLI\u003c/strong\u003e · \u003cstrong\u003eCopilot\u003c/strong\u003e · \u003cstrong\u003eKiro\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eShips with a Claude Code skill — just type \u003ccode\u003e/agentopology\u003c/code\u003e and describe your team.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n## The Problem\n\nBuilding one AI agent is easy. Building a **team** of agents that actually works together is brutal.\n\nYou want a marketing team? A dev pipeline? A support squad? You spend hours wiring up AGENT.md files, soul.md configs, MCP servers, hooks, and scripts. You get it working in Claude Code. Then you need the same team in OpenClaw — and you start from scratch. Different config format. Different directory structure. Different conventions. Same agents, same logic, zero portability.\n\n**OpenClaw alone** needs soul.md, skill files, channel configs, gateway setup, and workspace definitions — for each agent. Multiply that by 5 agents and you're maintaining 20+ files that you can't visualize, validate, or hand off to anyone.\n\nAnd that's just the platform problem. The architecture problem is worse:\n\n- **How do you see the big picture?** Your topology is scattered across 15 files in nested directories. No diagram. No single source of truth.\n- **How do agents talk to each other?** You hack together file-based protocols or copy-paste context between prompts. There's no standard.\n- **How do you enforce quality?** You want a gate between stages but there's no standard way to define one.\n- **How do you move fast?** Every new agent means touching 5-12 files across multiple tools.\n\n**AgenTopology fixes all of this.**\n\nWrite your agent team in one `.at` file. Marketing, development, support, copywriting — any team, any structure. Visualize it. Validate it. Scaffold it to any platform in one command.\n\n```\ntopology code-review : [pipeline] {\n  agent researcher  { model: sonnet  tools: [Read, Grep, WebSearch] }\n  agent writer      { model: sonnet  tools: [Read, Write] }\n  agent reviewer    { model: opus    tools: [Read, Grep] }\n\n  flow {\n    researcher -\u003e writer -\u003e reviewer\n    reviewer -\u003e writer  [when reviewer.verdict == revise, max 2]\n  }\n}\n```\n\n```bash\nagentopology scaffold my-team.at --target claude-code   # → .claude/agents/\nagentopology scaffold my-team.at --target openclaw       # → .openclaw/soul.md\nagentopology scaffold my-team.at --target codex          # → .codex/\nagentopology scaffold my-team.at --target cursor         # → .cursor/rules/\n```\n\nOne file. Seven platforms. The topology IS the documentation.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/visualizer-preview.png\" alt=\"AgenTopology Visualizer\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n---\n\n## What It Does\n\nAgenTopology is a **declarative language** (`.at` files) and a **CLI compiler** that transforms agent definitions into platform-native configuration files.\n\n```\n┌──────────────┐      ┌────────────┐      ┌─────────────────────┐\n│  .at file    │ ───▶ │  Parser \u0026  │ ───▶ │  Platform configs   │\n│  (you write) │      │  Validator │      │  (auto-generated)   │\n└──────────────┘      └────────────┘      └─────────────────────┘\n                                            ├── .claude/agents/\n                                            ├── .openclaw/\n                                            ├── .codex/\n                                            ├── .cursor/rules/\n                                            ├── .github/agents/\n                                            ├── .kiro/agents/\n                                            └── ...\n```\n\nYou stop hand-maintaining config files. Your topology becomes the single source of truth.\n\n---\n\n## Quick Start\n\n```bash\nnpm install -g agentopology\n```\n\n**Validate** — catch errors before you scaffold:\n```bash\nagentopology validate my-team.at\n```\n\n**Scaffold** — generate platform configs:\n```bash\nagentopology scaffold my-team.at --target claude-code\n```\n\n**Visualize** — see your topology as an interactive graph:\n```bash\nagentopology visualize my-team.at\n```\n\n**List targets** — see all supported platforms:\n```bash\nagentopology targets\n```\n\n---\n\n## Claude Code Skill — The Fastest Way to Start\n\n**You don't need to learn `.at` syntax.** AgenTopology ships with an interactive skill that turns Claude Code into a topology designer. Describe the team you want in plain English — the skill generates everything.\n\n### Setup (one time)\n\n```bash\n# Install globally\nnpm install -g agentopology\n\n# Link the skill into your project\nln -s $(npm root -g)/agentopology/skill .claude/skills/agentopology\n```\n\n### Usage\n\nIn Claude Code, type `/agentopology` — or just ask naturally:\n\n```\n\u003e /agentopology\n\n┌─────────────────────────────────────┐\n│  AgenTopology                       │\n│  Build agent teams in minutes.      │\n├─────────────────────────────────────┤\n│                                     │\n│  build       Design a new topology  │\n│  templates   Pick a proven team     │\n│  validate    Check an .at file      │\n│  scaffold    Generate platform files│\n│  visualize   Open graph viewer      │\n│                                     │\n└─────────────────────────────────────┘\n```\n\nSay **\"I want a code review team with an analyzer, security scanner, and reviewer\"** — the skill:\n\n1. Generates the `.at` file with the right syntax\n2. Validates it against 82 rules\n3. Scaffolds it to Claude Code, OpenClaw, Cursor, or any target\n\n**Full agent team in under 2 minutes.** No docs to read. No syntax to memorize. You describe what you want, the skill handles the rest.\n\n---\n\n## Evolving Your Topology\n\nYou have a working `.at` file and want to make it better? Just tell the skill what you need:\n\n- **\"Add a security scanner agent before the reviewer\"** — the skill adds the agent, wires it into the flow, and re-validates\n- **\"Add a hook that formats code after every write\"** — generates the hook block with the right lifecycle event\n- **\"Add an MCP server for GitHub\"** — adds the server config with environment variables\n- **\"Add a quality gate between the builder and reviewer\"** — inserts a gate with halt-on-fail\n- **\"Switch the target to OpenClaw\"** — re-scaffolds the entire topology for a different platform\n\nThe workflow is always the same: **describe the change → the skill updates the `.at` file → validates → re-scaffolds.** You never touch config files manually.\n\nAfter any change, `agentopology visualize` updates the interactive graph so you can see exactly what changed — every agent, connection, tool, hook, and gate in one view.\n\nFull language reference and guides at **[agentopology.com/docs](https://agentopology.com/docs)**.\n\n---\n\n## The Language\n\n`.at` files are human-readable and version-controllable. Here's a real topology:\n\n```\ntopology content-pipeline : [pipeline, human-gate] {\n\n  meta {\n    version: \"1.0.0\"\n    description: \"Research, write, review — with quality gate\"\n  }\n\n  agent researcher {\n    model: sonnet\n    description: \"Gathers information and sources\"\n    tools: [Read, Grep, WebSearch]\n    writes: [\"workspace/research.md\"]\n    prompt {\n      Search broadly for relevant sources.\n      Compile findings into structured research notes.\n      Include citations and source URLs.\n    }\n  }\n\n  agent writer {\n    model: sonnet\n    description: \"Drafts content from research\"\n    tools: [Read, Write]\n    reads: [\"workspace/research.md\"]\n    writes: [\"workspace/draft.md\"]\n  }\n\n  agent reviewer {\n    model: opus\n    description: \"Reviews drafts for quality\"\n    tools: [Read, Grep]\n    reads: [\"workspace/draft.md\"]\n    outputs: { verdict: approve | revise | reject }\n  }\n\n  gates {\n    gate quality-check {\n      after: reviewer\n      run: \"scripts/check-quality.sh\"\n      on-fail: halt\n    }\n  }\n\n  flow {\n    researcher -\u003e writer -\u003e reviewer\n    reviewer -\u003e writer  [when reviewer.verdict == revise, max 2]\n  }\n}\n```\n\nThis defines three agents, their tools and memory, a quality gate, and a flow with a conditional retry loop — all in 40 lines.\n\n---\n\n## Supported Platforms\n\n| Target | Command | What It Generates |\n|--------|---------|-------------------|\n| **Claude Code** | `--target claude-code` | `.claude/agents/`, `.claude/skills/`, `.mcp.json`, `.claude/settings.json` |\n| **OpenClaw** | `--target openclaw` | `.openclaw/soul.md`, `.openclaw/skills/`, `.openclaw/config.json` |\n| **Codex** | `--target codex` | `.codex/config.toml`, `AGENTS.md` |\n| **Cursor** | `--target cursor` | `.cursor/rules/*.mdc`, `.cursor/mcp.json`, `.cursor/hooks.json` |\n| **Gemini CLI** | `--target gemini-cli` | `.gemini/`, `AGENTS.md` |\n| **Copilot** | `--target copilot-cli` | `.github/agents/*.agent.md`, `.github/copilot-instructions.md` |\n| **Kiro** | `--target kiro` | `.kiro/agents/*.json`, `.kiro/steering/` |\n\nEvery binding is ground-truth validated against real-world configs from production repos.\n\n---\n\n## Language Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Agents \u0026 Models**\n```\nagent planner {\n  model: opus\n  tools: [Read, Write, Bash]\n  permissions: plan\n  thinking: high\n  thinking-budget: 4000\n  max-turns: 20\n}\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Flow Graphs**\n```\nflow {\n  intake -\u003e researcher\n  researcher -\u003e writer\n  writer -\u003e reviewer\n  reviewer -\u003e writer  [when verdict == revise, max 3]\n  reviewer -\u003e done    [when verdict == approve]\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Group Chats**\n```\ngroup debate-arena {\n  members: [pro, con]\n  speaker-selection: \"round-robin\"\n  max-rounds: 5\n  termination: \"judge declares winner\"\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**Quality Gates**\n```\ngates {\n  gate security-scan {\n    after: builder\n    run: \"scripts/security.sh\"\n    checks: [vulnerabilities, secrets]\n    on-fail: halt\n  }\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Hooks \u0026 Events**\n```\nhooks {\n  hook format-on-save {\n    on: PostToolUse\n    matcher: \"Write\"\n    run: \"scripts/format.sh\"\n  }\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**MCP Servers**\n```\nmcp-servers {\n  github {\n    command: \"npx\"\n    args: [\"-y\", \"@mcp/server-github\"]\n    env { TOKEN: \"${GITHUB_TOKEN}\" }\n  }\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nPlus: **memory stores** (semantic, graph, episodic — 11 backends), **retrieval strategies** (scoring weights, cache-hit routing), schemas, artifacts, metering, circuit breakers, scale configs, depth levels, environment overrides, prompt variants, composition via imports, and [more](spec/grammar.md).\n\n---\n\n## Group Chats — Agents That Talk to Each Other\n\nGroups aren't fan-out. They're real conversations. Each agent reads what others wrote and responds:\n\n```\ngroup design-review {\n  members: [architect, security-lead, tech-lead]\n  speaker-selection: \"round-robin\"\n  max-rounds: 3\n  termination: \"consensus reached\"\n}\n```\n\nIn Claude Code, this compiles to a **file-based protocol** — a shared transcript file that agents read and append to sequentially. No HTTP, no message bus. Just the filesystem as shared state.\n\n---\n\n---\n\n## Programmatic API\n\n```typescript\nimport { parse, validate, bindings } from \"agentopology\";\n\n// Parse\nconst ast = parse(atSource);\n\n// Validate (29 built-in rules)\nconst issues = validate(ast);\n\n// Scaffold\nconst files = bindings[\"claude-code\"].scaffold(ast);\n\n// Visualize\nimport { generateVisualization } from \"agentopology\";\nconst html = generateVisualization(ast);\n```\n\n---\n\n## Create Your Own Binding\n\nImplement the `BindingTarget` interface to add any platform:\n\n```typescript\nimport type { BindingTarget } from \"agentopology\";\n\nexport const myBinding: BindingTarget = {\n  name: \"my-platform\",\n  description: \"My AI Platform\",\n  scaffold(ast) {\n    return [\n      { path: \"agents.json\", content: JSON.stringify(ast.nodes) },\n    ];\n  },\n};\n```\n\n---\n\n## Focus on Structure, Not Config Files\n\nThe `.at` file IS your architecture diagram. When you open it, you see:\n- Who the agents are\n- What tools they have\n- How work flows between them\n- Where the quality gates are\n- What happens when things fail\n\nYou can `agentopology visualize` it into an interactive graph. You can hand it to a new team member and they understand the system in 30 seconds. Try doing that with 15 scattered AGENT.md files.\n\n| | Config files | AgenTopology |\n|---|---|---|\n| **Switch platforms** | Rewrite everything | Change `--target` |\n| **Add an agent** | Update 5-12 files across 3 tools | Add 4 lines to `.at` file |\n| **See the architecture** | Read YAML, JSON, TOML, Markdown across 6 dirs | One `.at` file. Or `visualize` it. |\n| **Validate** | Hope for the best | 29 built-in rules catch errors before deploy |\n| **Onboard someone** | \"Read these 15 files and figure it out\" | \"Read this `.at` file\" |\n| **Version control** | Diff 47 generated files | Diff one `.at` file |\n| **Move to a new tool** | Start over | `--target new-tool` |\n\n---\n\n## Examples\n\n- [`simple-pipeline.at`](examples/simple-pipeline.at) — Research → write → review with quality gate\n- [`code-review.at`](examples/code-review.at) — Multi-agent code review with security scanning\n- [`data-processing.at`](examples/data-processing.at) — ETL pipeline with batch processing and metering\n- [`scheduled-monitor.at`](examples/scheduled-monitor.at) — Monitoring system with scheduled health checks\n- [`openclaw-assistant.at`](examples/openclaw-assistant.at) — Customer support with routing and scheduling\n\n---\n\n## CLI Reference\n\n```\nagentopology validate \u003cfile\u003e              Validate an .at file (82 rules)\nagentopology scaffold \u003cfile\u003e --target \u003ct\u003e Generate platform configs\nagentopology sync \u003cfile\u003e --target \u003ct\u003e --dir \u003cd\u003e  Sync platform files back to .at\nagentopology import --target \u003ct\u003e --dir \u003cd\u003e       Reverse-engineer platform files to .at\nagentopology visualize \u003cfile\u003e             Interactive topology graph\nagentopology export \u003cfile\u003e --format \u003cfmt\u003e Export as markdown, mermaid, or json\nagentopology info \u003cfile\u003e                  Topology analysis and suggestions\nagentopology targets                      List supported platforms\nagentopology docs [topic]                 Language reference (42 topics)\n```\n\n---\n\n## Contributing\n\nWe welcome contributions. The easiest ways to start:\n\n- Add a new [example topology](examples/)\n- Improve a [binding](src/bindings/)\n- Add [tests](src/bindings/__tests__/)\n- Write [documentation](docs/)\n\nGrammar and AST changes require an RFC.\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eCreated by \u003ca href=\"https://github.com/nadavnaveh\"\u003eNadav Naveh\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentopology%2Fagentopology","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentopology%2Fagentopology","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentopology%2Fagentopology/lists"}