npm install -g @aoagents/ao

npm install -g @aoagents/ao@nightly

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
bash scripts/setup.sh

ao start https://github.com/your-org/your-repo

cd ~/your-project
ao start

ao start ~/path/to/project-one
ao start https://github.com/org/project-two

$schema: https://raw.githubusercontent.com/ComposioHQ/agent-orchestrator/main/schema/config.schema.json
port: 3000

defaults:
  runtime: tmux       # tmux on macOS/Linux, process on Windows
  agent: claude-code  # or codex, aider, cursor, opencode, kimicode
  workspace: worktree # or clone
  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  # Set to true for auto-merge
    action: notify

power:
  preventIdleSleep: true  # Keeps Mac awake for remote access

projects:
  frontend:
    repo: org/frontend
    path: ~/work/frontend
    defaultBranch: main
    sessionPrefix: fe
    
  backend:
    repo: org/backend
    path: ~/work/backend
    defaultBranch: develop
    sessionPrefix: be
    
  docs:
    repo: org/documentation
    path: ~/work/docs
    defaultBranch: main
    sessionPrefix: docs

# List all active sessions
ao list

# Start a new agent session
ao new "Fix login validation bug" --project my-app --issue 123

# Attach to existing session
ao attach my-app-fix-login

# Stop a session
ao stop my-app-fix-login

# Stop all sessions for a project
ao stop --project my-app --all

# Add project
ao add-project ~/path/to/repo

# Remove project
ao remove-project my-app

# Show configuration
ao config-help

# Show all sessions and their status
ao status

# Show detailed session info
ao status my-app-fix-login

# View logs
ao logs my-app-fix-login

# Generate completion file
mkdir -p ~/.zsh/completions
ao completion zsh > ~/.zsh/completions/_ao

# Add to ~/.zshrc before compinit
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

defaults:
  runtime: tmux  # or process, docker

defaults:
  agent: claude-code  # or codex, aider, cursor, opencode, kimicode

export interface AgentPlugin {
  name: string;
  start(config: AgentConfig): Promise<void>;
  stop(sessionId: string): Promise<void>;
  sendMessage(sessionId: string, message: string): Promise<void>;
  getStatus(sessionId: string): Promise<AgentStatus>;
}

defaults:
  workspace: worktree  # or clone

defaults:
  tracker: github  # or linear, gitlab

defaults:
  notifiers: [desktop, slack]  # Available: desktop, slack, discord, composio, webhook, openclaw

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
    message: "CI failed with the following errors: {{errors}}"

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
    message: "Reviewer requested: {{comments}}"

reactions:
  approved-and-green:
    auto: true  # Enable auto-merge
    action: merge
    strategy: squash  # or merge, rebase
    deleteAfter: true

reactions:
  label-added:
    auto: true
    condition: "label == 'needs-tests'"
    action: send-to-agent
    message: "Please add tests for this change"

import { SessionManager } from '@aoagents/core';

const manager = new SessionManager();

const session = await manager.create({
  projectId: 'my-app',
  name: 'fix-auth-bug',
  issue: 'GH-456',
  branch: 'fix/auth-validation',
  agent: 'claude-code',
  runtime: 'tmux',
  workspace: 'worktree'
});

// Session is now running in isolated worktree
console.log(`Session ${session.id} started at ${session.workspacePath}`);

# Via CLI
ao send my-app-fix-auth "Review the authentication flow in src/auth.ts"

# Via API
ao api POST /sessions/my-app-fix-auth/message -d '{"content":"Check the auth flow"}'

import { SessionManager } from '@aoagents/core';

const manager = new SessionManager();
const status = await manager.getStatus('my-app-fix-auth');

console.log(`Agent: ${status.agent}`);
console.log(`State: ${status.state}`);  // idle, working, waiting, error
console.log(`Current task: ${status.currentTask}`);
console.log(`Branch: ${status.branch}`);
console.log(`Workspace: ${status.workspacePath}`);

# Worktrees are automatically created under:
~/my-app/.worktrees/fix-auth-bug/

# Each worktree has its own:
# - Working directory
# - HEAD pointer
# - Index
# - Branch

# Cleanup happens automatically on session stop
ao stop my-app-fix-auth

# Manual cleanup if needed
cd ~/my-app
git worktree remove .worktrees/fix-auth-bug
git branch -D fix/auth-validation

curl http://localhost:3000/api/sessions

curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "my-app",
    "issue": "GH-789",
    "title": "Add user export feature"
  }'

curl http://localhost:3000/api/sessions/my-app-export/status

curl -X POST http://localhost:3000/api/sessions/my-app-export/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Export to CSV format"}'

curl -X DELETE http://localhost:3000/api/sessions/my-app-export

// plugins/agent-custom/src/index.ts
import { AgentPlugin, AgentConfig, AgentStatus } from '@aoagents/core';

export class CustomAgentPlugin implements AgentPlugin {
  name = 'custom-agent';
  
  async start(config: AgentConfig): Promise<void> {
    // Initialize agent in workspace
    const { workspacePath, sessionId, task } = config;
    
    // Launch agent process
    // Set up communication channel
    // Return when ready
  }
  
  async stop(sessionId: string): Promise<void> {
    // Cleanup agent process
    // Save state if needed
  }
  
  async sendMessage(sessionId: string, message: string): Promise<void> {
    // Forward message to agent
  }
  
  async getStatus(sessionId: string): Promise<AgentStatus> {
    return {
      state: 'working',
      currentTask: 'Analyzing codebase',
      lastActivity: new Date()
    };
  }
}

export default {
  agent: new CustomAgentPlugin()
};

// plugins/notifier-telegram/src/index.ts
import { NotifierPlugin, Notification } from '@aoagents/core';

export class TelegramNotifierPlugin implements NotifierPlugin {
  name = 'telegram';
  
  constructor(private botToken: string, private chatId: string) {}
  
  async notify(notification: Notification): Promise<void> {
    const { title, message, level, sessionId } = notification;
    
    const text = `*${title}*\n${message}\nSession: ${sessionId}`;
    
    await fetch(`https://api.telegram.org/bot${this.botToken}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        chat_id: this.chatId,
        text,
        parse_mode: 'Markdown'
      })
    });
  }
}

export default {
  notifier: new TelegramNotifierPlugin(
    process.env.TELEGRAM_BOT_TOKEN!,
    process.env.TELEGRAM_CHAT_ID!
  )
};

# Agent credentials
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# GitHub integration
export GITHUB_TOKEN=ghp_...

# Notifier credentials
export SLACK_WEBHOOK_URL=https://hooks.slack.com/...
export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Windows shell preference
export AO_SHELL=bash  # Use Git Bash instead of PowerShell

# Custom config location
export AO_CONFIG=~/custom/agent-orchestrator.yaml

# Error: worktree already exists
# Solution: Clean up manually
git worktree remove .worktrees/session-name --force
git branch -D branch-name

# Install tmux
brew install tmux       # macOS
sudo apt install tmux   # Ubuntu/Debian

# Or switch to process runtime
ao config set defaults.runtime process

# Check session logs
ao logs session-name

# Check agent process
ao status session-name

# Restart session
ao stop session-name
ao new "Same task" --project my-app --issue 123

# agent-orchestrator.yaml
port: 3001  # Change from default 3000

# Re-authenticate gh CLI
gh auth login

# Verify token has required scopes
gh auth status

# Agent handles automatically via reaction
# Or attach and resolve manually
ao attach session-name
# Inside session: resolve conflicts, commit, push

# Keep Mac awake for remote dashboard access
power:
  preventIdleSleep: true  # Default on macOS

# Clone and build
git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
pnpm install
pnpm build

# Run tests (3,288 test cases)
pnpm test

# Start dev server
pnpm dev

# Build plugins
cd packages/plugin-agent-custom
pnpm build

// orchestrator-custom.ts
import { OrchestratorAgent, Task, SessionManager } from '@aoagents/core';

class CustomOrchestrator extends OrchestratorAgent {
  async plan(goal: string): Promise<Task[]> {
    // Custom planning logic
    const tasks = await this.breakdownGoal(goal);
    
    return tasks.map(task => ({
      id: this.generateId(),
      title: task.title,
      description: task.description,
      dependencies: task.deps,
      estimatedEffort: task.effort
    }));
  }
  
  async spawn(task: Task): Promise<string> {
    const manager = new SessionManager();
    
    const session = await manager.create({
      projectId: this.projectId,
      name: this.toSessionName(task.title),
      issue: task.id,
      branch: this.toBranchName(task.title),
      agent: this.selectAgent(task),
      runtime: 'tmux',
      workspace: 'worktree'
    });
    
    return session.id;
  }
}