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.

See it in action

This 26-second recording uses live Codex and Claude Code sessions over the local transport—there is no mocked output.

1. Codex discovers the exact Claude Code session.
2. Codex posts a review request to the session's native inbox.
3. Claude Code follows the structured reply address and sends a response.
4. Codex receives the explicit reply in its own session.

sequenceDiagram
    participant C as Codex session
    participant P as session-peer CLI
    participant I as Claude Code native inbox
    participant H as Claude Code session
    C->>P: Discover exact session
    P-->>C: Return host and session ID
    C->>P: Send request and reply address
    P->>I: Write via local or SSH transport
    I-->>H: Deliver request
    H->>P: Send explicit reply
    P-->>C: Deliver to Codex native inbox

26-second looping demo: Codex sends a request to Claude Code and receives an explicit reply. A successful post confirms only the inbox write. The explicit reply at the end confirms that the receiving session consumed the request and responded.

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 v1.0 features

The stable 1.0.1 package includes authenticated public relay support and keeps the Antigravity bridge experimental. 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 stable release with pipx install 'session-peer[relay]==1.0.1'; package-managed upgrades may now select v1.0.1. Start with the session-peer project page and the paired-device guide above. Package publication does not guarantee hosted-service availability. 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.