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.
  • 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.
  • 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 include agent.message, agent.turn.completed, and work.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)

Source distribution for agent-runtime-py 0.2.2
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)

Table of built distributions (wheels) for agent-runtime-py 0.2.2
File Interpreter ABI Platform Actions
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 log

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

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

Select from 2 files

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