175 lines
6.2 KiB
Markdown
175 lines
6.2 KiB
Markdown
<div align="center">
|
|
|
|
# Agent Orchestrator — The Orchestration Layer for Parallel AI Agents
|
|
|
|
Spawn parallel AI coding agents, each in its own git worktree. Agents autonomously fix CI failures, address review comments, and open PRs — you supervise from one dashboard.
|
|
|
|
[](https://github.com/ComposioHQ/agent-orchestrator/stargazers)
|
|
[](LICENSE)
|
|
[](https://github.com/ComposioHQ/agent-orchestrator/pulls?q=is%3Amerged)
|
|
[](https://github.com/ComposioHQ/agent-orchestrator/releases/tag/metrics-v1)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
Agent Orchestrator manages fleets of AI coding agents working in parallel on your codebase. Each agent gets its own git worktree, its own branch, and its own PR. When CI fails, the agent fixes it. When reviewers leave comments, the agent addresses them. You only get pulled in when human judgment is needed.
|
|
|
|
**Agent-agnostic** (Claude Code, Codex, Aider) · **Runtime-agnostic** (tmux, Docker) · **Tracker-agnostic** (GitHub, Linear)
|
|
|
|
<div align="center">
|
|
|
|
## See it in action
|
|
|
|
<a href="https://x.com/agent_wrapper/status/2026329204405723180">
|
|
<img src="docs/assets/demo-video-tweet.png" alt="Agent Orchestrator demo — AI agents building their own orchestrator" width="560">
|
|
</a>
|
|
<br><br>
|
|
<a href="https://x.com/agent_wrapper/status/2026329204405723180"><img src="docs/assets/btn-watch-demo.png" alt="Watch the Demo on X" height="48"></a>
|
|
<br><br><br>
|
|
<a href="https://x.com/agent_wrapper/status/2025986105485733945">
|
|
<img src="docs/assets/article-tweet.png" alt="The Self-Improving AI System That Built Itself" width="560">
|
|
</a>
|
|
<br><br>
|
|
<a href="https://x.com/agent_wrapper/status/2025986105485733945"><img src="docs/assets/btn-read-article.png" alt="Read the Full Article on X" height="48"></a>
|
|
|
|
</div>
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install
|
|
git clone https://github.com/ComposioHQ/agent-orchestrator.git
|
|
cd agent-orchestrator && bash scripts/setup.sh
|
|
|
|
# Configure your project
|
|
cd ~/your-project && ao init --auto
|
|
|
|
# Launch and spawn an agent
|
|
ao start
|
|
ao spawn my-project 123 # GitHub issue, Linear ticket, or ad-hoc
|
|
```
|
|
|
|
Dashboard opens at `http://localhost:3000`. Run `ao status` for the CLI view.
|
|
|
|
## How It Works
|
|
|
|
```
|
|
ao spawn my-project 123
|
|
```
|
|
|
|
1. **Workspace** creates an isolated git worktree with a feature branch
|
|
2. **Runtime** starts a tmux session (or Docker container)
|
|
3. **Agent** launches Claude Code (or Codex, or Aider) with issue context
|
|
4. Agent works autonomously — reads code, writes tests, creates PR
|
|
5. **Reactions** auto-handle CI failures and review comments
|
|
6. **Notifier** pings you only when judgment is needed
|
|
|
|
### Plugin Architecture
|
|
|
|
Eight slots. Every abstraction is swappable.
|
|
|
|
| Slot | Default | Alternatives |
|
|
|------|---------|-------------|
|
|
| Runtime | tmux | docker, k8s, process |
|
|
| Agent | claude-code | codex, aider, opencode |
|
|
| Workspace | worktree | clone |
|
|
| Tracker | github | linear |
|
|
| SCM | github | — |
|
|
| Notifier | desktop | slack, composio, webhook |
|
|
| Terminal | iterm2 | web |
|
|
| Lifecycle | core | — |
|
|
|
|
All interfaces defined in [`packages/core/src/types.ts`](packages/core/src/types.ts). A plugin implements one interface and exports a `PluginModule`. That's it.
|
|
|
|
## Configuration
|
|
|
|
```yaml
|
|
# agent-orchestrator.yaml
|
|
port: 3000
|
|
|
|
defaults:
|
|
runtime: tmux
|
|
agent: claude-code
|
|
workspace: worktree
|
|
notifiers: [desktop]
|
|
|
|
projects:
|
|
my-app:
|
|
repo: owner/my-app
|
|
path: ~/my-app
|
|
defaultBranch: main
|
|
sessionPrefix: app
|
|
|
|
reactions:
|
|
ci-failed:
|
|
auto: true
|
|
action: send-to-agent
|
|
retries: 2
|
|
changes-requested:
|
|
auto: true
|
|
action: send-to-agent
|
|
escalateAfter: 30m
|
|
approved-and-green:
|
|
auto: false # flip to true for auto-merge
|
|
action: notify
|
|
```
|
|
|
|
CI fails → agent gets the logs and fixes it. Reviewer requests changes → agent addresses them. PR approved with green CI → you get a notification to merge.
|
|
|
|
See [`agent-orchestrator.yaml.example`](agent-orchestrator.yaml.example) for the full reference.
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
ao status # Overview of all sessions
|
|
ao spawn <project> [issue] # Spawn an agent
|
|
ao send <session> "Fix the tests" # Send instructions
|
|
ao session ls # List sessions
|
|
ao session kill <session> # Kill a session
|
|
ao session restore <session> # Revive a crashed agent
|
|
ao dashboard # Open web dashboard
|
|
```
|
|
|
|
## Why Agent Orchestrator?
|
|
|
|
Running one AI agent in a terminal is easy. Running 30 across different issues, branches, and PRs is a coordination problem.
|
|
|
|
**Without orchestration**, you manually: create branches, start agents, check if they're stuck, read CI failures, forward review comments, track which PRs are ready to merge, clean up when done.
|
|
|
|
**With Agent Orchestrator**, you: `ao spawn` and walk away. The system handles isolation, feedback routing, and status tracking. You review PRs and make decisions — the rest is automated.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+
|
|
- Git 2.25+
|
|
- tmux (for default runtime)
|
|
- `gh` CLI (for GitHub integration)
|
|
|
|
## Development
|
|
|
|
```bash
|
|
pnpm install && pnpm build # Install and build all packages
|
|
pnpm test # Run tests (3,288 test cases)
|
|
pnpm dev # Start web dashboard dev server
|
|
```
|
|
|
|
See [CLAUDE.md](CLAUDE.md) for code conventions and architecture details.
|
|
|
|
## Documentation
|
|
|
|
| Doc | What it covers |
|
|
|-----|---------------|
|
|
| [Setup Guide](SETUP.md) | Detailed installation and configuration |
|
|
| [Examples](examples/) | Config templates (GitHub, Linear, multi-project, auto-merge) |
|
|
| [CLAUDE.md](CLAUDE.md) | Architecture, conventions, plugin pattern |
|
|
| [Troubleshooting](TROUBLESHOOTING.md) | Common issues and fixes |
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome. The plugin system makes it straightforward to add support for new agents, runtimes, trackers, and notification channels. Every plugin is an implementation of a TypeScript interface — see [CLAUDE.md](CLAUDE.md) for the pattern.
|
|
|
|
## License
|
|
|
|
MIT
|