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 ten 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), and Zcode 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.5.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.5.0
File Size Uploaded Provenance Actions
agent_orchestration_process-0.5.0.tar.gz 123.8 kB Without provenance Details for agent_orchestration_process-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 259.4 kB

Release files / agent_orchestration_process-0.5.0.tar.gz

Download URL agent_orchestration_process-0.5.0.tar.gz
Size 123.8 kB
Tags Source
SHA-256 checksum
How to use checksums
de76e2617d8c5020ac0f3cb72725d9d763f04ec9f453fc3d09c299a20eecd359
BLAKE2b-256 checksum
How to use checksums
67c7cb848606aafe97be1ccbea05bcd7440dec07bfb15855091bc1d69c05c88b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.5.0-py3-none-any.whl

Download URL agent_orchestration_process-0.5.0-py3-none-any.whl
Size 135.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df9471ae216529e8035e1ff47e605250c0f0c352d916caf748beb4b06cef5d5e
BLAKE2b-256 checksum
How to use checksums
f65ab46a2f4cc1122f38104d18677965c40c447a85d795581cfd7d6da4ebfa84
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.5.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.5.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