session-peer

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

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

Ask a session on another machine to review a change, report progress, or pick up a task. For example, ask api-worker on SSH host worker to review a change. session-peer uses native agent inboxes and queues; the receiving agent controls how incoming messages are handled.

Quick start

Python 3.9+. The core CLI has no third-party Python dependencies.

pipx install session-peer
# Alternative: uv tool install session-peer

session-peer list
session-peer list --host worker

Send your first message

The names and UUID below are fictional examples. Discover your destination first, then replace them with a session from its listing.

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"

Replace worker with your SSH host or alias, api-worker with a discovered session name, and the example UUID with the full ID from the destination's listing. The destination needs Python and the target agent's inbox or queue; session-peer itself need not be installed there for SSH list/send.

posted / queued means submitted, not read or completed. Saved Codex threads may be inactive. Ask for an explicit reply when completion matters.

Common tasks

Installation options

Install the runtime with pipx or uv, or run python -m pip install session-peer in an activated virtual environment. Install the agent skill separately from its dedicated repository:

npx -y skills@latest add abruption/session-peer-skill \
  --skill session-peer --global \
  --agent claude-code --agent codex --agent antigravity \
  --copy --yes

For air-gapped or SSH deployment, the POSIX ./install.sh [--host worker] path continues to bundle a compatibility copy of the skill. On native Windows use a Python package manager for the runtime. Optional MCP tools require Python 3.10+ and session-peer[mcp]. See installation details.

Let an AI assistant help

If you would rather describe the goal than work through every document, give your coding agent the AI-assisted setup and operation guide. It provides a reusable request, approval and secret-handling boundaries, validation steps, and a completion-report format. You remain in control of account changes, public exposure, payments, reboots, merges, releases, and publication.

Optional 1.0 beta features

The opt-in 1.0.0b1 prerelease advances the authenticated public relay and keeps the v0.9 experimental Antigravity bridge. Unfiltered list also includes live registered bridges. Paired devices / encrypted relay require Unix, Python 3.11+ and the [relay] extra. Device identities are pinned and targets need explicit authorization on the receiving endpoint. The blind WSS relay cannot decrypt application messages; hosted-service availability remains separate from the package. Install the beta explicitly with pipx install 'session-peer[relay]==1.0.0b1'; normal upgrades do not select prereleases. Start with the session-peer project page and the paired-device guide above. Beta publication does not imply long-term stability. Ordinary local/SSH commands remain dependency-free.

Before you send

• Use the correct destination account and agent home; for custom Codex homes, pass the listed codexHome path with --codex-home. SSH access and receiver permissions still apply.
• Plain sends do not activate inactive sessions. Explicit wake can start a turn and consume usage; MCP requires separate wake permission.
• Redact secrets, conversation text, session IDs, and personal paths before sharing diagnostics.

Documentation

• Project site: a curated overview, quick start, and documentation entry point.
• Repository documentation map: user, integration, operator, development, and historical references.
• CLI reference: commands, JSON, environment variables, updates, limits, and validation history.
• Diagnostics and replies · Multiple Codex homes
• Moving from cc-peer · Releases
• Adapter development · Release process

The README and detailed documentation are available in English, Korean, Japanese, and Simplified Chinese. English is canonical; CI checks that translated files, commands, requirements, and behavior stay aligned. These translations do not change the CLI output language.

Support and security

GitHub Issues for bugs and features; private reporting for vulnerabilities (security policy). For private questions or an alternative security contact, email support@abruption.dev with [session-peer] in the subject. Support is best effort. Emails are reviewed manually and never automatically published as issues. English and Korean reports are welcome.

MIT license.