Agent runtime
agent-runtime-py provides detached Claude Code workers that applications can reconnect to after restarting. Import it as agent_runtime. The workers need the claude extra (agent-runtime-py[claude]), which installs the Claude Agent SDK; the hooks, monitors and peer messages do not. It uses the official Claude Agent SDK and your installed Claude Code executable, loading native user and project settings, hooks, skills, and MCP servers.
This repository is under active development. The current implementation supports macOS and Linux and has been exercised with Claude Code 2.1.281 and Claude Agent SDK 0.2.159. Windows is not supported.
from pathlib import Path
from agent_runtime import ClaudeRuntime, LaunchOptions
runtime = ClaudeRuntime(Path.home() / ".local/state/example/claude")
execution = await runtime.start(
"Inspect this project's tests.",
message_id="request-123",
launch_id="conversation-456:request-123",
options=LaunchOptions(cwd=Path.cwd()),
)
The default permission mode is Claude's ordinary permission behavior. Pending approvals and questions are persisted in runtime.store.interactions(execution_id) and remain pending until the application supplies an explicit answer. Applications must present these requests to the user; this library does not auto-approve them.
Lifetime and delivery
- Each execution is a detached Python worker owning one native Claude SDK connection. Destroying the application client does not stop the worker.
- A native session can have several executions after explicit stop and resume. A process lease prevents two managed workers from resuming it simultaneously.
- Message IDs are idempotent within a session. Reusing an ID with different text is an error. A launch ID also fixes the initial prompt and launch configuration.
acceptedmeans privately journaled,dispatchingmeans sent or being sent, anddeliveredrequires Claude to echo the exact input UUID. A crash before that acknowledgement producesuncertain; the runtime never silently replays that input.- Process identity includes PID and process creation time. Restarting a dead worker requires an explicit resume request. A process restart does not imply resubmitting previously delivered work.
- Events have durable increasing cursors across executions. Native SDK messages are retained as
claude.message; presentation events includeagent.message,agent.turn.completed, andwork.settled. - A normal turn result leaves the worker available for more requests. The idle timeout applies only when there is no active request or tracked background task or running monitor. Set it to zero to keep the worker open until explicitly stopped.
- Private SQLite state and logs contain conversation content. Environment variables are passed to the child without being serialized into launch configuration.
runtime.stop(execution_id) requests shutdown. runtime.attach(execution_id) returns an interactive resume command only after the managed worker has stopped, preventing concurrent native ownership. It must be launched from the recorded working directory.
Monitors and local peer messages
Run the hooks from an executable PEP 723 script with an exact agent-runtime-py pin and a [tool.uv] exclude-newer date, whose body is from agent_runtime.hooks import app and if __name__ == "__main__": app.main(). Register that script for SessionStart, UserPromptSubmit and PreToolUse in each host's hook file, with the host name (codex or claude) as its only argument and a timeout of 10 seconds. End each command with || true: uv exits nonzero when it cannot start the script (2, for example, when the package index is unreachable), and both hosts read exit 2 on UserPromptSubmit and PreToolUse as a block. The hooks register native process identities and current permission modes. Claude hooks start a private delivery child whose inherited native inbox token remains in memory; it is never written to the registry or used for messages to another session.
agent_runtime.operations supplies monitor_start, monitor_list, monitor_get, monitor_stop, monitor_events, agents, and send. Codex operations delegate to the installed codexr CLI. Claude monitors run a detached foreground Bash command and retain stdout observations in SQLite; stderr goes to a private log. A 1 MiB output limit stops an overly verbose monitor. Delivery batches retain each monitor's launch permission class. Native Claude receives these as peer context and applies its own admission policy, including holding messages if permission modes require approval. transport-written confirms only a socket write, not admission or model processing. Interrupted writes remain uncertain and are not replayed automatically.
A normal Claude monitor stops when its owning native process exits or its deadline expires. A persistent monitor has no deadline and continues collecting output after CLI exit; resuming the exact native session starts a new delivery child for pending observations. This does not keep a plain claude -p process open or restart processes after a host reboot. Interactive sessions and managed SDK workers receive observations between turns. A managed worker's idle timeout does not end a running monitor.
Cross-session sends identify their source and never use the destination's own-event token. Unknown source permission modes fail closed. Codex receipts preserve its native delivered/queued meanings; Claude socket receipts are transport-only. Native policy or a stopped process can prevent delivery.
Goals use Claude's native /goal, including its evaluator, retry limits and resume behavior. There is no second goal store or emulated Codex goal API. An objective can survive native resume while usage baselines reset; unrecoverable errors can clear it. See Claude goals.
Development
Run uv run pytest -q. The integration tests use the real Claude Agent SDK and detached worker processes against a deterministic fake native CLI. They cover application reconnection, stop/resume, duplicate admission, lost acknowledgement, explicit permission decisions, actual shell monitor failure, process-tree shutdown, deadlines, retained observations across native-owner exit/resume, and peer permission labels. They require no model account or API credentials.
Release publishing uses GitHub Actions trusted publishing. Configure a pending PyPI publisher with project agent-runtime-py, owner nimashoghi, repository agent-runtime, workflow release.yml, and environment pypi. Publishing a GitHub release whose tag matches v<package-version> builds and publishes the package.
Metadata
Release files for agent-runtime-py 0.2.2
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_runtime_py-0.2.2.tar.gz | 82.5 kB | With provenance | Details for agent_runtime_py-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_runtime_py-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for agent_runtime_py-0.2.2-py3-none-any.whl |
Total release size: 109.4 kB
Release files / agent_runtime_py-0.2.2.tar.gz
| Download URL | agent_runtime_py-0.2.2.tar.gz |
|---|---|
| Size | 82.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e736605b67526449ab28480a4bad1906df92678f1449feb652c9ec5290315e13
|
|
BLAKE2b-256 checksum How to use checksums |
49a353d01889bb44eaff82919ba78c74c962b8f0bf3eaf58f3e2174acb856ae7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 11, 2026.
Transparency logRelease files / agent_runtime_py-0.2.2-py3-none-any.whl
| Download URL | agent_runtime_py-0.2.2-py3-none-any.whl |
|---|---|
| Size | 26.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5acb4fd6da390b65c0fdc88650d9eaefe0cefb127ad72d30783a03b28cab1678
|
|
BLAKE2b-256 checksum How to use checksums |
627e472959bf44c430ae705a47c01a16c7c56b3e6b2bf62b262ccd1b918d6a6e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 11, 2026.
Transparency logSecurity for agent-runtime-py 0.2.2
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 agent_runtime_py-0.2.2.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 11, 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.