Agent Sidecar

English | 简体中文

Latest release · Website/demo

Agent Sidecar is a local-first CLI for observing AI-agent sessions. It discovers persisted session metadata, infers lifecycle state, follows normalized events, and presents the result as text, JSON, or a terminal dashboard. It can also aggregate read-only list and status snapshots over SSH, concurrently follow local and remote events, and, when explicitly authorized, start an experimental local headless resume to send a message. An optional HTTP panel and API expose read-only daemon data on local IPv4 loopback.

The observation commands do not edit agent transcripts, configuration, or hooks. send is a separate mutating boundary: the resumed native agent may contact its provider, run tools, and modify agent-owned state. The daemon writes its own socket and PID file, bounded ephemeral private temporary snapshots, and rotating private diagnostics. Only when HTTP is explicitly enabled does it also retain a private http.token and own a transient http.port record while running. Send-audit files are written by the mutating CLI send path, not by daemon observation. Those daemon and audit bookkeeping files do not themselves edit transcripts or agent configuration; a resumed native agent can do so as described above. The release installer writes only the selected executable and optional skill bundle; the checkout installer creates integration symlinks.

Version 0.5.0 requires Python 3.9+ and has no runtime Python dependencies. DSH event watching additionally requires an external zstd executable.

Version 0.5.0

Version 0.5.0 provides concurrent local/remote watch --all --remote, durable private send auditing and request-ID idempotency, and the opt-in numeric-loopback HTTP panel. It also includes a deterministic executable zipapp, package metadata suitable for pipx, an explicit macOS user LaunchAgent, bounded private daemon diagnostics with log rotation, immutable private status snapshots, and recoverable serialized release installation. New in 0.5.0 are a paged daemon replay operation, an optional agents filter on daemon subscribe streams, a send --message-stdin input mode, a dsh target in the checkout skill installer, and the native dsh plugin @shendeguize/dsh-agent-sidecar.

<a id="support-matrix"></a>

Support matrix

Environment	Support boundary
macOS	Primary platform and full quality-gate target. Local observation, remote monitoring, the daemon and HTTP panel, deterministic zipapps, experimental local send, and the user LaunchAgent are supported.
Linux	Portable observation, remote monitoring, daemon/HTTP, TUI, and packaging paths are exercised in CI. The macOS LaunchAgent is unavailable, and experimental send fails closed before execution because its required Darwin kqueue descendant containment is unavailable. Linux support is best-effort where agent-owned persistence formats or desktop integrations differ.
Windows	Unsupported. The current runtime and security contracts require POSIX permissions, file locking, process groups, Unix sockets, and related primitives.
Python	Python 3.9 or newer is required locally and on SSH targets. CI exercises Python 3.9 and 3.13; Agent Sidecar has zero runtime Python dependencies.

…