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 samerunandresumecommands. 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 thebubblewrappackage. Ubuntu 24.04 and later also needsudo 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
- CLI guide: running and resuming tasks, inputs and artifacts, batches, models, and cleanup.
- Execution profiles: what each profile exposes.
- Running unattended: safety, statuses, exit codes, and recovery.
- Harness adapters: per-harness support, versions, and options.
- Token usage and pricing: the usage and cost fields, and upgrading old run records.
- Integration: checkpointing and merging task changes.
- Glossary: the terms these pages use.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.