why orchestratr

coding agents such as Claude Code, Codex CLI, Pi, and OpenCode are single-player tools: one terminal, one session, one human watching. real work wants many of them at once, often across different providers, since each has different strengths and each subscription has its own quota, for example a reviewer fanned out per concern, a worker iterating under a verifier, or a nightly job that triages issues.

the single-player problem

running agents as headless API calls solves scale but loses three things that matter, and leaves a fourth gap.

headless loses plan pricing

interactive TUI sessions bill against flat subscription plans. API-mode invocations bill per token, so a fleet of agents multiplies the per-token cost while a flat plan does not.

headless loses steerability and visibility

a headless agent can't be watched mid-flight, nudged with a correction, or taken over when it goes sideways. a real TUI can.

headless loses uniformity

every provider has a different headless mode, different flags, different transcripts. a script that fans out across providers needs one interface.

nobody owns the tree

even where spawning works, there is no unified view of which agents are running, who spawned whom, what state each is in, or a single place to kill, steer, or watch any of them.

how orcr answers

orcr runs every agent as a real interactive TUI in a herdr-managed terminal pane, and exposes the smallest surface that spawns, messages, awaits, reads, and stops them, from a shell, from any programming language, or from inside another agent.

how lineage is recorded

an environment contract records lineage without any provider cooperation. every pane orcr launches carries the agent's ids (ORCR_ID/ORCR_PATH) and its parent's (ORCR_PARENT_ID/ORCR_PARENT_PATH). when an agent inside such a pane calls orcr agent run, the server reads the caller's identity, records the parent-child edge, and resolves the child's path relative to the caller's scope. orcr top then renders the resulting tree. see agents and lineage for the full contract.

what herdr provides, and what orcr adds

herdr solves the layer below: persistent named sessions, background TUIs, programmatic input and output to real interactive agent terminals, agent lifecycle detection, and remote attach over SSH. orcr's server speaks herdr's own socket API directly to launch panes, send input, read lifecycle state, and locate each provider's native transcript.

two facts shape the split:

• herdr exposes no token or cost fields and no structured last message. both come from orcr's per-provider transcript adapters.
• herdr's state detection depends on herdr's own per-provider integrations being installed (herdr integration install claude and so on). without the integration, an agent's status is unknown. this is why orcr requires the herdr integration for every supported provider.

herdr is discovered, never embedded. orcr looks for the binary in this order: config herdr.bin, then $ORCR_HERDR_BIN, then $PATH. if it is missing, orcr prints an install pointer and exits 2.

comparison

compared to raw herdr

herdr gives you the panes and the socket API to drive them. on its own it has no notion of an agent's identity across panes, no path tree, no admission queue, no GC policy, no cross-provider contract, and no scheduler. orcr adds identity (uuid plus path), lifecycle, placement, scheduling, and the uniform contract on top of herdr, all inside one owned session so your own herdr workspace is never polluted.

compared to headless API scripts

a headless script bills per token, can't be steered or watched mid-flight, and reimplements each provider's headless quirks. orcr keeps plan pricing, makes every agent attachable and steerable, and gives one interface across providers.

orcr depends on herdr and on each provider's herdr integration. a provider is supported only when both layers are present, orcr's integration and herdr's integration for that provider. anything else fails fast at agent run with the exact install commands, and unmanaged discovery skips it. there are no degraded half-modes.

goals

• agents as real TUIs: plan-pricing-safe, attachable, steerable, visible.
• one interface across agent providers, via per-provider integrations (claude and codex first; the surface is designed for more).
• extreme-minimal primitives that compose from any language. the server's socket API is the API; the CLI and the SDK are thin clients of it.
• agents can orchestrate agents: any orcr-spawned agent can call orcr itself, and lineage and placement assemble automatically.
• safe at scale: a single queue with global and per-provider concurrency caps for RAM protection, automatic lifecycle GC, and one owned herdr session so your own workspace is never polluted.
• organized at scale: every agent lives at a path (slash-separated, filesystem style, last segment is its name) alongside a permanent uuid, so a large workflow stays legible, operable by glob (wait/kill), and visualizable in herdr's native UI and in orcr top.
• durable scheduling: run any command on a cadence, surviving the caller's shell.

non-goals

non-goals for this version, along with the work that is explicitly deferred (Windows support, permission profiles, a Python SDK, remote orchestration, and more providers), are collected on the roadmap and limitations page.

next

• installation sets up orcr, herdr, and the provider integrations.
• architecture covers the single-writer server, the socket API, and the herdr driver.
• providers and integrations explains the two-layer requirement in depth.