Install & Run
npm i -g @oxgeneral/orch
orch Turn your AI tools into a coordinated engineering team. Orchestrate Claude, Codex, Cursor & OpenCode as one — with state machine, retry, inter-agent messaging, goals and git isolation.
orch = orchestry = ao
Task Management
orch task add <title>
-d Description
-p <1-4> Priority (default: 3)
-l <labels> Comma-sep labels
--depends-on Task ID deps
--assignee Agent ID
--review-criteria test_pass,typecheck,lint
--scope File glob patterns
--attach Attach files
-e Open $EDITOR
orch task list --status filter
orch task show <id>
orch task edit <id> Open in $EDITOR
orch task assign <task> <agent>
orch task approve <id> Approve review
orch task reject <id> -r reason
orch task retry <id>
orch task cancel <id>
Agent Management
orch agent add <name>
--adapter claude|codex|cursor|opencode|shell req
--role Agent role description
--model LLM model name
--skills Comma-sep skills
--approval-policy auto|suggest|manual
--workspace-mode shared|worktree|isolated
--max-turns Max turns per run
-e Open $EDITOR
orch agent shop Browse templates
orch agent list
orch agent status <id>
orch agent edit <id>
orch agent enable/disable <id>
orch agent autonomous <id> --on/--off
orch agent remove <id>
Execution
orch run <task-id> Run single task
orch run --all Run all todo
orch run --watch Continuous mode
orch run --watch --verbose With agent output
orch tui Interactive dashboard
orch status One-shot overview
TUI Dashboard (orch tui)
Tabs
G Goals — objectives + progress bars
T Tasks — status, priority, assignee
A Agents — stats, team membership
L Actions — live activity feed
Navigation
↑↓ j k Navigate list
Tab ←→ Switch tabs
Enter Open detail panel
Esc Close detail
/ Command bar
? Help overlay
+ / - Resize detail panel
M Fullscreen detail
Task actions
N New (wizard)
R Run selected
E Edit
A Approve (review)
X Reject (review)
C Cancel
D Delete (undo: Z)
S Show all / collapse
G Group by goal
Agent actions
S Force-stop
U Toggle autonomous
Command bar
/run Run task
/run-all Run all todo
/watch Start watch mode
/pause Pause watch
/status Orchestrator status
/agent shop Browse templates
/config TUI settings
/help All commands
/quit Exit TUI
F Activity filter: all → text → tools → errors
Logs
orch logs <run-id>
orch logs --agent <id>
orch logs --task <id>
orch logs --follow Live stream
orch logs --since 5m Time filter
Goals
orch goal add <title>
--description Goal description
--assignee <agent> Enables autonomous
orch goal list --status filter
orch goal show <id>
orch goal status <id> <status>
orch goal update <id> --title/--desc/--assignee
orch goal delete <id>
Teams
orch team create <name>
--lead <agent> req
--members Comma-sep agent IDs
orch team list
orch team show <id>
orch team join <team> <agent>
orch team leave <team> <agent>
orch team add-task <team> <task>
orch team set-lead <team> <agent>
orch team disband <id>
Messaging
orch msg send <to> <body>
-s Subject
--from Sender (default: cli)
--reply-to Reply to msg ID
orch msg broadcast <body>
--team Scope to team
orch msg inbox <agent>
orch msg list --agent filter
Shared Context
orch context set <key> <value>
--ttl TTL in ms
orch context get <key>
orch context list
orch context delete <key>
Configuration
orch config get <key> Dot notation
orch config set <key> <val>
orch config edit Open in $EDITOR
orch config global get/set/show
Setup & Diagnostics
orch init Initialize .orchestry/
--name <name> Project name
orch doctor Check adapters & deps
orch update Check for CLI updates
Pre-Built Organizations
orch org list Browse templates
orch org deploy <tmpl> --goal
startup-mvp CTO + 2 BE + FE + QA + Review
pr-review-corp Security + Perf + Style + QA
migration-squad CTO + 3 Migrators + QA
security-dept Lead + Scanner + Secrets + Hunter
test-factory Lead + 2 BE + 3 QA + Review
bugfix-dept Triager + 3 Fixers + QA
docs-team Lead + 2 Writers + Editor
content-agency Strategist + Writers + SEO
data-lab Lead Analyst + Data Engineer
sales-machine Director + 2 SDR + Copywriter
Task State Machine
todo →
in_progress →
review →
done
in_progress →
retrying →
in_progress
in_progress →
failed (max attempts)
review →
todo (rejected)
any →
cancelled
failed →
todo | retrying (manual)
Review Criteria
typecheck →
lint →
test_pass
fail-fast new
typecheck npx tsc --noEmit
lint npm run lint
test_pass npm test
Agent Statuses
idle Available for tasks
running Currently executing
error Last run failed
disabled Not available
Goal Statuses
active In progress
paused Temporarily stopped
achieved Terminal ✓
abandoned Terminal ✗
Adapters
claude Anthropic Claude CLI
opencode Multi-provider (OpenCode)
codex OpenAI Codex CLI
cursor Cursor IDE
shell Any shell command
Workspace Modes
worktree Git worktree per task (default)
shared Same directory, scope-guarded
isolated Full clone / rsync
Serve Mode (CI/CD)
orch serve Headless daemon
--once Run todo → exit
--log-format json | text
--log-file <path> Append to file
--tick-interval Poll ms
--verbose Include agent:output
Global Flags
--json JSON output
--quiet IDs only
--no-color Disable colors
--ascii No Unicode
.orchestry/ File Structure
.orchestry/
├── config.yml
├── state.json
├── tasks/
├── agents/
├── goals/
├── teams/
├── runs/
├── context/
├── messages/
└── workspaces/
Using from Claude Code
Type /orch in Claude Code to manage agents with natural language
/orch deploy a startup team for my project
/orch add a task to fix the login bug
/orch check what's running
/orch show me agent stats
Claude translates your intent into orch CLI commands automatically.
Agent Shop Templates (15)
backend-dev APIs, services, DB layers
frontend-dev React, components, CSS
fullstack-dev End-to-end development
qa-engineer Tests, coverage analysis
code-reviewer PR review, bugs, security
architect System design, blueprints
devops-engineer CI/CD, infrastructure
bug-hunter Find, reproduce, fix bugs
security-auditor Vulnerability scanning
performance-engineer Optimization, profiling
tech-writer Docs, READMEs, API docs
data-engineer Pipelines, ETL, analysis
marketer Strategy, copy, campaigns
content-creator Blog posts, social media
growth-hacker Growth experiments, A/B
Library Skills (26) — All Adapters
review Auto-fix, checklists, adversarial review
qa Testing + browser QA + health scoring
qa-only Report-only QA (no auto-fixes)
ship Merge, test, coverage audit, PR create
investigate 3-strike hypothesis root cause debug
careful Safety guardrails for destructive ops
guard Full safety mode (careful + freeze)
freeze / unfreeze Restrict edits to directory
autoplan Auto-review pipeline + decision rules
plan-*-review CEO / eng / design plan review
design-consultation Design system, visual language
design-review A11y, responsive, UX checks
land-and-deploy Merge PR, wait CI, verify prod
canary Post-deploy canary monitoring
document-release Auto-update docs after ship
office-hours YC-style product thinking
retro Weekly eng retrospective + trends
browse Headless browser navigation
benchmark Before/after perf metrics
codex Multi-AI cross-review challenge
setup-deploy Configure deployment settings
setup-browser-cookies Import cookies for auth QA
upgrade Upgrade skills to latest
MCP Skills — Claude Adapter Only
feature-dev:feature-dev Guided feature dev
feature-dev:code-explorer Deep codebase tracing
feature-dev:code-architect Architecture blueprints
feature-dev:code-reviewer Confidence-filtered review
testing-suite:generate-tests Tests + edge cases
testing-suite:test-coverage Coverage gap analysis
testing-suite:e2e-setup E2E framework config
testing-suite:test-quality-analyzer Quality metrics
devops-automation:cloud-architect Cloud infra, Terraform
frontend-design:frontend-design UI/UX implementation
product-manager-toolkit RICE, PRD, discovery
marketing-psychology Behavioral science
Model Recommendations
claude-opus-4-6 Strategy, review, architecture
claude-sonnet-4-6 Execution, coding, QA, writing
Config Defaults
max_concurrent_agents 6
poll_interval_ms 10,000
max_turns 50
timeout_ms 3,600,000 (1h)
stall_timeout_ms 600,000 (10m)
retry_base_delay_ms 10,000
retry_max_delay_ms 300,000 (5m)
max_attempts 3
Internals
Tick loop: Reconcile → Dispatch → Collect
Scoring: skill +50, role +30, idle +20, SR +10
Prompt: system (identity+skills) + user (task+context+inbox+goal)
IDs: tsk_ agt_ run_ goal_ team_ msg_
Aliases: orch = orchestry = ao