ORCH — AI Agent Orchestrator
One CLI to orchestrate them all: run teams of AI agents in parallel on your codebase from isolated git worktrees, hands-free.
SKILL.md claims git-worktree isolation and a mandatory review gate with local state storage and fairly clear data-flow disclosure; however, the default approval-policy is auto, and repository tests show Grok/Antigravity adapters spawn agents with bypassPermissions/--dangerously-skip-permissions; autonomous mode and org deploy auto-generate and execute tasks without mandatory user confirmation or documented rollback, so only a middle score is warranted.
Docs are internally consistent with a complete CLI reference and troubleshooting guidance (orch doctor, stall timeout, lock protection); the repo has CI workflows and extensive test files. Static review cannot execute anything, the 1954 tests cover the engine rather than the skill's documented CLI key paths, and failure-feedback quality is unverified — capped at 9.
Trigger phrases in frontmatter are clear, the Goals-vs-Tasks boundaries are well defined, and adapter scope is declared; but there is no Chinese-language support, and core function depends on overseas CLIs/APIs (Claude, Codex, Cursor) with real mainland-China reachability risk — deducted here.
Good layered structure, MIT license, versioned npm publish flow with changelog extraction, and SECURITY.md; but the skill document itself lacks version/changelog, has no FAQ, includes a hard-coded agent ID example, and maintenance responsibility is only vaguely community-based.
The CLI reference and workflows are detailed and actionable with clear value claims; but static review cannot verify actual outputs, README contains unverified marketing-style examples ($4.20 tokens, 48h MVP), and comparative-benefit evidence is thin — capped at 6.
Auditable test code (battle test, PTY e2e, adapter e2e) and CI configs partially corroborate claims; but the skill path's key CLI commands are not directly covered by these tests and no executed reproduction exists — capped at 4.
- Default auto approval policy and adapter permission-bypass flags mean agents may execute commands without user confirmation; prefer --approval-policy suggest/manual and review org deploy consequences
- Core function depends on overseas LLM CLIs/APIs which may be unreachable from mainland China; no Chinese-language support provided
- The skill's CLI reference is unverified by execution; actual command behavior may differ from docs; publisher identity is unverified
What does this skill do, and when should you use it?
ORCH (npm package @oxgeneral/orch) is an open-source AI agent runtime that coordinates teams of LLM agents working in parallel on a codebase from your terminal. It combines a CLI and TUI dashboard with automatic goal decomposition, multi-adapter agent management (Claude, Codex, Cursor, OpenCode, Pi, Grok, Antigravity, and any shell command), and a mandatory review state machine that protects your main branch. All state lives in plain YAML/JSON files under .orchestry/ in your project — no database, no cloud. It ships 15 pre-built agent templates and 10 ready-made team templates deployable in one command, aimed at solo founders who want full-team throughput.
Initializes a .orchestry/ project state directory; creates and manages agents with a chosen adapter, model, reasoning effort, approval policy, and workspace mode; adds tasks with priority, file-scope globs, dependencies, and auto-review criteria; hands high-level goals to a lead agent that autonomously decomposes them into tasks; isolates each agent's writes in git worktrees and flows work through todo → in_progress → review → done; supports inter-agent messaging, broadcasts, and a shared context store; provides a TUI dashboard, continuous orchestration via orch run --watch, and a headless daemon (orch serve) with structured JSON logs, pm2/systemd deployment, and a --once CI/CD mode; auto-retries failed tasks and detects stalled (zombie) processes.
- A solo founder sets a goal before bed (e.g. implement OAuth2); a CTO agent decomposes it, backend/QA/reviewer agents work in parallel, and pull requests await approval in the morning
- A team lead deploys an automated PR review department in one command (orch org deploy pr-review-corp) covering security, performance, and style checks
- An engineering team running a large JS-to-TS migration or lifting test coverage from 40% to 80% uses the migration-squad or test-factory templates with iterative, metric-driven goals
- Non-engineering workflows: orchestrate writing, data analysis, or sales outreach with content-agency, data-lab, or sales-machine templates, wiring in any CLI tool via the shell adapter
- An operator runs agents 24/7 on a server with orch serve under pm2/systemd, piping JSON logs into a monitoring stack
- A CI/CD pipeline processes pending tasks with orch serve --once and reads pass/fail from the exit code
What are this skill's strengths and limitations?
- Every agent works in an isolated git worktree — main is never touched until you explicitly approve, and a mandatory review gate blocks unreviewed merges
- Zero infrastructure: no database, no cloud, no Docker; all state is plain YAML/JSON files in .orchestry/
- Eight adapters (Claude, OpenCode, Codex, Pi, Cursor, Grok, Antigravity, Shell) — the shell adapter turns any CLI tool into a managed agent
- Ten pre-built org templates deploy a full department in one command, covering engineering, content, data, and sales workflows
- Auto-retry with exponential backoff, stall detection, and auto-cleanup of stale state after crashes; orch serve offers headless JSON logging and a --once CI/CD mode
- MIT-licensed, 1954 tests passing, and a layered engine/CLI/TUI architecture you can import as a library
- ~300 MB RAM per concurrent agent (≈2 GB for six agents), which limits scaling on modest hardware
- Costs depend entirely on the AI APIs you call; the $4.20 example in the README is illustrative, not a guarantee
- Supported platforms are macOS, Linux, and WSL2 only — native Windows is not listed
- Agent quality and autonomous goal decomposition depend heavily on model choice and role prompts; the source offers no independent benchmarks
- The SKILL.md uses the Claude Code-specific allowed-tools frontmatter field, so porting to other Agent Skills clients requires edits
How do you install this skill?
Prerequisites: macOS, Linux, or WSL2 with Node.js >= 20. Install with npm install -g @oxgeneral/orch. Then run orch inside your project directory — it auto-initializes and opens the TUI. Footprint: ~120 MB for ORCH plus roughly 300 MB RAM per concurrent agent process. Run orch doctor to diagnose problems. Note: the repository does not document a separate installation path for the Skill file itself; per the README, the /orch skill becomes automatically available in Claude Code after install.
How do you use this skill?
Typical flow: 1) orch init --name "my-project"; 2) pick agents with orch agent shop, or deploy a whole team with orch org deploy startup-mvp --goal "..."; 3) add work with orch task add "Fix login crash" -d "..." --scope "src/auth/**" -p 1, or create a goal with orch goal add and let the lead agent decompose it; 4) start orchestration with orch run --all --watch or inspect via orch tui; 5) approve or reject tasks in review with orch task approve/reject; 6) always pass -- when parsing output programmatically. In Claude Code, type /orch deploy a team to refactor the auth module and add tests to drive everything in natural language.
How does this skill compare with similar options?
The README contrasts ORCH with Paperclip: Paperclip requires PostgreSQL, a web server, and cloud setup, while ORCH needs only npm install — the same zero-human-company vision, but terminal-first, file-based, zero-infrastructure, and MIT licensed.