Autonomous Multi-Agent Coordination, File-Based IPC Event Bus, and Reactive Execution Engine. Built for pair-programming and autonomous workflows involving Claude Code, OpenAI Codex, Google Antigravity, Cursor, and automated pipelines.
Modern AI software development uses multiple specialized autonomous agents working concurrently:
- One agent implements backend code (e.g. Codex)
- Another agent reviews or refactors (e.g. Claude Code)
- A supervisory agent handles git synchronization, test verification, and CI tracking (e.g. Git Engine / Antigravity)
The Problem: Without a conductor, multi-agent setups suffer from:
- Race conditions: Two agents edit files at the same time, producing merge conflicts or overwritten code.
- Siloed communication: Agents cannot easily message each other across separate terminal sessions without manual human copy-pasting.
- Manual handoffs: Developers have to manually run verification test suites, stage commits, and push branches after an agent finishes.
The Solution: Agent Orchestra acts as the autonomous conductor. It provides:
- Instant Reactive Detection: Detects the moment an agent touches code or claims a task via an event-driven filesystem watcher.
- File-Based IPC Event Bus: Distributed pub/sub message broker (
events.jsonl) that works across all CLI agents with zero external dependencies. - Single-Writer Lock Manager: Prevents multiple agents from stepping on each other; enforces strict atomic ownership leases.
- Automated Script Execution: Automatically runs Python verification scripts, unit test suites, or contract probes upon agent handoffs.
- Autonomous Git Sync: Auto-commits with structured conventional messages, rebases on remote, and fast-forwards secondary branches.
- CI Monitoring: Connects to remote CI (GitHub Actions) using native Git credential helpers without leaking tokens.
Agent Orchestra is engineered to be 100% self-contained:
- Written in modern Python 3.10+ using only standard libraries (
json,subprocess,threading,pathlib,urllib). - Zero mandatory external packages.
- Works across Windows (PowerShell/CMD), Linux (Bash/Zsh), and macOS.
- Designed to be cut and pasted into any repository or published as an independent package on GitHub.
agent-orchestra/
βββ pyproject.toml # Modern Python packaging & CLI entry points
βββ README.md # Full documentation & usage guide
βββ .gitignore # Ignores runtime events, locks, and pycache
βββ orchestra.default.json # Starter configuration for any codebase
βββ orchestra.sefgh.json # Production configuration tailored for SEFGH
βββ orchestra/
β βββ __init__.py # Public API exports
β βββ cli.py # Full CLI interface (`orchestra claim`, `release`, etc.)
β βββ daemon.py # Central conductor event loop & state machine
β βββ bus.py # File-based IPC event bus & distributed lock manager
β βββ models.py # JSON-serializable dataclasses & event schemas
β βββ watcher.py # Debounced filesystem watcher with mtime tracking
β βββ runner.py # Python & shell script execution engine
β βββ git_sync.py # Git staging, commit, rebase, and multi-branch sync
β βββ ci_tracker.py # GitHub Actions workflow run tracker
βββ scripts/
β βββ example_verifier.py # Sample Python verification script emitting JSON
β βββ example_notifier.py # Sample webhook/notification script
β βββ sefgh_bridge.py # Bridge for docs/coordination.md integration
βββ tests/
βββ test_bus.py # IPC bus & lock manager tests
βββ test_config.py # Config loader tests
βββ test_models.py # Event serialization tests
βββ test_runner.py # Script runner & timeout tests
Run directly with Python, or install in editable mode:
# Direct execution:
python -m orchestra --help
# Or install locally:
pip install -e .orchestra initThis generates an orchestra.json configuration in your root directory.
The config is checked strictly. An unknown key (such as a typo like auto_psuh), a malformed file, or a section that isn't an object stops every command with an error naming the problem. Keys you leave out keep their defaults. workspace_root is resolved relative to the folder holding the config file.
Orchestra drives the official agent CLIs with your existing logins, so ChatGPT Plus or Google AI Pro subscriptions are used directly, with no API keys.
orchestra doctor # which agents are installed and logged in
orchestra chat "explain this repo" # one turn with Codex (ChatGPT) in the current folder
orchestra chat -a claude -C ../app # a conversation with Claude Code in another folder
orchestra chat -r <session-id> "and now add tests" # continue a previous sessionAgent (-a) |
Account | Needs |
|---|---|---|
codex (default) |
ChatGPT Plus / Pro | npm install -g @openai/codex, then codex login |
antigravity |
Google AI Pro / Ultra | Antigravity CLI (agy), signed in once interactively |
claude |
Claude Pro / Max | Claude Code, signed in |
-p sets what the agent may do: read-only, edit (default, changes files inside the project) or full (no limits). --json prints the normalized event stream instead of formatted text. Ctrl+C stops the current turn and the agent's processes.
Agents interact with the Orchestra using simple CLI commands or the Python API:
When Claude Code or Codex starts a task:
orchestra claim AUTH-001 --agent claude --scope "OAuth2 token rotation" --lease 1800- Emits an
AGENT_CLAIMevent on the IPC bus. - Creates
.orchestra/writer.lock. - Other agents trying to claim will be blocked until the lease expires or is released.
- Claims are atomic across processes: if several agents claim at once, exactly one wins.
Any agent or human can check the real-time status:
orchestra status=== AGENT ORCHESTRA STATUS ===
State: WRITER_ACTIVE
Is Locked: True
Task: AUTH-001
Agent: claude
Scope: OAuth2 token rotation
Git Branch: main (HEAD: 732d0dc)
Git Clean: False (3 changed files)
Latest Event: AGENT_CLAIM by claude
Or as JSON for machine parsing:
orchestra status --jsonWhen an agent finishes implementation:
orchestra release --agent claude --status complete --summary "Implemented JWT rotation and 12 unit tests"- Emits a
HANDOFF_REQUESTevent carrying the status and the lock that was released. - Removes
.orchestra/writer.lock. - The daemon passes the handoff to
should_ship()inorchestra/policy.py. Only handoffs it approves are verified, committed, and pushed. --status pausedand--status failednever ship. The daemon reportsPAUSED_CHECKPOINTand leaves the work untouched.
Agents can broadcast custom telemetry, review verdicts, or notifications:
orchestra emit REVIEW_VERDICT '{"task_id": "AUTH-001", "accepted": true, "comments": "All tests pass"}' --agent codexStream all agent activities in real-time:
orchestra listenOutput:
[LISTEN] Listening to Agent Orchestra event bus (Ctrl+C to stop)...
[AGENT_CLAIM] (claude) -> {"task_id": "AUTH-001", "scope": "OAuth2 token rotation"}
[TASK_PROGRESS] (claude) -> {"changed_count": 3, "sample_files": ["src/auth.py"]}
[HANDOFF_REQUEST] (claude) -> {"task_id": "AUTH-001", "status": "complete"}
[VERIFICATION_STARTED] (orchestra) -> {"command": "python scripts/example_verifier.py"}
[VERIFICATION_RESULT] (orchestra) -> {"success": true, "duration_seconds": 1.2}
[GIT_COMMITTED] (orchestra) -> {"commit_message": "chore(orchestra): automated multi-agent handoff sync"}
[GIT_SYNCED] (orchestra) -> {"main_branch": "main", "synced_branches": ["go-backend"]}
Agent Orchestra can execute custom Python scripts at every phase of the lifecycle:
{
"pipeline": {
"pre_claim_command": "python scripts/pre_flight.py",
"verify_command": "python scripts/example_verifier.py",
"post_sync_command": "python scripts/example_notifier.py",
"on_error_command": "python scripts/alert_failure.py"
}
}You can also run any Python script directly through the Orchestra runner:
orchestra run scripts/example_verifier.py --verboseThe runner:
- Enforces execution timeouts, killing the command and everything it started (for example
npmand thenodeprocesses under it) - Captures stdout and stderr cleanly
- Automatically extracts JSON metrics printed by the script into structured execution reports
To have the Orchestra run continuously in the background:
orchestra start --interval 2.0The daemon will:
- Watch watched paths for file modifications.
- Read new
HANDOFF_REQUESTevents fromevents.jsonl, resuming from.orchestra/daemon_cursor.jsonafter a restart. On its first start it skips existing history. - Run the verification pipeline once per approved handoff, holding the writer lock as
orchestraso no agent can start editing mid-pipeline. A dirty tree with no handoff is only reported, never committed. - When verification passes, commit on
main_branch. Withauto_push, it then fetches, rebases onto the remote, pushes, and moves eachsync_branchesentry forward on the remote (git push origin main:<branch>, with no checkout). If any step fails, the sync stops there: a failed rebase is aborted, nothing more is pushed, aGIT_SYNC_FAILEDevent names the step, and the state goes toERROR. If a different branch is checked out, nothing is committed. - Publish all lifecycle events to
events.jsonl, includingCUSTOM_EVENTwith"action": "handoff_skipped"when a handoff is not shipped. - Hold
ERRORafter a failed verification or sync until the next writer claims the lock.
To use this in other projects (Outcome Verifier, campus360-api, etc.):
- Cut or Copy the folder:
cp -r d:/SEFGH/sefgh-nextjs-main/agent-orchestra d:/projects/agent-orchestra
- Push to GitHub:
cd d:/projects/agent-orchestra git init git add . git commit -m "feat: initial commit of Agent Orchestra engine" git remote add origin https://github.com/Adeel0-0/agent-orchestra.git git push -u origin main
- Drop it into any project:
- As a submodule:
git submodule add https://github.com/Adeel0-0/agent-orchestra.git tools/orchestra - Or install via pip:
pip install git+https://github.com/Adeel0-0/agent-orchestra.git - Run
orchestra initin that new repo and configureorchestra.json.
- As a submodule:
See docs/OPENROUTER.md for keyring setup, tool-capable models,
permissions and verification. Start with python -m pip install -e ".[openrouter]",
then python -m orchestra openrouter-key, python -m orchestra models and
python -m orchestra chat -a openrouter -m <model-id> in an interactive terminal.
The Phase 3 local API provides durable sessions and protected
HTTP/WebSocket access. Install .[app] and run python -m orchestra serve; it prints
a random loopback URL and private launch token. The window/UI is still Phase 4.
cd agent-orchestra
python -m unittest discover testsThe suite covers models, event serialization, single-writer locking (including a multi-process claim race), the handoff-driven pipeline and git sync on throwaway repos with a bare remote, the shipping policy, script timeouts, strict configuration, entry points, recorded Codex/Claude event translation and cancellation. OpenRouter tests add confined file tools, approval/denial, shell timeout/output limits, SSE parsing and local HTTP streaming, context summaries and usage accounting. Tests do not use real API credentials or credits.
MIT License. Created by Syed Mohammad Adeel.