orchcore 0.2.0

Reusable orchestration core for AI coding agent CLI pipelines

orchcore

Reusable orchestration core for AI coding agent CLI pipelines.

What is orchcore?

orchcore is an async-first Python 3.12+ library that provides unified infrastructure for launching, monitoring, and managing multiple AI coding agent CLIs (Claude, Codex, Gemini, Copilot, OpenCode) as subprocesses through phase-based pipelines. It was extracted from four production orchestration systems — Planora, Articles, Finvault, and Raven — eliminating 60-70% of duplicated infrastructure 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
• DAG-based phase pipelines — sequential/parallel execution with dependency ordering and resume
• Rate-limit recovery — automatic detection, timezone-aware reset parsing, exponential backoff
• Layered configuration — TOML files, env vars, CLI overrides, named profiles
• Protocol-based UI — UICallback decouples engine from display (Rich, Textual, headless)
• Registry-as-data — new agent support via TOML config alone, zero code changes
• Graceful shutdown — SIGINT/SIGTERM with subprocess cleanup and state preservation

Installation

uv pip install orchcore

From source:

git clone https://github.com/AbdelazizMoustafa10m/orchcore.git
cd orchcore
uv pip install -e ".[dev]"

Requirements: Python 3.12+

Quick Start

1. Define Agents

# agents.toml
[agents.claude]
binary = "claude"
model = "claude-sonnet-4-20250514"
subcommand = "-p"
stream_format = "claude"

[agents.claude.flags]
plan = ["--think", "--verbose"]

[agents.claude.output_extraction]
strategy = "jq_filter"
jq_expression = ".content[0].text"

2. Run a Pipeline

import asyncio
from pathlib import Path
from orchcore.pipeline import PipelineRunner, PhaseRunner, Phase
from orchcore.registry import AgentRegistry, AgentMode, ToolSet
from orchcore.runner import AgentRunner
from orchcore.ui import NullCallback

async def main() -> None:
    registry = AgentRegistry()
    registry.load_from_toml(Path("agents.toml"))

    phase = Phase(
        name="planning",
        agents=["claude"],
        tools=ToolSet(internal=["Read", "Glob", "Grep"], permission="read-only"),
    )

    runner = AgentRunner()
    phase_runner = PhaseRunner(runner, registry, max_concurrency=4)
    pipeline = PipelineRunner(phase_runner)

    result = await pipeline.run_pipeline(
        phases=[phase],
        prompts={"planning": "Analyze the codebase and create a plan."},
        ui_callback=NullCallback(),
        mode=AgentMode.PLAN,
    )
    print(f"Success: {result.success} | Cost: ${result.total_cost_usd}")

asyncio.run(main())

Modules

Module	Purpose
stream/	4-stage pipeline (Filter → Parse → Monitor → Stall Detect) for 5 agent formats
pipeline/	DAG-based phase orchestration — sequential/parallel multi-agent execution
runner/	Async subprocess management with stdin/stdout/stderr piping
registry/	Agent configurations as data (TOML/dict) with runtime lookup
config/	Layered configuration: TOML → env vars → CLI overrides → 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 for pluggable display layers
signals/	Graceful SIGINT/SIGTERM shutdown
display/	Colored stderr logging (no Rich dependency in core)
observability/	Optional OpenTelemetry integration

Documentation

Full documentation is available at abdelazizmoustafa10m.github.io/orchcore.

Document	Description
Installation	Prerequisites, install options, extras
Quick Start	Define agents, build phases, run pipelines
Configuration Reference	Full settings table, profiles, env vars
Stream Events Reference	StreamEvent fields, types, agent states
UICallback Reference	Protocol methods and built-in implementations
Architecture	Package layout, core abstractions, design decisions
Stream Pipeline	4-stage composable pipeline deep-dive
Design Document	Problem statement, requirements, proposed design
Writing a UICallback	Build custom display layers
Agent Registry	TOML config, adding new agents, ToolSets
Recovery & Retry	Rate limits, backoff, failure modes
Contributing	Dev setup, code standards, testing

Contributing

See CONTRIBUTING.md for development setup, testing instructions, and code standards.

Please also review CODE_OF_CONDUCT.md and SECURITY.md.

License

orchcore is released under the MIT License.