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 execution with dependency checks, and managing configuration, recovery, and graceful shutdown — so consuming projects only implement domain-specific logic.

Features

  • Multi-agent subprocess orchestration — async launch, stream capture, concurrency control
  • Unified stream processing — 4-stage pipeline normalizes 5 JSONL formats into a single StreamEvent model
  • Phase pipelines — sequential/parallel execution with dependency checks and resume
  • 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 with subprocess cleanup and state preservation
  • Safe subprocess boundaries — filtered agent environments by default, explicit cwd support, and opt-in git recovery
  • Optional observability — OpenTelemetry integration via OrchcoreTelemetry

Modules at a Glance

Module Purpose
stream/ 4-stage pipeline (Filter → Parse → Monitor → Stall Detect) for 5 agent formats
pipeline/ Phase orchestration — sequential/parallel multi-agent execution in topological dependency order
runner/ Async subprocess management with stdout/stderr streaming and optional stdin prompt transport (prompt_via = "stdin")
registry/ Agent configurations as data (TOML/dict) with runtime lookup
config/ Layered configuration: TOML files, env vars, CLI overrides, and profiles
recovery/ Rate-limit detection, exponential backoff, git dirty-tree recovery
workspace/ Artifact lifecycle management
prompt/ Jinja2 template rendering with frontmatter stripping
ui/ UICallback protocol — consuming projects implement their own display layer
signals/ Graceful SIGINT/SIGTERM shutdown
display/ Colored stderr logging (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
010 Topological phase ordering and explicit success semantics