bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add comprehensive README with quick start guide 

- 3-line magical setup: clone → setup → init → start
- Architecture overview with plugin slots table
- Usage examples and auto-reaction configuration
- Links to detailed docs (SETUP.md, TROUBLESHOOTING.md, examples/)
- Philosophy: push not pull, amplify judgment

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Prateek 2026-02-16 15:42:31 +05:30
parent 26cc28ee68
commit 4e6fb232f6
1 changed files with 183 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

365
README.md
View File

@ -1,238 +1,239 @@
# Agent Orchestrator
Open-source system for orchestrating parallel AI coding agents. Agent-agnostic, runtime-agnostic, tracker-agnostic.
**Core principle: Push, not pull.** Spawn agents, walk away, get notified when your judgment is needed.
## Features
- **8 plugin slots** — Runtime (tmux, docker, k8s), Agent (Claude Code, Codex, Aider), Workspace (worktree, clone), Tracker (GitHub, Linear), SCM (GitHub), Notifier (desktop, Slack), Terminal (iTerm2, web), Lifecycle (core)
- **Agent-agnostic** — Works with Claude Code, Codex, Aider, Goose, or custom agents
- **Runtime-agnostic** — Run in tmux (local), Docker, Kubernetes, SSH, or E2B
- **Tracker-agnostic** — GitHub Issues, Linear, Jira (extensible)
- **Auto-reactions** — CI failures, review comments, merge conflicts → auto-handled
- **Push notifications** — Desktop, Slack, Discord, Webhook, Email
- **Web dashboard** — Real-time session monitoring with SSE
- **TypeScript** — Strict types, ESM modules, Zod validation
Orchestrate parallel AI coding agents across any runtime, any repo, any issue tracker.
## Quick Start
**Option 1: One-command setup (recommended)**
```bash
# Clone and setup
git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
./scripts/setup.sh
# Initialize in your project
cd /path/to/your/project
ao init --auto
gh auth login # Authenticate GitHub CLI
ao start # Launch dashboard
cd agent-orchestrator && bash scripts/setup.sh
cd ~/your-project && ao init --auto && ao start
```
**Option 2: Manual setup**
**That's it!** Dashboard opens at http://localhost:3000
## What Is This?
Agent Orchestrator spawns and manages multiple AI coding agents working in parallel on your repository. Each agent works in isolation (separate worktrees), handles its own PR lifecycle, and auto-responds to CI failures and review comments.
**Key benefits:**
- 🚀 **10-30x productivity** - Work on 10+ issues simultaneously
- 🤖 **Human-in-the-loop** - Agents notify you when judgment needed, not for routine work
- 🔌 **Fully pluggable** - Swap any component (runtime, agent, tracker, SCM)
- 📊 **Real-time dashboard** - Monitor all agents from one place
**Built itself:** This project was built using itself (399 commits, 34 PRs, 63 hours of dog-fooding).
## Features
- **Agent-agnostic**: Claude Code, Codex, Aider, or bring your own
- **Runtime-agnostic**: tmux, Docker, Kubernetes, or custom
- **Tracker-agnostic**: GitHub Issues, Linear, Jira, or custom
- **Auto-reactions**: CI failures, review comments, merge conflicts → handled automatically
- **Notifications**: Desktop, Slack, Composio, or webhook - only when you're needed
- **Live terminal**: See agents working in real-time through browser
## Architecture
8 plugin slots - every abstraction is swappable:
| Slot | Interface | Default | Alternatives |
|-----------|-------------|-----------|-----------------------|
| Runtime | `Runtime` | tmux | docker, k8s, process |
| Agent | `Agent` | claude-code | codex, aider, opencode |
| Workspace | `Workspace` | worktree | clone |
| Tracker | `Tracker` | github | linear, jira |
| SCM | `SCM` | github | (gitlab, bitbucket) |
| Notifier | `Notifier` | desktop | slack, composio, webhook |
| Terminal | `Terminal` | iterm2 | web |
| Lifecycle | core | — | — |
## Installation
### Prerequisites
- Node 20+
- Git 2.25+
- tmux (for tmux runtime)
- gh CLI (for GitHub integration)
### Setup
```bash
# Install dependencies
pnpm install
# Clone and run setup
git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
bash scripts/setup.sh
```
# Build all packages
pnpm build
The setup script:
- Installs dependencies with pnpm
- Builds all packages
- Rebuilds node-pty from source (fixes terminal issues)
- Links `ao` CLI globally
# Link CLI globally
npm link -g ./packages/cli
### Initialize Your Project
# Initialize in your project
cd /path/to/your/project
ao init --auto
ao start
```bash
cd ~/your-project
ao init --auto # Auto-detects project type, generates config
ao start # Launches orchestrator + dashboard
```
**Auto-detection:**
- Git repo and remote
- Project type (languages, frameworks, test runners)
- Generates custom agent rules based on your stack
## Usage
### Spawn Agents
```bash
# Spawn agent for a GitHub issue
ao spawn my-project 123
# Spawn for a Linear issue
ao spawn my-project INT-1234
# Spawn without issue (ad-hoc work)
ao spawn my-project
```
### Monitor Progress
```bash
# Command-line dashboard
ao status
# Web dashboard
open http://localhost:3000
```
### Manage Sessions
```bash
# List all sessions
ao session ls
# Send message to agent
ao send <session-id> "Fix the linting errors"
# Kill session
ao session kill <session-id>
```
### Auto-Reactions
Configure reactions for common scenarios:
```yaml
reactions:
ci-failed:
auto: true
action: send-to-agent
retries: 3
changes-requested:
auto: true
action: send-to-agent
escalateAfter: 1h
approved-and-green:
auto: true
action: auto-merge
```
## Configuration
Agent Orchestrator reads `agent-orchestrator.yaml` from your working directory.
### Minimal Example
Basic config (`agent-orchestrator.yaml`):
```yaml
# Paths
dataDir: ~/.agent-orchestrator
worktreeDir: ~/.worktrees
port: 3000
# Projects
defaults:
runtime: tmux
agent: claude-code
workspace: worktree
notifiers: [desktop]
projects:
my-app:
repo: org/my-app
repo: owner/my-app
path: ~/my-app
defaultBranch: main
agentRules: |
Always run tests before pushing.
Use conventional commits.
Write clear commit messages.
```
### Using Secrets Securely
See `agent-orchestrator.yaml.example` for full reference.
**⚠️ NEVER commit real secrets to git!**
## Examples
Use environment variables for all tokens and API keys:
See `examples/` directory for:
- `simple-github.yaml` - Minimal GitHub Issues setup
- `linear-team.yaml` - Linear integration
- `multi-project.yaml` - Multiple repos
- `auto-merge.yaml` - Aggressive automation
```yaml
notifiers:
slack:
plugin: slack
webhookUrl: ${SLACK_WEBHOOK_URL} # Reference env var
projects:
my-app:
tracker:
plugin: linear
apiKey: ${LINEAR_API_KEY} # Reference env var
```
Then set in your shell:
```bash
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
export LINEAR_API_KEY="lin_api_..."
export GITHUB_TOKEN="ghp_..."
```
See [SECURITY.md](./SECURITY.md) for best practices.
### Full Example
See [`agent-orchestrator.yaml.example`](./agent-orchestrator.yaml.example) for all options.
## Commands
## Development
```bash
# Development
pnpm install # Install dependencies
pnpm build # Build all packages
pnpm dev # Start web dashboard (dev mode)
pnpm test # Run tests
# Code quality
pnpm lint # Check linting
pnpm lint:fix # Auto-fix linting
pnpm format # Format with Prettier
pnpm typecheck # TypeScript type checking
# Package management
pnpm clean # Clean build artifacts
pnpm install
pnpm build
pnpm dev # Start web dev server
```
## Architecture
### Plugin Slots
Every abstraction is swappable:
| Slot | Interface | Default Plugins |
| --------- | ----------- | --------------- |
| Runtime | `Runtime` | tmux, process, docker, kubernetes, ssh, e2b |
| Agent | `Agent` | claude-code, codex, aider, goose, opencode |
| Workspace | `Workspace` | worktree, clone |
| Tracker | `Tracker` | github, linear |
| SCM | `SCM` | github |
| Notifier | `Notifier` | desktop, slack, composio, webhook |
| Terminal | `Terminal` | iterm2, web |
| Lifecycle | (core) | — |
All interfaces defined in [`packages/core/src/types.ts`](./packages/core/src/types.ts).
### Directory Structure
### Project Structure
```
packages/
core/ — @composio/ao-core (types, config, services)
cli/ — @composio/ao-cli (the `ao` command)
web/ — @composio/ao-web (Next.js dashboard)
core/ - Core types and services
cli/ - ao command-line tool
web/ - Next.js dashboard
plugins/
runtime-{tmux,process,docker,kubernetes,ssh,e2b}/
agent-{claude-code,codex,aider,goose,opencode}/
workspace-{worktree,clone}/
tracker-{github,linear}/
scm-github/
notifier-{desktop,slack,composio,webhook}/
terminal-{iterm2,web}/
integration-tests/
runtime-*/ - Runtime plugins
agent-*/ - Agent plugins
workspace-*/ - Workspace plugins
tracker-*/ - Tracker plugins
scm-*/ - SCM plugins
notifier-*/ - Notifier plugins
terminal-*/ - Terminal plugins
```
## Security
## Troubleshooting
🔒 **This repository uses automated secret scanning** to prevent accidental commits of API keys, tokens, and other secrets.
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and solutions.
### For Developers
**Most common:**
- Terminal not working → node-pty rebuild (automatic via postinstall hook)
- Port in use → Kill existing server or change port in config
- Config not found → Run `ao init` from your project directory
- **Pre-commit hook** — Scans staged files before every commit
- **CI pipeline** — Scans full git history on every push/PR
- **Gitleaks** — Industry-standard secret detection
## Philosophy
Before committing:
```bash
# Scan current files
gitleaks detect --no-git
**Push, not pull:** Spawn agents, walk away, get notified only when your judgment is needed.
# Scan staged files (automatic in pre-commit hook)
gitleaks protect --staged
```
### For Users
- **Use environment variables** for all secrets
- **Never hardcode** tokens in config files
- Store `agent-orchestrator.yaml` securely (it's in `.gitignore`)
- Rotate tokens regularly
See [SECURITY.md](./SECURITY.md) for detailed security practices and how to report vulnerabilities.
## Required Secrets
Depending on which features you use, you may need:
| Service | Environment Variable | Where to Get |
|---------|---------------------|--------------|
| GitHub | `GITHUB_TOKEN` | https://github.com/settings/tokens |
| Linear | `LINEAR_API_KEY` | https://linear.app/settings/api |
| Slack | `SLACK_WEBHOOK_URL` | https://api.slack.com/messaging/webhooks |
| Anthropic | `ANTHROPIC_API_KEY` | https://console.anthropic.com/ |
- Stateless orchestrator (filesystem > database)
- Plugin everything (no vendor lock-in)
- Amplify judgment, don't bypass it
- Auto-handle routine, escalate complex decisions
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `pnpm test`
5. Run linting: `pnpm lint && pnpm typecheck`
6. Commit (pre-commit hook will scan for secrets)
7. Open a pull request
See [CLAUDE.md](./CLAUDE.md) for code conventions and architecture details.
Contributions welcome! See `CLAUDE.md` for code conventions and architecture details.
## License
MIT — see [LICENSE](./LICENSE) file.
MIT
## Responsible Disclosure
## Links
If you discover a security vulnerability, please report it to security@composio.dev. See [SECURITY.md](./SECURITY.md) for details.
## Tech Stack
- **TypeScript** (ESM modules, strict mode)
- **Node 20+**
- **pnpm** workspaces
- **Next.js 15** (App Router) + Tailwind
- **Commander.js** CLI
- **YAML + Zod** config
- **Server-Sent Events** for real-time
- **ESLint + Prettier**
- **vitest** for testing
## Resources
- **Documentation**: See individual package READMEs
- **Core types**: [`packages/core/src/types.ts`](./packages/core/src/types.ts)
- **Example config**: [`agent-orchestrator.yaml.example`](./agent-orchestrator.yaml.example)
- **Security policy**: [SECURITY.md](./SECURITY.md)
- **Code conventions**: [CLAUDE.md](./CLAUDE.md)
- [Setup Guide](SETUP.md) - Detailed setup and configuration
- [Examples](examples/) - Config templates for common use cases
- [CLAUDE.md](CLAUDE.md) - Code conventions and architecture
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and fixes