ORCH — CLI orchestrator for AI agent teams (Claude Code, Codex, Cursor)

[oxgeneral]

Hey Haystack community! 👋

I built ORCH — an open-source CLI orchestrator that coordinates teams of AI coding agents from the terminal.

What it does

ORCH manages the coordination layer for CLI-based AI agents:

npm install -g @oxgeneral/orch

orch agent add "researcher" --adapter claude --model claude-opus-4-6
orch agent add "coder" --adapter codex

orch task add "Analyze codebase" -p 1 --assignee researcher
orch task add "Implement feature" -p 2 --assignee coder --scope "src/**"

orch tui  # live TUI dashboard

Key features

• State machine — todo → in_progress → review → done with auto-retry
• Scope locking — no file conflicts between concurrent agents
• Inter-agent messaging — agents pass results without human copy-paste
• Goal tracking — decompose high-level goals into agent tasks
• Zero infrastructure — plain YAML/JSON, no database

Connection to Haystack

Haystack excels at building NLP pipelines and RAG systems. ORCH is a CLI runtime complement for the coding workflow layer — coordinating Claude Code, Codex, and Cursor for software development tasks. Together they could power AI pipelines where Haystack handles retrieval + ORCH handles the agent execution coordination.

1,657 passing tests · TypeScript strict · MIT · https://github.com/oxgeneral/ORCH

Happy to discuss! 🚀

[oxgeneral]

Thanks for the thoughtful feedback, @rehan243!

On scope locking — glad it resonates. Monorepo conflicts with concurrent agents was exactly the pain point. ORCH uses glob-based scope patterns per task (--scope "src/auth/**") with a ScopeIndex that pre-computes base prefixes for O(1) overlap checks during dispatch. Conservative by design — may block a borderline case, but never lets two agents stomp the same files.

On Redis Streams / pub-sub — great question. Right now the event bus is in-process and synchronous (EventBus.emit() → handlers run inline). This is intentional for the CLI-first use case: zero infrastructure, single-process orchestrator. At the "5 agents on a monorepo" scale this works well — the bottleneck is the AI tools themselves (Claude/Codex response times), not the event bus.

That said, the architecture does not close the door. EventBus implements typed pub/sub with on(), onAny(), and once(). Swapping the transport to Redis Streams or NATS would mean implementing the same emit/on interface over a network layer — the orchestrator and adapters would not change. For now, it is a deliberate trade-off: zero-config > distributed scale. If real demand appears for 500+ concurrent ops, it is a clean extraction point.

On Haystack integration — orch serve --once already works as a headless daemon with structured JSON logs, designed for CI/CD pipelines. The programmatic API is also available:

import { buildFullContainer, TaskService } from '@oxgeneral/orch';

const container = await buildFullContainer({ projectRoot: '.' });
await container.taskService.create({
  title: 'Summarize retrieved docs',
  assignee: 'researcher',
  description: retrievedDocs.join('\n'),
});
await container.orchestrator.startWatch();

So the pattern you described (Haystack retriever → ORCH task) is already possible today — either via CLI (orch task add ...) or the TypeScript API.

On production metrics — honest answer: ORCH is built and tested for small-to-medium agent teams (2–8 agents). The orchestrator tick loop runs reconcile → dispatch → collect with a promise-chain mutex for state serialization. 1,829 tests cover the state machine, race conditions, retry logic, and OOM protection (batched TUI events, JSONL tail reads). Real-world throughput benchmarks with full agent teams are on the roadmap — would be happy to share numbers once we have them.

Appreciate the concrete integration example — that's exactly the kind of workflow we are optimizing for. 🤝

[reallyticsai]

This orchestration layer looks super useful for real-world AI agent deployment. Scope locking and inter-agent messaging are things we’ve built custom before—avoiding file conflicts and making agents pass outputs directly (no human in the loop) is crucial for reliable automation. We’ve had issues with agents stepping on each other’s toes in voice agent projects, so state machines and locking are must-haves.

Connecting Haystack’s retrieval to ORCH’s codegen pipeline feels like a natural integration. For example, in a RAG-driven code assistant, Haystack could pull docs and tickets, then ORCH could assign a researcher agent to summarize, coder to implement, and reviewer to verify—each step tracked with state and file locks. We’ve done similar flows with custom Python and FastAPI orchestration, but your CLI/TUI approach is way lighter weight.

Have you benchmarked agent throughput or latency under multi-agent concurrency? We’ve seen 300ms-600ms agent-to-agent handoff using Redis pub/sub and shared volume mounts, but curious how YAML/JSON and TUI scale. Also, how extensible is the adapter layer—could we plug in a Haystack pipeline as a "researcher" agent or does it expect LLM endpoints?

Here’s a typical snippet from our prod orchestration layer:

# Assign task and lock scope
assign_task(agent="coder", task="implement_feature", files=["src/**"])
lock_files(["src/**"])

# Agent completes task, unlock files
if task.status == "done":
    unlock_files(["src/**"])
    push_result_to_next_agent()

Would love to hear how you handle agent failures or retries—any backoff or error propagation in your state machine?