coding-agent-cli
Run coding-agent CLIs from Python, stream typed events, and get a classified result.
Built-in drivers: claude, codex, pi, and agy. Python 3.12 or later on Linux, macOS, and Windows. No runtime dependencies.
Install
pip install coding-agent-cli
The CLIs themselves are not bundled. Install and log in to each one you use.
Quick start
import asyncio
from pathlib import Path
from coding_agent_cli import Request, run
async def main() -> None:
result = await run(Request(driver="claude", prompt="Summarize README.md", cwd=Path.cwd()))
print(result.outcome, result.text)
asyncio.run(main())
Streaming events
Use stream inside async with. Leaving the block, by break or by an exception, cancels the run and kills the process tree.
from coding_agent_cli import RunCompleted, TextDelta, stream
async def main() -> None:
async with stream(Request(driver="codex", prompt="List the tests", cwd=Path.cwd())) as events:
async for event in events:
if isinstance(event, TextDelta):
print(event.text, end="")
elif isinstance(event, RunCompleted):
print("\n", event.result.outcome)
run also accepts on_event, an async callback that receives the same events. An exception raised by on_event is raised from run after the process tree is killed.
Synchronous use
from coding_agent_cli import run_sync
result = run_sync(Request(driver="pi", prompt="Hello", cwd=Path.cwd()))
run_sync raises RuntimeError when called inside a running event loop. Await run there instead.
Checking a CLI
from coding_agent_cli import check
caps = await check(Request(driver="agy", prompt="", cwd=Path.cwd()))
print(caps.available, caps.executable, caps.structured_streaming)
Request
| Field | Meaning |
|---|---|
driver |
Driver name, such as claude. |
prompt |
The prompt text. |
cwd |
Working directory for the CLI. |
session_id |
Resume this CLI session. |
model |
Portable model option. |
reasoning |
Portable reasoning or effort option. |
system_prompt |
Portable system prompt option. |
args |
Extra CLI arguments, appended by the driver. |
env |
Variables layered over the inherited environment. |
timeout_s |
Wall-clock limit in seconds. |
executable |
Path or name of the CLI to run instead of the default. |
Portable options
| Option | claude | codex | pi | agy |
|---|---|---|---|---|
model |
--model |
--model |
--model |
--model |
reasoning |
--effort |
-c model_reasoning_effort=<value> |
--thinking |
unsupported |
system_prompt |
--system-prompt |
unsupported | --system-prompt |
unsupported |
An unsupported option returns a request_fatal result with code unsupported_option. Setting a portable option and the same flag in args returns invalid_args. So does passing a flag the driver owns for its transport, such as --output-format.
Permission and approval flags
The drivers never add a permission, approval, or sandbox-bypass flag. A run that needs tools without prompts must pass the flag through args:
| CLI | Flag for unattended runs | Notes |
|---|---|---|
| claude | --permission-mode bypassPermissions |
--dangerously-skip-permissions is equivalent. |
| codex | --dangerously-bypass-approvals-and-sandbox |
Also accepted as --yolo. Use only inside an external sandbox. |
| pi | none | --approve trusts project-local files for the run. It is not a tool-permission bypass. |
| agy | --dangerously-skip-permissions |
Auto-approves all tool permission requests. |
Request(driver="codex", prompt="Fix the failing test", cwd=repo, args=("--dangerously-bypass-approvals-and-sandbox",))
These flags give the agent full control of the machine it runs on. Use them only in an environment you are prepared to lose.
Events
Every event has a kind, a sequence that strictly increases within a run, an optional entity_id, and a schema_version. Each run ends with exactly one RunCompleted, sent after the process tree is gone.
| Class | kind |
Fields |
|---|---|---|
SessionIdentified |
session.identified |
session_id |
MessageStarted |
assistant.message.started |
none |
TextDelta |
assistant.text.delta |
text |
MessageCompleted |
assistant.message.completed |
none |
ToolStarted |
tool.started |
tool, activity, input |
ToolCompleted |
tool.completed |
status |
UsageUpdated |
usage.updated |
usage |
RunCompleted |
run.completed |
result |
Outcomes
Outcome |
Meaning |
|---|---|
success |
The CLI finished and returned text. |
retryable |
Possibly transient: timeout, service error, nonzero exit, or no output. |
agent_fatal |
The CLI cannot run here: missing CLI, spawn failure, or authentication. |
request_fatal |
The request itself is wrong: bad arguments, unsupported option, invalid model, or context overflow. |
cancelled |
The caller cancelled the run. |
Result.error holds a Diagnostic with a code and message. Result.warnings holds non-fatal diagnostics.
Retryable is not replay-safe. A retryable run may already have edited files, run commands, or spent tokens. Check the working tree before you send the same prompt again.
Cancellation
Pass an asyncio.Event as cancel. Setting it ends the run with a cancelled result that keeps any partial text. From another thread, set it through the loop:
cancel = asyncio.Event()
loop = asyncio.get_running_loop()
# in the other thread:
loop.call_soon_threadsafe(cancel.set)
Custom drivers
A driver implements the Driver protocol: async check(req, *, refresh=False) -> Capabilities and async run(req, *, on_event, cancel, on_spawn) -> Result. Register it in a DriverRegistry and pass the registry to any entry point:
from coding_agent_cli import DriverRegistry
registry = DriverRegistry()
registry.register("my-cli", MyDriver())
result = await run(Request(driver="my-cli", prompt="Hi", cwd=Path.cwd()), registry=registry)
DriverRegistry(builtins=False) starts empty. An unknown driver name raises KeyError.
Known limits
- Windows process trees. Cleanup uses
taskkill /T /F. A descendant whose launcher exits first can be missed. Job Objects are not used in 0.1. - Live behavior. The test suite uses fake CLIs. The live tests in
tests/test_live.pyrun the real CLIs and are excluded by default:uv run pytest -m live -rP.
Contributing
Contributions are welcome. Read CONTRIBUTING.md for setup, the coding standard, and the pull request process. Report security problems privately as described in SECURITY.md. Everyone taking part follows the Code of Conduct.
uv sync
uv run ruff format --check && uv run ruff check
uv run pyright
uv run pytest
License
Provenance
This library is extracted from the CLI-driver layer of Refract, a multi-model coordination tool. Its drivers, process handling, and many of its tests are ported from Refract under the MIT license.
Metadata
Release files for coding-agent-cli 0.1.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 |
|---|---|---|---|---|
| coding_agent_cli-0.1.0.tar.gz | 158.3 kB | With provenance | Details for coding_agent_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| coding_agent_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for coding_agent_cli-0.1.0-py3-none-any.whl |
Total release size: 202.7 kB
Release files / coding_agent_cli-0.1.0.tar.gz
| Download URL | coding_agent_cli-0.1.0.tar.gz |
|---|---|
| Size | 158.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d4a10e5d134a75923c112b506d6b47088b8729ece7081791a896748257634ca9
|
|
BLAKE2b-256 checksum How to use checksums |
afc45229604841dc5adc23eb738c31dcfe0343b5ac8d8852e5f56cce683f614e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / coding_agent_cli-0.1.0-py3-none-any.whl
| Download URL | coding_agent_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 44.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
10b9f1648a3ee47b690682eb9ec30673d51f144f34108cb81d28c730cab0a315
|
|
BLAKE2b-256 checksum How to use checksums |
230d73cbe5e5b4d2116eec6f99316266495efd800b17d8e5924edc32f87d312b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for coding-agent-cli 0.1.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for coding_agent_cli-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA 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.