ComposioHQ/agent-orchestrator

각각 자신의 git worktree 내에서 병렬로 실행되는 AI 코딩 에이전트(AI coding agents)를 생성하세요. 에이전트들은 CI 실패를 자율적으로 수정하고, 리뷰 코멘트를 처리하며, PR(Pull Request)을 생성합니다 — 당신은 하나의 대시보드에서 이를 감독하기만 하면 됩니다.

Agent Orchestrator는 당신의 코드베이스에서 병렬로 작동하는 AI 코딩 에이전트 군단을 관리합니다. 각 에이전트는 자신만의 git worktree, 자신만의 브랜치(branch), 그리고 자신만의 PR을 가집니다. CI가 실패하면 에이전트가 이를 수정합니다. 리뷰어가 코멘트를 남기면 에이전트가 이를 처리합니다. 당신은 오직 인간의 판단이 필요할 때만 개입하면 됩니다.

에이전트 불가지론 (Agent-agnostic) (Claude Code, Codex, Aider) · 런타임 불가지론 (Runtime-agnostic) (tmux, ConPTY/process, Docker) · 트래커 불가지론 (Tracker-agnostic) (GitHub, Linear)

사전 요구 사항:
Node.js 20+, Git 2.25+, gh CLI, 그리고:

macOS / Linux: tmux — brew install tmux 또는 sudo apt install tmux를 통해 설치

Windows: PowerShell 7+ 권장. tmux는 필수 사항이 아닙니다 — AO는 runtime-process 플러그인(Windows 기본값)을 통해 네이티브 ConPTY를 사용합니다. 만약 Git Bash를 사용하고 이를 선호한다면 AO_SHELL=bash로 설정하세요.

npm install -g @aoagents/ao

나이틀리 빌드 (최신 main 브랜치, 금~화 매일 제공): npm install -g @aoagents/ao@nightly

안정 버전으로 복구: npm install -g @aoagents/ao@latest

권한 거부(Permission denied)? 소스에서 설치하시겠습니까?

npm install -g 실행 시 EACCES 오류가 발생하면, 앞에 sudo를 붙이거나 npm 권한을 수정하세요.

소스에서 설치하려면 (기여자용):

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

설치된 CLI로부터 자동 완성(completion) 파일을 생성하세요:

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

그 다음 compinit이 실행되기 전에 해당 디렉토리가 fpath에 포함되어 있는지 확인하세요:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

Oh My Zsh의 경우, 동일하게 생성된 파일을 커스텀 플러그인 디렉토리에 설치하고 플러그인 목록에 ao를 추가하세요:

mkdir -p "${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/ao"
ao completion zsh > "${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/ao/_ao"

소스 체크아웃 (source checkout) 상태에서 기여하는 경우, 저장소 복사본을 completions/_ao에 심볼릭 링크 (symlink)로 연결할 수도 있습니다.

어떤 저장소든 지정하면 단 하나의 명령어로 클론 (clone), 설정, 대시보드 실행을 수행합니다:

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

또는 기존 로컬 저장소 내부에서 다음과 같이 실행할 수 있습니다:

cd ~/your-project && ao start

그게 전부입니다. 대시보드가 http://localhost:3000에서 열리고, 오케스트레이터 에이전트 (orchestrator agent)가 프로젝트 관리를 시작합니다.

ao start ~/path/to/another-repo

사용자가 시작합니다 — ao start가 대시보드와 오케스트레이터 에이전트를 실행합니다.
오케스트레이터가 워커 (workers)를 생성합니다 — 각 이슈 (issue)는 격리된 git 워크트리 (worktree) 내에서 자신만의 에이전트를 갖게 됩니다.
에이전트가 자율적으로 작업합니다 — 코드를 읽고, 테스트를 작성하며, PR (Pull Request)을 생성합니다.
반응 (Reactions)이 피드백을 처리합니다 — CI 실패 및 리뷰 코멘트가 에이전트에게 자동으로 다시 전달됩니다.
사용자가 검토하고 머지 (merge)합니다 — 인간의 판단이 필요한 경우에만 개입하면 됩니다.

오케스트레이터 에이전트는 세션 관리를 위해 내부적으로 AO CLI를 사용합니다. 사용자가 CLI를 직접 배우거나 사용할 필요는 없습니다. 대시보드와 오케스트레이터가 모든 것을 처리합니다.

ao start는 합리적인 기본값(sensible defaults)을 포함하여 agent-orchestrator.yaml 파일을 자동으로 생성합니다. 이후에 이 파일을 편집하여 동작을 커스텀할 수 있습니다:

# agent-orchestrator.yaml
$schema: https://raw.githubusercontent.com/ComposioHQ/agent-orchestrator/main/schema/config.schema.json
# 런타임 데이터는 ~/.agent-orchestrator/{hash}-{projectId}/ 아래에 자동으로 파생됩니다.
...

