orchcore

Reusable orchestration core for AI coding agent CLI pipelines.

What is orchcore?

orchcore is an async-first Python library for launching, monitoring, and managing AI coding agent CLIs (Claude Code, Codex, Antigravity, Copilot, OpenCode) as subprocesses in phase-based pipelines. It was extracted from four production orchestration systems (Planora, Articles, Finvault, and Raven), where an estimated 60-70% of the orchestration code was the same infrastructure. Consuming projects keep only their domain-specific logic: pipeline definitions, prompts, output interpretation, and presentation.

Features

• Launches agent CLIs as async subprocesses, captures their output streams, and limits how many run at once.
• Normalizes five JSONL output formats into one StreamEvent model through a four-stage stream pipeline (filter, parse, monitor, stall detection).
• Runs phases in dependency order, with each phase's agents running sequentially or in parallel, and supports resume, skip, and single-phase options.
• Detects rate limits, parses reset times (including named time zones), and retries after a backoff wait.
• Layers settings from TOML files, .env and environment variables, constructor arguments, and named profiles.
• Separates the engine from presentation through the UICallback protocol, so the consuming project chooses Rich, Textual, or headless output.
• Defines agents as data: a new agent CLI that uses a supported stream format needs only a TOML entry.
• On SIGINT or SIGTERM, terminates agent process trees and force-kills them after a 30-second grace period. With a workspace attached, completed phases are saved for resume.
• Starts agent subprocesses with a filtered environment by default and in an explicit working directory when one is given (cwd). Git recovery runs only when a phase opts in.

Installation

orchcore requires Python 3.12 or later.

uv pip install orchcore

To install from source with the development dependencies:

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

Quick Start

1. Define Agents

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

# Flag profiles — names are your project's workflow vocabulary, not orchcore's.
[agents.claude.flags]
plan = ["--think", "--verbose"]

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

2. Run a Pipeline

"""Minimal orchcore pipeline setup.

Requires a matching ``agents.toml`` file and the configured agent CLI on
``PATH``. Use ``dry_run=True`` at the AgentRunner layer for artifact-level
smoke tests; a real pipeline run launches the configured CLI.
"""

from __future__ import annotations

import asyncio
from pathlib import Path

from orchcore.pipeline import Phase, PhaseRunner, PipelineRunner
from orchcore.registry import AgentRegistry, 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",),
        # Selects [agents.<name>.flags].plan — a name YOUR project defines.
        flag_profile="plan",
        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(),
    )

    print(f"Success: {result.success} | Cost: ${result.total_cost_usd}")


if __name__ == "__main__":
    asyncio.run(main())

By default, agent subprocesses receive a filtered environment, so common API keys and provider-specific variables are not inherited. To pass them through, set env_policy = "inherit", list the names in env_passlist, or set explicit env_vars in the agent config.

Modules

Documentation

The full documentation is published on the orchcore documentation site. The pages below are also readable on GitHub.

Contributing

See CONTRIBUTING.md for development setup, testing instructions, and code standards. Contributors follow the Code of Conduct, and security issues are reported as described in the security policy.

License

orchcore is released under the MIT License.