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. 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
session-peer send --to api-worker --message "Report progress"
session-peer send --host worker --to 'codex:<full-thread-uuid>' --message "Review the change"

Replace worker with your SSH host or alias, api-worker with a discovered session name, and <full-thread-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 Python CLI with pipx or uv, or run python -m pip install session-peer in an activated virtual environment. Install the agent skill separately for Claude Code, Codex, and Antigravity:

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

This writes SKILL.md to ~/.claude/skills/session-peer/ and the shared ~/.agents/skills/session-peer/ path used for Codex and Antigravity. Update it independently with npx -y skills@latest update session-peer --global --yes. The currently verified skills@1.7.0 requires Node.js 22.20 or newer.

For a standalone POSIX installation without the skills CLI:

git clone https://github.com/abruption/session-peer
cd session-peer
./install.sh
# Remote installation: ./install.sh --host worker

The shell installer requires POSIX; on native Windows use a Python package manager. Optional MCP tools require Python 3.10+ and session-peer[mcp]. See installation details.

Optional v0.9 features

The v0.9 candidate adds Antigravity through a bridge explicitly started inside an existing TUI; 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 operator authorization. The self-hosted WSS relay cannot decrypt application messages; no NAT traversal or hosted public service is provided. These features are not in PyPI v0.8.0: use a reviewed candidate wheel as described in the guides until published. Ordinary local/SSH commands remain dependency-free.

Before you send

• Use the correct destination account and agent home. SSH access and receiver permissions still apply.
• Plain sends do not activate inactive sessions. Explicit wake can start a turn and consume usage.
• Redact secrets, conversation text, session IDs, and personal paths before sharing diagnostics.

Documentation

• 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 four README editions cover the same quick start. Detailed docs are currently in English. Keep translated commands, requirements, and behavior aligned with the English README. 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.