Skip to main content

Agent Orchestration Process (AOP)

AOP is a command-line tool for running coding agents such as Claude Code and Codex as unattended jobs. It is for automation: CI jobs, batch experiments, benchmarks, and programs that hand work to an agent and need a dependable result back. One aop run command drives eleven different agent CLIs, called harnesses here, and gives every run the same sandbox, deadline, and result record, so a caller does not need a separate adapter for each CLI's flags, sessions, and output.

  • Run Codex, Claude Code, Cursor Agent, Devin CLI, OpenCode, Antigravity (agy), Grok Build, Hermes, DeepSeek Harness (dsh), Zcode, and Muse Code through the same run and resume commands. Each keeps its own login, models, and tools.
  • Isolate each run in a Git worktree or an empty sealed workspace, inside a bubblewrap sandbox, with optional network-level blocking of web access.
  • Get one JSON result per run: the answer, timing, token usage, an API-equivalent cost, the harness session ID for exact resume, and whether the provider refused.
  • Keep cleanup, checkpointing, and Git integration outside the agent's control.

Agent Client Protocol (ACP) connects agents to editors for interactive sessions, where a person chats, approves actions, and steers. AOP serves the opposite case: software running bounded jobs with nobody watching. The two are complementary.

Requirements

  • Linux. AOP's sandbox is built on Linux namespaces.
  • Python 3.11 or newer and uv.
  • bwrap (bubblewrap) for the sandboxed profiles, with unprivileged user namespaces allowed. On Fedora and Debian, install the bubblewrap package. Ubuntu 24.04 and later also need sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0.
  • Git, for runs in a repository.
  • At least one harness, installed and signed in. Codex needs version 0.150.1 or newer and Antigravity 1.1.16 or newer; Harness adapters lists the versions each adapter was last tested with.

Quickstart

Install AOP from PyPI:

uv tool install agent-orchestration-process

Run a sealed task. It sees no repository and no local files, only what you pass with --input:

aop run --agent claude --profile sealed --prompt "Reply with only the word copper."

The answer goes to stdout; the run's details go to stderr:

aop: run_id=74a91b9f-d64e-45cd-9c56-b308c8840d58 session_id=fba843cd-3050-4672-a39b-1deaa63ef5d9 time=2.13s tokens=16887 accounting=complete calculated_cost=$0.000171 provider_reported_cost=n/a billing=subscription artifacts=/home/me/.aop/runs/74a91b9f-d64e-45cd-9c56-b308c8840d58
copper

AOP records the run in a .aop folder in the directory you ran it from. Add --json for the full result as one object, abridged here:

{
  "run_id": "5f668bbc-cad7-4852-b1b3-00b021952dd2",
  "provider": "claude",
  "model": "claude-haiku-5-5",
  "status": "succeeded",
  "final_message": "copper",
  "session_id": "24ec7778-cd70-450f-a1f1-9090ae51b889",
  "duration_seconds": 2.18,
  "error": null,
  "usage": {"input_tokens": 16883, "cached_input_tokens": 11227, "output_tokens": 4},
  "accounting_status": "complete",
  "calculated_cost": {"amount_usd": 0.00124527, "currency": "USD", "priced_as": "claude-haiku-5-5"},
  "billing": {"route": "subscription", "credential_source": "claude-oauth"},
  "refusal": null
}

Continue the same harness session from any directory with the run ID:

aop resume 5f668bbc-cad7-4852-b1b3-00b021952dd2 --prompt "Now reply with silver."

To work on a repository, run from inside it. AOP creates a worktree for the task and leaves your checkout alone:

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

aop init adds /.aop/ to .gitignore; commit that before integrating tasks. See Integration for merging a task's changes back.

Safety defaults

AOP is built to run agents unattended, so know what a run can do before you start one:

Running unattended covers what the sandbox does and does not stop, every result status and exit code, recovery after a crash, and cleanup.

Execution profiles

--profile sets what a run can see and change. The default is edit.

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, with no sandbox.

Preview a run's boundary without starting it:

aop run --agent codex --profile sealed --prompt "Answer using only declared inputs" --dry-run

See Execution profiles for exact filesystem, instruction, environment, credential, input, and output boundaries, and CLI guide for --no-web.

Documentation

Development

See CONTRIBUTING.md for setting up a checkout and running the tests, including the opt-in tests against installed harnesses.

Metadata

Release files for agent-orchestration-process 0.7.0

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

Source distribution (sdist)

Source distribution for agent-orchestration-process 0.7.0
File Size Uploaded Provenance Actions
agent_orchestration_process-0.7.0.tar.gz 140.0 kB Without provenance Details for agent_orchestration_process-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-orchestration-process 0.7.0
File Interpreter ABI Platform Actions
agent_orchestration_process-0.7.0-py3-none-any.whl Python 3 none any Details for agent_orchestration_process-0.7.0-py3-none-any.whl

Total release size: 291.9 kB

Release files / agent_orchestration_process-0.7.0.tar.gz

Download URL agent_orchestration_process-0.7.0.tar.gz
Size 140.0 kB
Tags Source
SHA-256 checksum
How to use checksums
dadd9b514d1e6a735dc7644191a6e87fb3cbfee38b57e1e630bcbd81d60d8f98
BLAKE2b-256 checksum
How to use checksums
be91dd7a50892b85ae80d1ab73e26e656c1421987dd0563186251ea8b7e46d12
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / agent_orchestration_process-0.7.0-py3-none-any.whl

Download URL agent_orchestration_process-0.7.0-py3-none-any.whl
Size 151.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e0e79c6395def61d62f1513978f1970c81cad46f23eab6ed250a85034c0b431
BLAKE2b-256 checksum
How to use checksums
a17fcb233ea175b3289f1c3884463045123c9c143b70de94a4a6c11527b70b51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for agent-orchestration-process 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page