diff --git a/README.md b/README.md index f34f077e7..2b249fa64 100644 --- a/README.md +++ b/README.md @@ -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 "Fix the linting errors" + +# Kill session +ao session kill +``` + +### 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