Open-source orchestration for zero-human companies, processes and departments.
Run multiple AI agents on one project — without babysitting any of them.
Coordinate Claude, Codex, Cursor and any CLI tool in parallel. One npm install. Zero infrastructure.
Problem • Install • Claude Code • How It Works • Features • Serve • Templates • CLI • Architecture • FAQ
npm install -g @oxgeneral/orch # Install
cd ~/your-project && orch # Launch TUI
demo.mp4
Set a goal at 10pm. Five agents decompose, implement, test, and review. You wake up to pull requests.
You bought Claude, Codex, maybe Cursor. Each one is powerful alone. But your actual job isn't "use AI tools" — it's ship a product at the speed of a full team, while being one person.
Here's what that looks like today:
- You open 3 terminals. Copy-paste context between them. Forget which agent is doing what.
- One agent edits a file another is working on. Merge conflict. You fix it manually.
- An agent crashes at 2am. You don't notice until morning. Half a night wasted.
- You spend 40-60% of your time routing agents instead of building your product.
You're not the founder. You're the bottleneck.
$ orch org deploy startup-mvp --goal "Implement user auth with OAuth2"
✓ Deployed team "platform" — 5 agents
CTO (claude) → Decomposing goal into tasks...
Backend A (claude) → Waiting for tasks
Backend B (codex) → Waiting for tasks
QA (codex) → Waiting for tasks
Reviewer (claude) → Waiting for reviews
✓ CTO created 6 tasks from goal
$ orch run --all --watch
22:03 ▶ Backend A → "Implement OAuth2 flow" [feature/oauth]
22:03 ▶ Backend B → "JWT token service" [feature/jwt]
22:03 ▶ QA → waiting for implementations...
22:15 ✓ Backend B DONE (12m · 4,200 tokens)
22:15 ▶ QA → "Test JWT service" [test/jwt]
22:22 ✓ Backend A DONE (19m · 8,100 tokens)
22:24 ↻ QA RETRY attempt 2/3
22:28 ✓ QA DONE (6m · 2,800 tokens)
22:29 ▶ Reviewer → "Review OAuth2 implementation"
22:33 ✓ Reviewer DONE → all tasks in review
→ You went to sleep at 22:05.
→ You wake up to 6 tasks in review. Approve. Merge. Ship.
One goal. Five agents. Six PRs. Zero tab-switching. $4.20 in tokens.
That's it. ORCH auto-initializes and opens the TUI dashboard. Add agents, set goals, and run — right from there.
After install, the /orch skill is automatically available in Claude Code. Just type /orch and describe what you need in natural language:
/orch deploy a team to refactor the auth module and add tests
Claude will translate your intent into the right orch commands — create agents, tasks, goals, and run the orchestration. No need to memorize CLI flags.
Or deploy a pre-built team:
orch org deploy startup-mvp --goal "Build invoicing SaaS with Stripe"
orch run --all --watch|
Minimum 1-2 agents
|
Recommended — full department 4-6 agents
|
No database. No cloud. No Docker. No GPU — LLMs run via API, not locally.
Every agent works in an isolated git worktree. Your
mainbranch is never touched until you explicitly approve and merge. Mandatory review step in the state machine — no code ships without your OK. Agents can't overwrite each other's work.
Why does each agent need ~300 MB?
ORCH itself is lightweight (~120 MB). The RAM goes to the agent CLI processes that ORCH spawns — each is a separate Node.js/Python runtime:
| Agent process | RAM per instance | Why |
|---|---|---|
| Claude Code CLI | 200-400 MB | Full Node.js runtime + context window |
| OpenCode | 200-400 MB | Node.js + provider SDK |
| Codex CLI | 150-300 MB | Python runtime + OpenAI SDK |
| Cursor CLI | 200-400 MB | Electron-based agent |
| Shell scripts | 10-50 MB | Depends on the tool |
Formula: 120 MB (ORCH) + N × ~300 MB per concurrent agent.
2 agents ≈ 0.7 GB, 4 agents ≈ 1.3 GB, 6 agents ≈ 2 GB.
|
Set a high-level goal. Your CTO agent decomposes it into concrete tasks, assigns priorities, and delegates to the right departments. You set strategy — AI executes. Backend A, Backend B, Frontend — each agent gets its own git worktree (isolated branch). They work in parallel without file conflicts. Failed? Auto-retry with exponential backoff. Stalled? Zombie detection kills and re-queues. |
QA agents pick up completed work, run tests, validate contracts. Reject with feedback → task goes back to engineering with your notes. The loop closes automatically. Agents talk to each other — direct messages, team broadcasts, shared context store. Backend finishes auth module → sends message to QA → QA starts testing. No copy-paste. No manual routing. |
Nothing touches main until reviewed. Every task flows through the state machine:
Every transition validated. No task gets lost. No code merges without approval.
ORCH orchestrates any process — not just code. The shell adapter runs any CLI tool, which means any workflow becomes an automated pipeline:
| Department | Agents | What they do |
|---|---|---|
| Engineering | Claude, Codex, Cursor | Write code, fix bugs, refactor |
| Editorial | Claude (writer), Claude (editor), Shell (grammarly) | Write articles, edit, check grammar, publish |
| Sales Ops | Shell (CRM scripts), Claude (copywriter), Shell (email sender) | Generate leads, write sequences, send outreach |
| Analytics | Shell (pandas, duckdb), Claude (analyst), Shell (matplotlib) | Clean data, compute KPIs, generate reports |
| Content Factory | Claude (strategist), Claude (writer x2), Claude (SEO) | Plan content calendar, write posts, optimize |
| Security | Shell (Semgrep, Trivy, Gitleaks), Claude (hunter) | Scan code, correlate findings, auto-fix |
| DevOps | Shell (terraform, kubectl), Claude (architect) | Plan infra changes, apply, verify |
Every department gets the same superpowers: state machine governance, retry, messaging, isolation, review gate.
The shell adapter is the key: if it runs in a terminal, it's an agent — npm test, python bot.py, Semgrep, curl, CRM scripts, data pipelines. Any CLI tool gets state tracking, retry, and coordination for free.
Deploy a full team with one command:
Engineering
| Template | Agents | What it does |
|---|---|---|
startup-mvp |
CTO, Backend x2, Frontend, QA, Reviewer | Ship an MVP in 48 hours |
pr-review-corp |
Security, Performance, Style, QA, CTO | Automated review for every PR |
migration-squad |
CTO, Migrator x3, QA, Reviewer | JS-to-TS migration over a weekend |
security-dept |
Lead Auditor, Scanner, Secrets Auditor, Hunter, Reviewer | Multi-layer security audit |
test-factory |
Coverage Lead, Backend x2, QA x2, Reviewer | Coverage from 40% to 80% overnight |
bugfix-dept |
Triager, Fixer x3, QA, Reviewer | 100 issues to 0 in a week |
Non-Engineering
| Template | Agents | What it does |
|---|---|---|
content-agency |
Strategist, Writer x2, Editor, SEO | Content factory: plan, write, edit, optimize |
data-lab |
Lead Analyst, Data Engineer | 3 CSVs → executive report by morning |
sales-machine |
Sales Director, SDR x2, Copywriter, Growth Analyst | Outbound pipeline: research, outreach, follow-up, close |
docs-team |
Docs Lead, Writer x2, Editor, Reviewer | Technical docs from codebase analysis |
orch org list # See all teams
orch org deploy startup-mvp # Deploy the default
orch org deploy startup-mvp --goal "Build X" # Deploy with a goal
orch org export my-team # Save your setup as template
Run ORCH on a server 24/7 — no terminal, no TUI. Structured JSON logs for Datadog, Grafana Loki, or jq.
# Daemon mode — runs forever, picks up new tasks automatically
orch serve
# CI/CD mode — process current tasks and exit
orch serve --once # exit 0 = all done, exit 1 = has failures| Flag | Description | Default |
|---|---|---|
--once |
Process all todo tasks and exit | watch mode |
--tick-interval <ms> |
Override polling interval | 10000 |
--log-file <path> |
Tee logs to a file (append) | stdout only |
--log-format json|text |
Output format | json |
--verbose |
Include agent:output events |
off |
Every event is a single JSON line — pipe to any log aggregator:
{"ts":"2026-03-17T03:00:10.000Z","level":"info","event":"agent:started","agentId":"agt_abc","taskId":"tsk_123","runId":"run_xyz"}
{"ts":"2026-03-17T03:12:45.000Z","level":"info","event":"task:status_changed","taskId":"tsk_123","from":"in_progress","to":"review"}
{"ts":"2026-03-17T03:12:46.000Z","level":"info","event":"orchestrator:tick","running":0,"queued":2,"heap_mb":142}pm2
pm2 start "orch serve" --name orch-daemon --cwd ~/my-project
pm2 logs orch-daemon # structured JSON logs
pm2 stop orch-daemon # SIGINT → graceful shutdownsystemd
[Unit]
Description=ORCH AI Agent Daemon
After=network.target
[Service]
Type=simple
WorkingDirectory=/home/user/my-project
ExecStart=/usr/local/bin/orch serve
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target- Watch mode (default): tick loop runs indefinitely. Add tasks from another terminal (
orch task add) — daemon picks them up on the next tick. - Once mode (
--once): processes all existing todo tasks, skips autonomous task seeding, exits when everything reaches a terminal status. - Lock protection: only one orchestrator per project (reuses
.orchestry/orchestry.lock). Secondorch serveexits with a clear error. - Graceful shutdown: SIGINT/SIGTERM → stops accepting new tasks → waits for running agents → saves state → releases lock.
- Heap monitoring: every tick logs
heap_mb— catch memory leaks before OOM. - Idle throttling: logs every 6th idle tick (~60s) to avoid flooding logs when nothing is happening.
Setup & Diagnostics
orch init # Initialize project
orch doctor # System diagnostics
orch update # Check for updatesDepartments & Agents
orch agent add <name> --adapter claude --role "CTO — decomposes goals"
orch agent list # Status of all agents
orch agent disable/enable <id> # Toggle availabilityOrganization Templates
orch org list # List available companies
orch org deploy <template> # Deploy a full department
orch org deploy <template> --goal "..." # Deploy with a goal
orch org export <name> # Export current setupTasks
orch task add "Title" -p 1 # Create task (priority 1-4)
orch task list # List all tasks
orch task assign <task> <agent> # Manual assignment
orch task cancel <task> # Cancel running taskTeams (Departments)
orch team create <name> --lead <agent-id>
orch team join <team-id> <agent-id>
orch team add-task <team-id> <task-id>
orch team disband <id>Goals (Strategy)
orch goal add "Title" --description "..."
orch goal list
orch goal status <id> achievedCommunication
orch msg send <agent-id> "message" # Direct message
orch msg broadcast "message" --team <team-id> # Team broadcast
orch context set <key> <value> # Shared contextExecution & Monitoring
orch run --all --watch # Launch all agents
orch run <task-id> # Run single task
orch serve # Headless daemon (JSON logs)
orch serve --once # CI/CD: process and exit
orch status # Quick overview
orch logs <run-id> # View run logs
orch tui # Command center (TUI)
orch config edit # Open in $EDITORAliases: orchestry orch ao
ORCH is an engine first, CLI second. The core has zero dependencies on CLI/TUI layers — you can import @oxgeneral/orch as a library and build your own interface.
Directory structure
src/
├── domain/ # Models, state machine, errors
├── application/ # Orchestrator engine, services, event bus
├── infrastructure/
│ ├── adapters/ # Claude, OpenCode, Codex, Cursor, Shell
│ ├── storage/ # File-based (YAML/JSON/JSONL)
│ ├── process/ # PID management, graceful kill
│ ├── template/ # LiquidJS prompt templates
│ └── workspace/ # Git worktree isolation
├── cli/ # Commander.js commands
└── tui/ # Ink + React command center
npm run dev # Run via tsx
npm run build # Build ESM + DTS
npm test # 1694 tests via Vitest
npm run typecheck # Strict TypeScript
If ORCH saves you time — Star it on GitHub — it helps other founders find the project.
- Open an issue if something breaks or could be better
- Submit a PR — see CONTRIBUTING.md
Using ORCH on a real project? Share your setup — we'd love to hear how it went.
Do I need a team to use ORCH?
No. Solo founders are the primary users. You + 2 agents is already a zero-human company. ORCH gives you auto-retry, state machine, dashboard, and token tracking even with a single agent. Start with one, scale to departments.
Will agents mess up my codebase?
No. Every agent works in an isolated git worktree on its own branch. Nothing touches main until you explicitly approve. Mandatory review step in the state machine. Scope overlap detection prevents conflicts before they happen.
Is this only for engineering?
No. The shell adapter runs any CLI tool — which means ORCH orchestrates any process. Engineering, editorial, sales, analytics, security, DevOps. If it runs in a terminal, it's an employee. Deploy content-agency, data-lab, or sales-machine with one command.
How much does it cost?
ORCH is open-source (MIT license). You pay only for the AI APIs you already use — Claude, Codex, etc. The TUI shows token costs per agent per run in real-time. Example: 5 agents, 6 tasks — $4.20 in tokens. No surprise bills.
What AI tools does it support?
Five adapters: Claude Code, OpenCode (Gemini, DeepSeek, any OpenRouter model), Codex, Cursor, and Shell (any CLI tool). Your API keys, your tools — ORCH coordinates them.
Can I run agents 24/7 on a server?
Yes. orch serve runs the orchestrator as a headless daemon — no TUI, structured JSON logs to stdout. Deploy with pm2, systemd, or any process manager. Add tasks from another terminal or machine — the daemon picks them up automatically. Graceful shutdown on SIGINT/SIGTERM.
Is there a cloud component?
None. Zero cloud. All state in .orchestry/ — plain YAML, JSON, JSONL files. No signup, no account, no data leaves your machine.
How is this different from Paperclip?
Paperclip needs PostgreSQL, a web server, and cloud setup. ORCH needs npm install. Same vision — zero-human companies — but ORCH is the hacker's version: terminal-first, file-based, zero infrastructure, MIT licensed.
MIT — build whatever you want.
This is how zero-human engineering teams start.