Skip to main content

coding-agent-cli

CI PyPI Python License: MIT

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.py run 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

MIT

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)

Source distribution for coding-agent-cli 0.1.0
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)

Table of built distributions (wheels) for coding-agent-cli 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

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