session-peer

English · 한국어 · 日本語 · 简体中文

Find and message Claude Code and Codex sessions from one CLI, locally or over SSH.

Ask another session to review a change, report progress, or pick up a task. session-peer uses native agent inboxes and queues; the receiving agent decides how to respond.

Demo

A real local request and reply using session-peer 1.0.2: Codex contacts Claude Code and receives ACK DEMO-READY. CLI and message excerpts are anonymized and re-rendered in this ~22-second animation, not a screen recording; send success alone is not an ACK.

Quick Start

Install

Python 3.9+. The core local/SSH CLI has no third-party Python dependencies. Version covered by this README: 1.1.1.

Maintenance release prepared on 2026-10-12; see the release notes. This patch updates documentation and development-only tests, not runtime behavior. Package publication and operational deployment are separate.

Development candidate 1.1.2 is unpublished; its release notes describe the #298 Claude registry and target-resolution fix. The published version above remains 1.1.1 until publication is independently verified.

Experimental handoff is opt-in: local POSIX Claude supports receipt ACKs; Codex and SSH support correlation-only submission, not ACK observation. See the handoff guide for the shipped scope and remaining acceptance gates.

pipx install session-peer
session-peer --version
session-peer list

Use uv tool install session-peer instead if you prefer uv. Native Windows, virtual-environment pip, and standalone/SSH installation variants are in the installation guide.

For SSH discovery, replace the example host worker with your host or alias. Then replace the fictional session name and full UUID with the listed destination:

session-peer list --host worker
session-peer send --to api-worker --message "Report progress"
session-peer send --host worker --to 'codex:00000000-0000-4000-8000-000000000001' --message "Review the change"

The SSH destination needs Python and the target agent's native inbox or queue, but not an installed session-peer CLI. For a custom Codex home, pass the listed codexHome with --codex-home; use --dry-run to validate without sending. Use the destination account that owns the session (--host USER@HOST). SSH access and receiver permissions still apply.

posted / queued confirms submission, not consumption, ACK, or completion. Ask for an explicit reply when needed. Ordinary sends refuse inactive Codex destinations by default and do not start them. Never automatically retry an uncertain send.

The optional agent skill is installed separately from the runtime; see the installation guide for its Skills CLI command.

Update

Use the same manager that installed the runtime:

pipx upgrade session-peer
# or: uv tool upgrade session-peer
# or, in its virtual environment: python -m pip install --upgrade session-peer

For local installations, session-peer update replaces standalone runtime files; package-managed installs receive upgrade guidance instead. It never updates agent skills: use their original installer (Skills CLI, or install.sh only for an installer-owned compatibility copy). The compatibility copy is separate from the independently released skill; existing manager-owned skills are preserved. See update details and remote limitations.

Docs

• Documentation map: user, integration, operator, and development guides.
• CLI reference: options, JSON, installation variants, and migration.
• Diagnostics and replies · Multiple Codex homes.
• AI-assisted setup · Project site · Release notes.
• Release process.

Paired devices / encrypted Relay require Unix, Python 3.11+, and session-peer[relay], with pinned identities and explicit receiver policy. Package publication does not guarantee hosted-service availability. The blind Relay cannot decrypt application message content. MCP / Codex plugin requires Python 3.10+ and session-peer[mcp]; MCP wake requires both send and wake capabilities. Wake runs only when explicitly requested and can start a turn, consume usage, and change project files. The Antigravity bridge remains experimental.

English is canonical; Korean, Japanese, and Simplified Chinese guides are kept aligned. Translations do not change the CLI output language.

License

MIT.

Support and security

Use GitHub Issues for bugs and features. Report vulnerabilities privately under the security policy, not in public issues. Redact secrets, conversation text, session IDs, and personal paths from shared diagnostics.

For private questions or an alternative security contact, email support@abruption.dev with [session-peer] in the subject. Support is best effort, with no guaranteed response time. Emails are reviewed manually, never automatically published as issues. English and Korean reports are welcome.