CI가 실패하면 → 에이전트가 로그를 전달받아 수정합니다. 리뷰어가 변경을 요청하면 → 에이전트가 이를 해결합니다. CI가 통과된 상태로 PR이 승인되면 → 머지할 수 있도록 알림이 전송됩니다.

에디터가 schema/config.schema.json을 기준으로 자동 완성 및 유효성 검사를 수행할 수 있도록 $schema 라인을 유지해 주세요.

전체 참조를 보려면 agent-orchestrator.yaml.example을 확인하거나, 전체 스키마(schema)를 보려면 ao config-help를 실행하세요.

AO는 실행 중인 동안 Mac이 잠자기 모드로 들어가지 않도록 유지하므로, 기기가 잠들지 않은 상태에서 원격으로(예: 휴대폰에서 Tailscale을 통해) 대시보드에 접속할 수 있습니다.

작동 방식: macOS에서 AO는 caffeinate를 사용하여 유휴 상태 수면 방지 어설션 (idle-sleep prevention assertion)을 자동으로 유지합니다. AO가 종료되면 해당 어설션은 해제됩니다.

# agent-orchestrator.yaml
$schema: https://raw.githubusercontent.com/ComposioHQ/agent-orchestrator/main/schema/config.schema.json
power:
...

AO가 실행되는 동안 유휴 상태 수면 (idle sleep)을 허용하려면 false로 설정하십시오.

덮개 닫기 제한 (Lid-close limitation): macOS는 하드웨어 수준에서 덮개를 닫을 때의 수면을 강제하며, 사용자 공간 어설션 (userspace assertion)으로는 이를 무시할 수 없습니다. 덮개를 닫은 채 이동하는 동안 원격 접속이 필요한 경우, 클램쉘 모드 (clamshell mode, 외부 전원 + 디스플레이 + 입력 장치)를 사용하십시오.

Linux / Windows: AO는 현재 이 플랫폼들에서 웨이크 어설션 (wake assertion)을 유지하지 않습니다. Linux의 경우, 유휴 상태 수면 동작은 데스크톱 환경 또는 systemd-logind에 의해 제어되므로 이를 직접 구성하십시오. Windows의 경우, 유휴 상태에서 원격 접속이 중요하다면 OS 전원 계획을 설정하십시오.

7개의 플러그인 슬롯. 라이프사이클 (Lifecycle)은 코어 (core)에 유지됩니다.

슬롯 (Slot)	기본값 (Default)	대안 (Alternatives)
런타임 (Runtime)	tmux (macOS/Linux) / process (Windows)	process, docker
...

모든 인터페이스는 packages/core/src/types.ts에 정의되어 있습니다. 플러그인은 하나의 인터페이스를 구현하고 PluginModule을 내보내기 (export) 합니다. 그것이 전부입니다.

터미널에서 하나의 AI 에이전트를 실행하는 것은 쉽습니다. 하지만 서로 다른 이슈, 브랜치, PR에 걸쳐 30개의 에이전트를 실행하는 것은 조정 (coordination)의 문제입니다.

오케스트레이션 (orchestration)이 없는 경우, 사용자는 수동으로 다음 작업을 수행해야 합니다: 브랜치 생성, 에이전트 시작, 에이전트가 멈췄는지 확인, CI 실패 확인, 리뷰 코멘트 전달, 머지 (merge) 준비가 된 PR 추적, 작업 완료 후 정리.

Agent Orchestrator를 사용하는 경우, ao start를 입력하고 자리를 비우면 됩니다. 시스템이 격리 (isolation), 피드백 라우팅 (feedback routing), 상태 추적 (status tracking)을 처리합니다. 사용자는 PR을 검토하고 결정을 내리기만 하면 되며, 나머지는 자동화됩니다.

문서 (Doc)	다루는 내용
설정 가이드 (Setup Guide)	상세 설치, 구성 및 문제 해결
...

pnpm install && pnpm build # 모든 패키지 설치 및 빌드
pnpm test # 테스트 실행 (3,288개 테스트 케이스)
pnpm dev # 웹 대시보드 개발 서버 시작

코드 컨벤션 (code conventions) 및 아키텍처 (architecture) 상세 내용은 docs/DEVELOPMENT.md를 참조하세요.

기여를 환영합니다. 플러그인 시스템 (plugin system)을 통해 새로운 에이전트 (agents), 런타임 (runtimes), 트래커 (trackers) 및 알림 채널 (notification channels)에 대한 지원을 간편하게 추가할 수 있습니다. 모든 플러그인은 TypeScript 인터페이스 (interface)의 구현체입니다. 해당 패턴에 대해서는 CONTRIBUTING.md 및 개발 가이드 (Development Guide)를 참조하세요.

MIT