Skip to content

orchcore

Reusable orchestration core for AI coding agent CLI pipelines.

orchcore extracts the 60-70% of duplicated infrastructure from production AI orchestration systems into a single, typed, async-first Python 3.12+ library. It handles launching agent CLIs as subprocesses, processing their JSONL output through a unified stream pipeline, orchestrating multi-phase DAG-based execution, and managing configuration, recovery, and graceful shutdown — so consuming projects only implement domain-specific logic.

Features

  • Multi-agent subprocess orchestration — launch and manage Claude, Codex, Gemini, Copilot, and OpenCode CLIs as async subprocesses
  • Unified stream processing — 4-stage pipeline (Filter, Parse, Monitor, Stall Detect) normalizes 5 different JSONL formats into a single StreamEvent model
  • DAG-based phase pipelines — sequential and parallel phase execution with dependency ordering, partial failure semantics, and resume support
  • Rate-limit recovery — automatic detection with timezone-aware reset parsing and exponential backoff
  • Layered configuration — TOML files, environment variables, CLI overrides, and named profiles via pydantic-settings
  • Protocol-based UI — UICallback protocol decouples engine from presentation; plug in Rich, Textual, or headless output
  • Registry-as-data — add new agent support via TOML configuration alone, zero code changes
  • Graceful shutdown — SIGINT/SIGTERM handling with cooperative cancellation flag; PhaseRunner owns subprocess termination with 30s grace period
  • Git dirty-tree recovery — auto-stash or auto-commit before retry to ensure clean working state
  • Optional observability — OpenTelemetry integration via OrchcoreTelemetry

Modules at a Glance

Module Purpose
stream/ 4-stage pipeline normalizing JSONL from 5 agent formats into unified StreamEvent models
pipeline/ DAG-based phase orchestration engine for sequential/parallel multi-agent execution
runner/ Async subprocess management — launches agent CLIs with stdin/stdout/stderr piping
registry/ Agent configurations as data (TOML/dict) with runtime lookup and tool resolution
config/ Layered configuration: TOML → env vars (ORCHCORE_*) → CLI overrides → profiles
recovery/ Rate-limit detection, retry with exponential backoff, git dirty-tree recovery
workspace/ Manages .orchcore-workspace/outputs/<phase>/<agent>.md artifact lifecycle
prompt/ Jinja2 template rendering with frontmatter stripping
ui/ UICallback protocol — consuming projects implement their own display layer
signals/ Cooperative SIGINT/SIGTERM shutdown flag (shutdown_requested) with check_shutdown()
display/ Colored stderr logging via ANSI codes (no Rich dependency in core)
observability/ Optional OpenTelemetry integration

Guides

Guide Description
Writing a UICallback Implement custom display layers for your project
Agent Registry Configure agents via TOML, add new agent support
Recovery & Retry Rate limits, backoff, git recovery, failure modes
Workspace Management Artifact lifecycle, archival, and cleanup
Prompt Templating Jinja2 templates, frontmatter stripping, template loading
Signal Handling Cooperative SIGINT/SIGTERM shutdown flag and graceful exit
Observability Optional OpenTelemetry tracing integration
Display Utilities ANSI colored logging and formatting helpers

Architecture Decision Records

ADR Decision
001 Extract reusable orchestration core from 4 production systems
002 Async-first with stdlib asyncio
003 Protocol-based UI decoupling
004 Composable 4-stage stream processing pipeline
005 Multi-source layered configuration
006 Pydantic for all data models
007 Registry pattern for agent management
008 Partial failure semantics with retry
009 Tool assignment as phase-level concern