English | Türkçe

agent-orchestrator

Point it at the agent you are already running. It picks up from there.

No new harness. No re-planning. No "start a fresh session so the tool can manage it." ao attaches to a coding agent that is already working — in your IDE, in a terminal, started by someone else — reads its state without touching it, and takes over the tedious half: noticing when it stalls, running the gates, deciding what may be committed, and keeping work moving while you sleep.

That is the whole difference. Every other orchestrator owns the agent: it spawns the process, it drives the loop, and adopting it means restarting your work inside it. ao owns the authority instead — what is finished, what is good, what may land — and leaves the agent where it is.

pip install ao-orchestrator                  # or: uv tool install ao-orchestrator
cd ~/your-project && ao status      # it finds the running session by itself

Or with nothing installed at all, using the Python macOS and most Linux distributions already ship:

git clone https://github.com/hakkisagdic/agent-orchestrator ~/ao
echo 'alias ao="$HOME/ao/bin/ao"' >> ~/.zshrc && exec zsh

No dependencies, by choice — this watches agents on machines it does not control, and a dependency is a thing that can be missing exactly there. Nothing to configure before the first run: ao discovers the session from the agent's own store.

Windows ships PowerShell and does not ship Python, so bin/ao.ps1 covers status, board and doctor with nothing installed. It is a deliberate subset and stays one — everything else either takes a decision, spends the machine, kills processes or speaks a protocol, and a second implementation of any of those is a second thing to be wrong. For the rest: winget install Python.Python.3.12 && pip install ao-orchestrator. The script is written and reviewed but not yet run on Windows.

Where this came from. Extracted from a 30-epic durable-workflow product built over weeks by exactly this loop. Every guard in here exists because something went wrong first: a watchdog that started a second turn on one session and left a rename half-applied; fifteen agent processes accumulated in one repository; a timestamp bug that made live evidence look three hours stale. docs/lessons.md is the list. None of it was designed in advance.

What it does

Watches. ao watch is a live panel: what the agent is doing, context and cost, open reviews, the work board, and — the part no other panel has — whether it is busy but producing nothing. An agent stuck in a wait loop looks perfectly healthy: transcript growing, tool calls firing, credits burning. ao compares activity against artifacts and says so.

Restarts. Turn-based agents stop when a turn ends, mid-slice or not. A watchdog notices and nudges. Detection is free — a file mtime and a couple of git calls — and a chain of guards makes sure a nudge is never spent where it cannot help: no second turn while one is running, no nudge into a provider outage, no nudge past the round budget, no nudge when a human has taken the tree.

Verifies. ao verify runs your gates and writes the numbers to a ledger. Not the agent's report of its gates — the commands, run again, by something with no stake in the result.

Decides. ao commit-ok grants commit authority from that evidence: gates passed, review approved, plan unedited, and the measurement still describes the tree in front of it. Every refusal names its missing condition. It never covers push.

Keeps going. A slice blocked on a human decision is parked with the reason recorded, and work moves to the next pre-authorised item. When the queue runs dry, the architect is woken to refill it — never the implementer, because choosing your own scope is the one authority an implementer must not have.

Commands

The rules it enforces

These are not style preferences. Each one is a failure that cost real hours.

• Whoever writes the code does not verify it, and does not decide it may land.
• A plan is read, never edited — when the document a slice is judged against can be edited by the thing being judged, every later check is circular.
• Pulling work is not authorising it. A tracker item is something a person wrote, not a specification anyone verified. It enters the queue with a written acceptance boundary or it does not enter.
• Heavy operations belong to one actor. Gates are serialised machine-wide; N projects running N test suites is not N times the throughput, it is one suite that no longer finishes.
• Authority lives in always-included context, never in a mailbox. A stuck agent is exactly the agent not reading its mail.
• push is never granted by this tool. Nor PRs, force-pushes, or hook bypasses.

Agent support

ao reads each agent's own session store; the adapter says where and in what shape.

ao adapters shows this table against what is actually installed on your machine, and — with keyflip — whether an account exists even when the CLI does not. Adding one is a JSON file; see docs/adapters.md.

Documentation

protocol · safety · roles · slices · gates · sources · adapters · parallel · cloud · models · telegram · mcp · telemetry · surfaces · ledger · recovery · keyflip · ide-extensions · lessons

Status

Working today: everything in the command table above, exercised daily against a real project. Still specification: ao init, ao decide, ao since, and cross-project parallel execution (the view exists; running several implementers at once is governed by the machine gate lock but has not been run in anger).

MIT.