Skip to main content

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: a new worker waits up to 30 seconds for the worker before it to be gone.
  • 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.
  • accepted means privately journaled, dispatching means sent or being sent, and delivered requires Claude to echo the exact input UUID. A crash before that acknowledgement produces uncertain; the runtime never silently replays that input. A worker that ends records its result and the receipts of its open inputs (uncertain, or rejected for an input that it had not taken) in one transaction.
  • A worker process is known by its PID and its command line, which names the execution; a step of the system clock does not make a live worker look gone, and neither does a process that cannot be inspected: only proof ends a running worker's record (no such process, a zombie, another process's command line, or, for a process that cannot be inspected, a free session lease after the worker took it). The proof is made on the machine that runs the worker; a store must not be shared between hosts or PID namespaces. In one rare case a dead worker counts as running until another process ends: it died before it took the session's lease (or was started by 0.2.3), and its PID now belongs to a process that cannot be inspected. runtime.store.finish(execution_id, result, rejection=..., observed=True) records such an execution as ended. Other processes (native sessions, monitors) are known by 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 include agent.message, agent.turn.completed, and work.settled. runtime.store.snapshot(session_id, after=cursor) reads a session's executions, its new events and all its receipts in one transaction; separate reads can fall between two writes of a worker.
  • 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. A worker that exits closes its execution to new inputs first (state stopping), and submit with resume=True then starts a new execution. A worker that exits on idle does not close while an accepted input waits, so it never leaves an input that it was given. On any other exit (a stop, a failure), every input that the worker had not taken yet is rejected together with the worker's result: the inputs that waited behind a running turn, and one that is accepted in the moment (up to about 0.1 s) before the worker closes. A reader of snapshot calls inspect on an execution without a result to learn whether its worker still runs.
  • 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.4

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-runtime-py 0.2.4
File Size Uploaded Provenance Actions
agent_runtime_py-0.2.4.tar.gz 91.7 kB With provenance Details for agent_runtime_py-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-runtime-py 0.2.4
File Interpreter ABI Platform Actions
agent_runtime_py-0.2.4-py3-none-any.whl Python 3 none any Details for agent_runtime_py-0.2.4-py3-none-any.whl

Total release size: 122.7 kB

Release files / agent_runtime_py-0.2.4.tar.gz

Download URL agent_runtime_py-0.2.4.tar.gz
Size 91.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a1e18450eef8bbc5dc24488c41fde7e5fae8df8e46bd20804afbc539b71be8ef
BLAKE2b-256 checksum
How to use checksums
d91c8186099beab2cded5bc783c2cb3bcc1901ba7b8935f2a6e08ee8844b88bb
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 log

Release files / agent_runtime_py-0.2.4-py3-none-any.whl

Download URL agent_runtime_py-0.2.4-py3-none-any.whl
Size 31.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cf226a34fe88c886a77e509a5365490f5eb844868005c3af44a9d7bf31b403a4
BLAKE2b-256 checksum
How to use checksums
38365adbf6b8b2a368c10f6cd303be69350c39589ce7220fe4de179e4aca5e77
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 log

Security for agent-runtime-py 0.2.4

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 agent_runtime_py-0.2.4.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 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