open-agent-engine

Open Agent Engine 🚀

The open-source compiler & multi-agent runtime for coding agents.
Write canonical agent architecture once (.agents/). Transpile into Claude Code, Cursor, Windsurf, Roo Code, Aider, and Linux Foundation AAIF native configurations in milliseconds.

💡 Why Open Agent Engine?

Modern AI coding agents (Claude Code, Cursor, Windsurf, Roo Code, Aider) are powerful, but developers face massive friction:

• Prompt Drift & Context Exhaustion: Giant monolithic prompt files blow past token limits, degrade reasoning, and invalidate prompt caching.
• Vendor Lock-in: Every tool invents its own bespoke config format (CLAUDE.md, .cursor/rules/*.mdc, .windsurfrules, .roomodes, .aider.conf.yml).
• No Modular Skill Sharing: No standard way to install, version, or share progressive disclosure agent skills.
• Cowboy Coding on Main: Agents edit shared working directories without branch isolation, causing dirty git trees and collisions.

Open Agent Engine solves this with 4 core pillars:

flowchart TD
    Canonical["Canonical Core (.agents/)<br>(Personas, Rules &lt; 150 lines, Skills, Hooks)"]
    Compiler["agent-engine build<br>(Zero-loss Transpiler)"]
    
    Canonical --> Compiler
    
    Compiler --> C1["Claude Code (CLAUDE.md)"]
    Compiler --> C2["Cursor (.cursor/rules/*.mdc)"]
    Compiler --> C3["Windsurf (.windsurfrules)"]
    Compiler --> C4["Roo Code (.roomodes)"]
    Compiler --> C5["Aider (.aider.conf.yml)"]
    Compiler --> C6["Universal AAIF (AGENTS.md)"]

1. 🧙‍♂️ Interactive Scaffolding Wizard (init): Sets up an AAIF-compliant multi-agent architecture in 1 second.
2. ⚡ Multi-Platform Compiler (build): Transpiles canonical .agents/ AST into 6 native target configurations with zero loss.
3. 📦 SkillHub Package Manager (skill): "shadcn for Agent Skills" — install, author, and version progressive disclosure markdown skills directly in your repository.
4. 🌿 Ephemeral Worktree Engine (worktree): Windows-resilient Git worktree isolation with exponential lock retries and merge conflict rollback.

⚡ Quick Start

1. Initialize Your Workspace

In any project directory, run:

npx agent-engine init

The interactive wizard asks you which AI coding tools you use and scaffolds the canonical .agents/ directory:

┌  Welcome to Open Agent Engine
│
◇  What is the name of your project?
│  my-app
│
◇  Which AI coding platforms are you using?
│  ◼ Claude Code (CLAUDE.md)
│  ◼ Cursor (.cursor/rules)
│  ◻ Windsurf (.windsurfrules)
│
└  ✔ Initialized your workspace! Generated native configs in 14ms.

2. Install Battle-Tested Agent Skills

Add skills directly from the built-in community catalog:

# Context snapshotting and session continuity
npx agent-engine skill add antigravity-handoff --build

# Multi-pass automated code review gate
npx agent-engine skill add code-reviewer --build

# Multi-subagent worktree coordination
npx agent-engine skill add subagent-coordinator --build

3. Compile Target Configurations

Rebuild native target files whenever you update skills or personas:

npx agent-engine build

🎓 The Educational Mental Model: From Cowboy Prompts to Canonical Architecture

Modern AI agent engineering requires unlearning the anti-pattern of monolithic prompt dumping. Open Agent Engine teaches and enforces a high-performance mental model:

1. The 3-Level Progressive Disclosure Framework

Instead of forcing 3,000+ tokens of instructions into every prompt, skills disclose context on demand:

• Level 1 (Metadata Index ~100 tokens): YAML frontmatter (name, description, triggers) stays in active context.
• Level 2 (Workflow Runbook ~500 tokens): Step-by-step markdown loaded into context only when triggered.
• Level 3 (Deterministic Assets 0 tokens): Auxiliary scripts and templates executed externally.

💡 Token Economics: Progressive disclosure reduces active token overhead by 90% and keeps LLM prompt prefix caches hot (>95% hit rate).

2. The 4-Stage Operational Workflow

flowchart LR
    subgraph S1["1. Scaffold"]
        A1["init wizard"]
    end
    subgraph S2["2. Equip"]
        A2["skill package mgr"]
    end
    subgraph S3["3. Transpile"]
        A3["build compiler"]
    end
    subgraph S4["4. Isolate"]
        A4["ephemeral worktrees"]
    end
    S1 --> S2 --> S3 --> S4

For more learning resources:

• 🎈 Beginner? Read our Simple Beginner Guide (ELI5).
• 📖 Deep Dive? Read our Architectural Workflow & Mental Model Guide.

📦 Canonical .agents/ Architecture

Open Agent Engine enforces a clean, progressive disclosure folder structure:

.agents/
├── config.yaml          # Project configuration, targets, and skills registry
├── personas/            # Active agent roles with AAIF frontmatter
│   └── default.md       # Principal Systems Architect persona
├── rules/               # Context-lean guidelines (strictly <150 lines)
│   └── 000-base.md      # Foundational engineering invariants
├── skills/              # Progressive disclosure capabilities (L1, L2, L3)
│   ├── antigravity-handoff/
│   ├── code-reviewer/
│   └── subagent-coordinator/
└── hooks/               # Tool execution safety guardrails
    └── hooks.json

🛠️ CLI Command Reference

🧩 Supported Platforms

🧪 Testing & Verification

Open Agent Engine is thoroughly tested with a 100% passing test suite across all modules:

# Run Vitest test suite
pnpm test

# Run TypeScript typechecks
pnpm typecheck

Test Files  20 passed (20)
     Tests  136 passed (136)
  Duration  7.69s

🤝 Contributing

Contributions are warmly welcomed! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

📄 License

Open Agent Engine is open-source software licensed under the MIT License.