Agent Orchestration Process (AOP)#

AOP is a command-line tool that runs coding agents such as Claude Code, Codex and Gemini as unattended jobs. It gives automation one CLI for running bounded, non-interactive jobs across different agent harnesses without requiring callers to learn each harness's command flags, session format, output schema, runtime state, or resume behavior:

• Run Codex, Claude Code, Cursor Agent, Devin CLI, OpenCode, Antigravity (agy), Grok Build, Hermes, DeepSeek Harness (dsh), and Zcode through the same run and resume commands. See Harness adapters for current model support and limitations.
• Reuse each harness's existing authentication, model execution, tools, and conversations instead of maintaining a separate AOP credential store.
• Apply the same isolated worktrees, inputs-only sealed runs, configured deadlines, process cleanup, snapshotted inputs, and validated artifacts across harnesses. A harness that reaches its deadline receives a stop signal and a short grace period to save its session before AOP ends the run.
• Retain consistent results, logs, timing, token usage, and exact provider session identity when available.
• Keep cleanup, checkpointing, and Git integration outside agent control.

Codex runs can also use Z.AI Coding Plan as the zai-coding-plan inference provider rather than as a separate harness. AOP resolves the effective native Codex configuration, validates the authenticated model inventory, projects only the selected credential into isolated runs, and preserves the exact route for resume. List the currently available models with:

aop models --agent codex --provider zai-coding-plan

Agent Client Protocol (ACP) standardizes interactive communication between agents and clients such as editors and IDEs. Use ACP when a person needs to chat, approve actions, watch progress, and steer a session.

Use AOP when software needs to run bounded jobs unattended across different agent CLIs. The two are complementary: ACP serves interactive clients, while AOP serves automation.

Install and run#

AOP requires Linux and Python 3.11 or newer. The edit, review, and sealed profiles require bwrap. Git is required for edit, review, and host. Install and authenticate at least one supported agent harness.

Install AOP from PyPI:

uv tool install agent-orchestration-process

Run a sealed task from any directory without exposing local files or requiring a Git repository:

aop run --agent codex --profile sealed --prompt "Explain the difference between TCP and UDP"

Run a task in an existing Git repository:

aop init
aop run task-a --agent codex --prompt "Implement the parser and its tests"

aop init adds /.aop/ to .gitignore; commit that change before integrating tasks. AOP creates the task worktree automatically and prints the run ID needed to resume the exact provider session:

aop resume <run-id> --prompt "Address the review findings"

Give a run read-only copies of files or whole project folders with --input, and leave out build output or large files with --input-exclude; --dry-run checks every input before anything is copied. Follow a running harness with tail -f .aop/runs/<run-id>/events.jsonl.

See the CLI guide for other harnesses, inputs, artifacts, batch runs, cleanup, and machine-readable results. See Integration when a task's changes are ready to checkpoint and merge.

Execution profiles#

AOP profiles describe the complete execution boundary rather than only where writes are allowed. The isolated profiles expose only the declared workspace, inputs, provider runtime, private state, cache, scratch, output, and required operating-system paths. host runs without that isolation.

Profile	Use it when
edit	The agent should modify an isolated task worktree.
review	The agent should inspect a task worktree without modifying it.
sealed	The agent should see only explicit input snapshots, with no repository or inherited instructions.
host	The command needs the native host environment and filesystem.

Inspect a declared profile or preview the intended policy without compiling or dispatching it:

aop profile explain sealed
aop profile explain sealed --agent codex --json
aop run study-arm --profile sealed --prompt "Answer using only declared inputs" --dry-run

Profiles retain native network connectivity because the supported provider CLIs need it, except under --no-web. See Execution profiles for the exact filesystem, instruction, environment, credential, input, and output boundaries.

Use --no-web to deny model-controlled external retrieval while retaining the harness's inference connection. AOP restricts the harness's own web tools and, in sandboxed profiles, gives the run a network namespace whose only way out is a proxy allowing the harness's inference and login endpoints. AOP records the effective policy and every connection attempt, and rejects harnesses that cannot enforce the boundary. See CLI guide for current support.

Codex --no-web uses the canonical top-level web_search = "disabled" mode introduced in Codex 0.82.0. AOP's current Codex app-server integration targets Codex 0.150.1 or newer.

Results and usage#

Every adapter records the same result shape, including provider session identity when available, timing, token usage, cost evidence, logs, and declared artifacts. See Token usage and pricing for the normalized token contract, provider mappings, and cost calculation rules.

Results distinguish complete accounting from partial or unavailable deadline accounting. Codex deadlines use native app-server interruption to retain per-turn usage and an API-equivalent cost when available. If any harness terminates before reporting usage, usage and cost fields remain null instead of being reported as measured zero.

AOP also keeps a copy of every result in ~/.local/state/aop/results/ (under $XDG_STATE_HOME when set), so a run's usage and cost remain available after the directory holding its .aop is deleted. Each result names the .aop directory it ran in.

AOP reads only current run records. After upgrading from a version that wrote older records, run aop migrate-results once; it converts them in place and keeps each original beside it. See Token usage and pricing.

Development#

Clone the repository and synchronize its locked development environment:

git clone https://github.com/wakamex/agent-orchestration-process.git
cd agent-orchestration-process
uv sync --locked
uv run --locked python -m unittest discover -s tests
uv run --locked ruff check src tests