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

Merge pull request #537 from suraj-markup/feat/onboarding-improvements 

feat: zero-friction onboarding — ao start does everything
This commit is contained in:
suraj_markup 2026-03-19 07:52:31 +05:30 committed by GitHub
parent 178af32682 78a4233282
commit a99aedf9a8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 148 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.changeset/config.json
View File

@ -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",

153
README.md
View File

@ -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
```
<details>
<summary>Permission denied? Install from source?</summary>
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
```
</details>
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 <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
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.

106
SETUP.md
View File

@ -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 <url>`
### `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 <session-name> "Please report your current status"
# Kill and respawn if necessary
ao session kill <session-name>
ao spawn <project-id> <issue-id>
ao spawn <issue-id>
```
### "Permission denied" when spawning
@ -813,7 +795,7 @@ ao open <session-name>
# Kill and respawn if necessary
ao session kill <session-name>
ao spawn <project-id> <issue-id>
ao spawn <issue-id>
```
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
---

41
docs/CLI.md Normal file
View File

@ -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 <url> # 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 <session> "Fix the tests" # Send instructions to a running agent
ao session ls # List sessions
ao session kill <session> # Kill a session
ao session restore <session> # 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.

0
packages/agent-orchestrator/bin/ao.js → packages/ao/bin/ao.js
View File

4
packages/agent-orchestrator/package.json → packages/ao/package.json
View File

@ -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": {

2
packages/cli/src/lib/web-dir.ts
View File

@ -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",
);
}

2
pnpm-lock.yaml
View File

@ -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:*