Orchestration Library (`jleechanorg-orchestration`)

Python package and CLI for AI CLI task execution (passthrough and async tmux modes).

Install from PyPI
Verify Install and Version
CLI Entry Points
Primary Usage: ai_orch
Task Dispatcher Python Interface
Legacy: orchestrate_unified (deprecated)
Design Summary
Tech Stack (Summary)
Local Development (Package Source)

Install from PyPI

python3 -m pip install jleechanorg-orchestration

Upgrade:

python3 -m pip install --upgrade jleechanorg-orchestration

Install a specific version:

python3 -m pip install "jleechanorg-orchestration==0.1.40"  # omit version for latest

Verify Install and Version

python3 -m pip show jleechanorg-orchestration
ai_orch --version

CLI Entry Points

Console scripts installed by the package:

ai_orch
orch (alias)

Both map to orchestration.runner:main.

Primary Usage: ai_orch

Passthrough (default)

Run the selected CLI directly and stream output to stdout:

ai_orch "explain this code"
ai_orch --agent-cli codex "print 1"
ai_orch --agent-cli gemini "fix the bug"

Async (detached tmux)

Spawn a detached tmux session and return immediately:

ai_orch --async "implement feature X"
ai_orch --async --resume "add error handling"   # resume existing session for this dir
ai_orch --async --worktree "refactor auth"      # create git worktree first, then async

Flags:

--agent-cli: CLI to use (claude, codex, gemini, minimax, cursor)
--model: model override for supported CLIs
--async: spawn detached tmux session
--resume: reuse existing session for this directory (requires --async)
--worktree: create git worktree before async (requires --async)

Task Dispatcher Python Interface

For programmatic multi-agent orchestration (used by automation/), use TaskDispatcher directly:

from orchestration.task_dispatcher import TaskDispatcher

dispatcher = TaskDispatcher()

agent_specs = dispatcher.analyze_task_and_create_agents(
    "Fix failing tests in PR #123 and push updates",
    forced_cli="claude",
)

for spec in agent_specs:
    ok = dispatcher.create_dynamic_agent(spec)
    print(spec["name"], ok)

Core methods

TaskDispatcher.analyze_task_and_create_agents(task_description: str, forced_cli: str | None = None) -> list[dict]
TaskDispatcher.create_dynamic_agent(agent_spec: dict) -> bool

Agent spec fields used by `create_dynamic_agent`

name: unique agent/session name
task: full task instructions
cli or cli_chain: selected CLI or fallback chain
workspace_config (optional): workspace placement/settings
model (optional): model override

Legacy: orchestrate_unified (deprecated)

orchestrate_unified.py is retained as a stub for import compatibility. Its orchestration logic has moved to runner.py. Use ai_orch for passthrough/async or TaskDispatcher for programmatic agent creation.

Design Summary

Full design details live in orchestration/design.md.

High-level design:

Entry point is ai_orch/orch (mapped to orchestration.runner:main).
Default flow is passthrough: invoke CLI directly, stream output.
Async flow (--async) spawns detached tmux sessions with resume and optional worktree support.
TaskDispatcher remains for programmatic multi-agent orchestration (automation, PR monitors).
Coordination uses file-backed A2A/task state under /tmp (no Redis dependency).

Tech Stack (Summary)

Runtime: Python 3.11+
Session/process isolation: tmux
VCS/PR operations: git, gh
Agent CLIs: claude, codex, gemini, minimax, cursor-agent
Coordination: file-backed A2A/task state under /tmp (no Redis requirement)

Detailed architecture and implementation docs:

orchestration/design.md
orchestration/A2A_DESIGN.md
orchestration/AGENT_SESSION_CONFIG.md

Local Development (Package Source)

cd orchestration
python3 -m pip install -e .
python3 -m pytest tests -q

Use editable installs only for local package development.

Metadata

Release files for jleechanorg-orchestration 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jleechanorg-orchestration 0.2.3
File	Size	Uploaded
jleechanorg_orchestration-0.2.3.tar.gz	204.1 kB	Mar 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for jleechanorg-orchestration 0.2.3
File	Interpreter	ABI	Platform	Reset
jleechanorg_orchestration-0.2.3-py3-none-any.whl 156.1 kB Mar 9, 2026	Python 3	none	any	Details

Total release size: 360.2 kB

Release files / jleechanorg_orchestration-0.2.3.tar.gz

Download URL	jleechanorg_orchestration-0.2.3.tar.gz
Size	204.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`b2725adcc6652aa66de1ba9b88a8dcdc106266726a7b8c0892987684519f9307`
BLAKE2b-256 checksum How to use checksums	`688039972d46a233fe6170c0149b814fd8914cf385fdb8d71573d21f599c08f1`
Upload date	Mar 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`

Release files / jleechanorg_orchestration-0.2.3-py3-none-any.whl

Download URL	jleechanorg_orchestration-0.2.3-py3-none-any.whl
Size	156.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2912a4d6bbbc73967f0004b872f5f27e781ec9ff4f6565bbb632c0a8cbd8d878`
BLAKE2b-256 checksum How to use checksums	`128a51f9949cd6aaeaedda8a573af5213188fe8515075ffd4823476a57c7c741`
Upload date	Mar 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`