diff --git a/.changeset/config.json b/.changeset/config.json index ecac5bfc7..2c78a2b6c 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -7,7 +7,7 @@ [ "@composio/ao-core", "@composio/ao-cli", - "@composio/agent-orchestrator", + "@composio/ao", "@composio/ao-plugin-runtime-tmux", "@composio/ao-plugin-runtime-process", "@composio/ao-plugin-agent-claude-code", diff --git a/README.md b/README.md index 334119016..e455aebba 100644 --- a/README.md +++ b/README.md @@ -44,78 +44,63 @@ Agent Orchestrator manages fleets of AI coding agents working in parallel on you ## Quick Start -**Option A — Install via npm (recommended):** - -```bash -npm install -g @composio/agent-orchestrator - -# Permission denied? Use one of these: -sudo npm install -g @composio/agent-orchestrator # quick fix -npx @composio/agent-orchestrator # no install needed -``` - > **Prerequisites:** [Node.js 20+](https://nodejs.org), [Git 2.25+](https://git-scm.com), [tmux](https://github.com/tmux/tmux/wiki/Installing), [`gh` CLI](https://cli.github.com). Install tmux via `brew install tmux` (macOS) or `sudo apt install tmux` (Linux). -**Option B — Install from source (for contributors):** +### Install + +```bash +npm install -g @composio/ao +``` + +
+Permission denied? Install from source? + +If `npm install -g` fails with EACCES, prefix with `sudo` or [fix your npm permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). + +To install from source (for contributors): ```bash git clone https://github.com/ComposioHQ/agent-orchestrator.git cd agent-orchestrator && bash scripts/setup.sh ``` +
-Then set up your project: +### Start + +Point it at any repo — it clones, configures, and launches the dashboard in one command: ```bash -# From a repo URL (fastest — clones, configures, and launches in one command) ao start https://github.com/your-org/your-repo +``` -# Or from an existing local repo -cd ~/your-project && ao start # auto-detects everything, zero prompts +Or from inside an existing local repo: -# Add more projects to an existing setup +```bash +cd ~/your-project && ao start +``` + +That's it. The dashboard opens at `http://localhost:3000` and the orchestrator agent starts managing your project. + +### Add more projects + +```bash ao start ~/path/to/another-repo ``` -Spawn agents: - -```bash -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. **You start** — `ao start` launches the dashboard and an orchestrator agent +2. **Orchestrator spawns workers** — each issue gets its own agent in an isolated git worktree +3. **Agents work autonomously** — they read code, write tests, create PRs +4. **Reactions handle feedback** — CI failures and review comments are automatically routed back to the agent +5. **You review and merge** — you only get pulled in when human judgment is needed -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. +The orchestrator agent uses the [AO CLI](docs/CLI.md) internally to manage sessions. You don't need to learn or use the CLI — the dashboard and orchestrator handle everything. ## Configuration +`ao start` auto-generates `agent-orchestrator.yaml` with sensible defaults. You can edit it afterwards to customize behavior: + ```yaml # agent-orchestrator.yaml port: 3000 @@ -149,39 +134,24 @@ reactions: 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. +See [`agent-orchestrator.yaml.example`](agent-orchestrator.yaml.example) for the full reference, or run `ao config-help` for the complete schema. -## CLI +## Plugin Architecture -```bash -ao start # Auto-detect project, generate config, and start -ao start ~/other-repo # Add a new project and start -ao config-help # Show full config schema reference -ao status # Overview of all sessions -ao spawn [issue] # Spawn an agent (project auto-detected) -ao send "Fix the tests" # Send instructions -ao session ls # List sessions -ao session kill # Kill a session -ao session restore # Revive a crashed agent -ao dashboard # Open web dashboard -ao doctor [--fix] # Check install, runtime, and stale temp issues -ao update # Update local AO install and run smoke tests -``` +Eight slots. Every abstraction is swappable. -## Maintenance +| 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 | — | -```bash -# Run deterministic install and runtime checks -ao doctor - -# Apply safe cleanup and launcher fixes -ao doctor --fix - -# Update this local AO checkout, rebuild critical packages, and verify the launcher -ao update -``` - -`ao doctor` checks PATH and launcher resolution, required binaries, tmux and GitHub CLI health, config support directories, stale AO temp files, and core build/runtime sanity. `ao update` fast-forwards the local install repo on `main`, runs `pnpm install`, clean-rebuilds `@composio/ao-core`, `@composio/ao-cli`, and `@composio/ao-web`, refreshes the global `ao` launcher with `npm link`, and finishes with CLI smoke tests. +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. ## Why Agent Orchestrator? @@ -189,14 +159,17 @@ Running one AI agent in a terminal is easy. Running 30 across different issues, **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. +**With Agent Orchestrator**, you: `ao start` and walk away. The system handles isolation, feedback routing, and status tracking. You review PRs and make decisions — the rest is automated. -## Prerequisites +## Documentation -- Node.js 20+ -- Git 2.25+ -- tmux (for default runtime) -- `gh` CLI (for GitHub integration) +| Doc | What it covers | +| ---------------------------------------- | ------------------------------------------------------------ | +| [Setup Guide](SETUP.md) | Detailed installation, configuration, and troubleshooting | +| [CLI Reference](docs/CLI.md) | All `ao` commands (mostly used by the orchestrator agent) | +| [Examples](examples/) | Config templates (GitHub, Linear, multi-project, auto-merge) | +| [Development Guide](docs/DEVELOPMENT.md) | Architecture, conventions, plugin pattern | +| [Contributing](CONTRIBUTING.md) | How to contribute, build plugins, PR process | ## Development @@ -208,16 +181,6 @@ pnpm dev # Start web dashboard dev server See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.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) | -| [Development Guide](docs/DEVELOPMENT.md) | Architecture, conventions, plugin pattern | -| [Contributing](CONTRIBUTING.md) | How to contribute, build plugins, PR process | -| [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 [CONTRIBUTING.md](CONTRIBUTING.md) and the [Development Guide](docs/DEVELOPMENT.md) for the pattern. diff --git a/SETUP.md b/SETUP.md index 9b1cf58d1..e745b5daa 100644 --- a/SETUP.md +++ b/SETUP.md @@ -60,7 +60,7 @@ Comprehensive guide to installing, configuring, and troubleshooting Agent Orches ### Install via npm (recommended) ```bash -npm install -g @composio/agent-orchestrator +npm install -g @composio/ao # Verify ao --version @@ -72,17 +72,17 @@ This installs the `ao` CLI globally along with all default plugins and the web d ```bash # Option 1: Use sudo -sudo npm install -g @composio/agent-orchestrator +sudo npm install -g @composio/ao # Option 2: Use npx (no global install needed) -npx @composio/agent-orchestrator start +npx @composio/ao start # Option 3: Fix npm permissions permanently (recommended) mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc -npm install -g @composio/agent-orchestrator +npm install -g @composio/ao ``` ### Build from Source (for contributors) @@ -103,24 +103,19 @@ ao --version The setup script handles pnpm installation, dependency resolution, building all packages, and linking the `ao` command globally (with automatic permission handling on macOS). -## First-Time Configuration +## First-Time Setup -### Quick Onboarding with `ao start ` +### `ao start` — the only command you need -The fastest way to get started with any repo: +`ao start` handles everything: auto-detecting your project, generating config, and launching the dashboard + orchestrator. There are three ways to use it: + +**From a URL (fastest for any repo):** ```bash ao start https://github.com/your-org/your-repo ``` -This single command will: - -1. **Clone** the repo (or reuse an existing clone) -2. **Auto-detect** language, package manager, SCM platform, and default branch -3. **Generate** `agent-orchestrator.yaml` with smart defaults -4. **Start** the dashboard and orchestrator agent - -Supports GitHub, GitLab, and Bitbucket URLs (HTTPS and SSH): +This clones the repo, auto-detects language/framework/branch, generates `agent-orchestrator.yaml`, and starts everything. Supports GitHub, GitLab, and Bitbucket (HTTPS and SSH): ```bash ao start https://github.com/owner/repo @@ -128,45 +123,36 @@ ao start https://gitlab.com/org/project ao start git@github.com:owner/repo.git ``` -If the repo already has an `agent-orchestrator.yaml`, it will be used as-is. - -### Quick Setup with `ao init` - -For more control over configuration: +**From a local repo (zero prompts):** ```bash -cd ~/your-repo -ao init +cd ~/your-project +ao start ``` -The wizard will prompt you for: +Auto-detects git remote, default branch, language, and available agent runtimes. Generates config and starts. -1. **Data directory** - Where to store session metadata (default: `~/.agent-orchestrator`) -2. **Worktree directory** - Where to create isolated workspaces (default: `~/.worktrees`) -3. **Dashboard port** - Web interface port (default: `3000`) -4. **Runtime plugin** - Session runtime (default: `tmux`) -5. **Agent plugin** - AI coding assistant (default: `claude-code`) -6. **Workspace plugin** - Workspace isolation method (default: `worktree`) -7. **Notifiers** - Notification channels (default: `desktop`) -8. **Project ID** - Short name for your project -9. **GitHub repo** - Repository in `owner/repo` format -10. **Local path** - Path to your repository -11. **Default branch** - Main branch name (usually `main` or `master`) +**Adding more projects:** -### What `ao init` Detects Automatically +```bash +ao start ~/path/to/another-repo +``` -The wizard is smart and tries to help: +If a config already exists, the new project is appended. If not, one is created first. -- **Git repository** - Detects if you're in a git repo -- **GitHub remote** - Parses `owner/repo` from git remote -- **Current branch** - Suggests default branch from git -- **API keys** - Checks for `LINEAR_API_KEY` in environment -- **GitHub auth** - Verifies `gh` CLI authentication status -- **tmux availability** - Warns if tmux is not installed +### What `ao start` detects automatically + +- **Git remote** — parses `owner/repo` from origin +- **Default branch** — checks symbolic-ref, GitHub API, then common names (main/master) +- **Project type** — language, framework, test runner, package manager +- **Agent runtime** — which AI agents are installed (Claude Code, Codex, Aider, OpenCode) +- **Free port** — if configured port is busy, auto-finds the next available +- **tmux** — warns if not installed +- **GitHub CLI** — checks `gh auth status` ### Manual Configuration -If you prefer to write the config manually: +If you prefer to write the config by hand: ```bash cp agent-orchestrator.yaml.example agent-orchestrator.yaml @@ -184,13 +170,9 @@ nano agent-orchestrator.yaml ### Minimal Configuration -The absolute minimum needed: +The absolute minimum needed (everything else has sensible defaults): ```yaml -dataDir: ~/.agent-orchestrator -worktreeDir: ~/.worktrees -port: 3000 - projects: my-app: repo: owner/my-app @@ -198,6 +180,8 @@ projects: defaultBranch: main ``` +`ao start` generates this automatically — you only need to write it manually if you want full control. + ### Full Configuration Schema See [agent-orchestrator.yaml.example](./agent-orchestrator.yaml.example) for a fully commented example with all options. @@ -437,10 +421,10 @@ ao update **Solution:** ```bash -# Run init wizard -ao init +# ao start auto-creates the config if none exists +ao start -# Or copy an example +# Or copy an example and edit manually cp examples/simple-github.yaml agent-orchestrator.yaml ``` @@ -504,7 +488,7 @@ echo $LINEAR_API_KEY **Problem:** Another service is using the dashboard port (default 3000). -**Solution:** +**Note:** `ao start` automatically finds the next free port if the configured port is busy. You'll see a message like "Port 3000 is busy — using 3001 instead." If you still need to fix it manually: ```bash # Option 1: Change port in agent-orchestrator.yaml @@ -514,8 +498,6 @@ port: 3001 lsof -ti:3000 | xargs kill ``` -**Note:** When running multiple projects, each needs a different `port:` value in its config. - ### "Workspace creation failed" **Problem:** Orchestrator can't create worktrees or clones. @@ -565,7 +547,7 @@ ao send "Please report your current status" # Kill and respawn if necessary ao session kill -ao spawn +ao spawn ``` ### "Permission denied" when spawning @@ -813,7 +795,7 @@ ao open # Kill and respawn if necessary ao session kill -ao spawn +ao spawn ``` Agents also send "stuck" notifications automatically after inactivity threshold. @@ -849,12 +831,12 @@ Useful for: ## Next Steps -1. **Run `ao init`** - Create your first config -2. **Spawn an agent** - `ao spawn my-app ISSUE-123` -3. **Monitor progress** - `ao status` or dashboard -4. **Read [Development Guide](./docs/DEVELOPMENT.md)** - Code conventions and architecture -5. **Explore examples** - See [examples/](./examples/) for more configs -6. **Join the community** - Report issues, share configs, contribute plugins +1. **Start the orchestrator** — `ao start` (auto-creates config on first run) +2. **Spawn an agent** — `ao spawn 123` (project auto-detected from cwd) +3. **Monitor progress** — `ao status` or dashboard at http://localhost:3000 +4. **Read [Development Guide](./docs/DEVELOPMENT.md)** — Code conventions and architecture +5. **Explore examples** — See [examples/](./examples/) for more configs +6. **Join the community** — Report issues, share configs, contribute plugins --- diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 000000000..c673b9558 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,41 @@ +# AO CLI Reference + +The `ao` CLI is the control interface for Agent Orchestrator. Most commands are used by the **orchestrator agent itself** to manage sessions, not by humans directly. Humans typically only need `ao start` and the web dashboard. + +## Commands humans use + +```bash +ao start # Auto-detect, generate config, start dashboard + orchestrator +ao start # Clone repo, auto-configure, and start +ao start ~/other-repo # Add a new project and start +ao stop # Stop everything (dashboard, orchestrator, lifecycle worker) +ao status # Overview of all sessions +ao dashboard # Open web dashboard in browser +``` + +## Commands the orchestrator agent uses + +These are primarily invoked by the orchestrator agent running inside a tmux session. You can use them manually if needed, but the orchestrator handles this automatically. + +```bash +ao spawn [issue] # Spawn an agent (project auto-detected from cwd) +ao spawn 123 --agent codex # Override agent for this session +ao batch-spawn 101 102 103 # Spawn agents for multiple issues at once +ao send "Fix the tests" # Send instructions to a running agent +ao session ls # List sessions +ao session kill # Kill a session +ao session restore # Revive a crashed agent +``` + +## Maintenance commands + +```bash +ao doctor # Check install, runtime, and stale temp issues +ao doctor --fix # Apply safe fixes automatically +ao update # Update local AO install (source installs only) +ao config-help # Show full config schema reference +``` + +`ao doctor` checks PATH and launcher resolution, required binaries, tmux and GitHub CLI health, config support directories, stale AO temp files, and core build/runtime sanity. + +`ao update` fast-forwards the local install on `main`, reinstalls dependencies, clean-rebuilds core packages, refreshes the launcher, and runs smoke tests. Use `ao update --skip-smoke` to stop after rebuild, or `ao update --smoke-only` to rerun just the smoke checks. diff --git a/packages/agent-orchestrator/bin/ao.js b/packages/ao/bin/ao.js similarity index 100% rename from packages/agent-orchestrator/bin/ao.js rename to packages/ao/bin/ao.js diff --git a/packages/agent-orchestrator/package.json b/packages/ao/package.json similarity index 86% rename from packages/agent-orchestrator/package.json rename to packages/ao/package.json index 0443b9f6f..1ad077035 100644 --- a/packages/agent-orchestrator/package.json +++ b/packages/ao/package.json @@ -1,5 +1,5 @@ { - "name": "@composio/agent-orchestrator", + "name": "@composio/ao", "version": "0.1.0", "description": "Orchestrate parallel AI coding agents — global CLI wrapper", "license": "MIT", @@ -13,7 +13,7 @@ "repository": { "type": "git", "url": "https://github.com/ComposioHQ/agent-orchestrator.git", - "directory": "packages/agent-orchestrator" + "directory": "packages/ao" }, "homepage": "https://github.com/ComposioHQ/agent-orchestrator", "bugs": { diff --git a/packages/cli/src/lib/web-dir.ts b/packages/cli/src/lib/web-dir.ts index 0314a99ae..63e9c613c 100644 --- a/packages/cli/src/lib/web-dir.ts +++ b/packages/cli/src/lib/web-dir.ts @@ -181,7 +181,7 @@ export function findWebDir(): string { } throw new Error( "Could not find @composio/ao-web package.\n" + - " If installed via npm: npm install -g @composio/agent-orchestrator\n" + + " If installed via npm: npm install -g @composio/ao\n" + " If cloned from source: pnpm install && pnpm build", ); } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e06c6bf97..3893d7c74 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -33,7 +33,7 @@ importers: specifier: ^8.55.0 version: 8.55.0(eslint@10.0.0(jiti@2.6.1))(typescript@5.9.3) - packages/agent-orchestrator: + packages/ao: dependencies: '@composio/ao-cli': specifier: workspace:*