ORCH — Summary

ORCH (@oxgeneral/orch) is a TypeScript npm package that orchestrates teams of AI agents (Claude, Codex, OpenCode, Cursor) working on a single codebase in parallel, with a terminal TUI dashboard, a headless serve mode for CI/CD, and a Claude Code skill (/orch) for natural-language orchestration commands. The architecture is layered DDD (domain/application/infrastructure/CLI) with dependency injection, a state-machine task lifecycle (todo → in_progress → review → done), and an orchestrator tick-loop that reconciles PIDs, dispatches idle agents, and collects completed runs. All state lives in flat files under .orchestry/ — individual YAML files for tasks/agents/goals/teams, JSON for runs, atomic writes for corruption safety. The framework supports multi-agent parallel execution with role-based adapter selection (claude, opencode, codex, cursor, shell), 26 Markdown skills injected at agent dispatch, and a --once headless mode for CI pipelines. ORCH is most similar to claude-flow in its orchestrator-agent hierarchy, but uses flat-file YAML storage instead of SQLite, a TUI instead of a web dashboard, and does not implement any consensus protocols. The /orch Claude Code skill makes ORCH self-bootstrapping — the user types natural language and Claude translates it into orch CLI commands.

ORCH — Overview

Origin

Published as @oxgeneral/orch on npm (68 stars, MIT license, TypeScript, last commit 2026-05-19). The project positions itself against the "you're managing agents full-time" problem — founders/solo developers with Claude/Codex who spend 40-60% of their time routing agents rather than building.

Philosophy

"Open-source orchestration for zero-human companies, processes and departments." "Run multiple AI agents on one project — without babysitting any of them." "Set a goal at 10pm. Five agents decompose, implement, test, and review. You wake up to pull requests."

From CLAUDE.md:

"ORCH is an AI agent runtime — not just a CLI tool. The core engine (domain + application + infrastructure) has zero dependencies on CLI/TUI layers."

Key design choices:

1. Zero infrastructure: No database server, no cloud, no Docker — just flat files in .orchestry/
2. Multi-adapter: The same IAgentAdapter interface works for claude, codex, opencode, cursor, shell
3. State machine formalism: Task transitions are validated by canTransition() — no ad-hoc status strings
4. Skill injection: 26 Markdown skills loaded from skills/library/ are injected into agent prompts at dispatch time
5. Natural language entry: The /orch Claude Code skill means users never need to memorize CLI flags

Target User

Solo founders, small engineering teams who want to run background agent work overnight without manual supervision.

ORCH — Architecture

Distribution

• Type: npm-package
• Binaries: orchestry, orch, ao (all point to ./dist/cli.js)
• Version: latest on npm as @oxgeneral/orch
• Language: TypeScript (ESM + DTS bundles via tsup)

Install Methods

npm install -g @oxgeneral/orch
cd ~/your-project && orch    # Launch TUI
# Or headless:
orch serve --once --log-format json

Required Runtime

• Node.js (version unspecified; uses ESM)

Directory Structure (layered DDD)

src/
├── domain/              # Models, state machine, errors
│   └── transitions.ts   # canTransition() — todo→in_progress→review→done
├── application/         # Services, orchestrator, event bus
│   └── orchestrator.ts  # Tick loop: reconcile→dispatch→collect
├── infrastructure/      # Adapters, storage, process manager, templates
│   ├── adapters/        # IAgentAdapter implementations: claude, opencode, codex, cursor, shell
│   ├── storage/         # YAML/JSON file stores, atomicWrite(), readJsonlTail()
│   ├── skills/          # SkillLoader — 26 Markdown skills
│   └── workspaces/      # Workspace isolation (worktree/shared/isolated modes)
├── tui/                 # Ink/React TUI dashboard
│   └── App.tsx          # Batched message queue (80ms flush), OOM protection
├── bin/
│   └── cli.ts           # Entry point → LightContainer or Container (DI)
├── cli/
│   └── commands/        # 16 CLI command modules
│       ├── agent.ts, config.ts, context.ts, doctor.ts, goal.ts, init.ts
│       ├── logs.ts, msg.ts, org.ts, run.ts, serve.ts, status.ts
│       ├── task.ts, team.ts, tui.ts, update.ts
└── container.ts         # DI: LightContainer (read-only) vs Container (full)

.orchestry/ State Directory

All state in flat files — no database server:

.orchestry/
├── tasks/          # Individual YAML files per task
├── agents/         # Individual YAML files per agent
├── goals/          # Individual YAML files per goal
├── teams/          # Individual YAML files per team
├── runs/           # JSON metadata + append-only JSONL events per run
├── context/        # Context JSON files
├── messages/       # Message JSON files
└── state.json      # Single orchestrator state file

Target AI Tools

Claude Code (claude adapter), Codex (codex adapter), OpenCode (opencode adapter), Cursor (cursor adapter), any shell command (shell adapter).

ORCH — Components

CLI Commands (16)

Skill Library (26 Markdown skills in skills/library/)

Claude Code Skill (skills/orch/SKILL.md)

A skill file auto-discovered by Claude Code:

• Natural language → CLI commands translation
• Full CLI reference embedded in skill
• --json flag guidance for programmatic output
• Handles: init, task management, agent management, goal management, team management, running agents

Agent Adapters (src/infrastructure/adapters/)

All implement IAgentAdapter.execute(params) → { pid, events: AsyncGenerator<AgentEvent> }:

Workspace Modes

Task-level workspace isolation:

• shared — all agents share the working directory
• worktree — each agent gets its own git worktree
• isolated — fully isolated workspace

Pre-Built Organization Templates

orch org deploy <template> deploys named teams:

• startup-mvp — CTO + Backend A/B + QA + Reviewer (5 agents)
• Other templates available via orch agent shop

ORCH — Uniqueness

differs_from_seeds

ORCH is most similar to claude-flow — both implement a hierarchical orchestrator-worker pattern with parallel multi-agent execution and a CLI + dashboard surface. Key differences: ORCH uses flat YAML files in .orchestry/ instead of SQLite; it ships a terminal TUI (Ink/React) instead of a web dashboard; it does not implement hive-mind consensus protocols; and it is multi-adapter (claude/codex/opencode/cursor/shell) rather than claude-only. The /orch Claude Code skill that lets users type natural language is an inversion of claude-flow's pattern — ORCH is controlled through Claude rather than separately from it. Compared to taskmaster-ai (single-agent task decomposition via JSON), ORCH operates multiple simultaneous agents in parallel and has a state machine with explicit review gates. The 26 injected Markdown skills resemble superpowers' skill-pack pattern but are injected at agent dispatch time rather than via CLAUDE.md.

Distinctive Positioning

1. Three binary aliases: orch, orchestry, ao — unusual commitment to CLI ergonomics
2. Layered DDD architecture: Explicit domain/application/infrastructure/CLI separation with two DI container tiers (LightContainer for reads, Container for full orchestration) — the most formally architected project in this batch
3. Scope Drift Detection in /review skill: The pre-landing review skill explicitly checks for both over-delivery (scope creep) and under-delivery (missing requirements) before code quality — a novel quality-gate pattern
4. orch serve --once for CI: First-class CI integration with JSON structured logging and exit codes
5. 1954 passing tests: The README badge claim suggests unusually high test coverage for a framework in this category
6. Pre-built org templates: orch org deploy startup-mvp deploys a 5-agent team in one command

Observable Failure Modes

• YAML file contention: Atomic writes prevent corruption, but many concurrent agents could create write pressure on the state directory
• No distributed execution: All agents run on the same machine; no remote agent dispatch
• Skill injection is all-or-nothing: Skills are injected based on agent config, not task context — a code-writing agent always gets the same skills regardless of the specific task
• Review gate is manual by default: Unless --review-criteria is set, tasks stay in review until a human approves — no automated review completion
• TUI OOM risk: Despite safeguards, very high-frequency agent event streams can still cause performance degradation