Metadata-Version: 2.5
Name: session-peer
Version: 1.3.1
Summary: Discover and message Claude Code, Codex, and Antigravity sessions locally, over SSH, through MCP, or via an optional end-to-end encrypted relay.
Project-URL: Homepage, https://github.com/abruption/session-peer
Project-URL: Repository, https://github.com/abruption/session-peer
Project-URL: Issues, https://github.com/abruption/session-peer/issues
Author-email: YEONGUK LEE <hashcode@kakao.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,cli,codex,cross-session,messaging,ssh
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.12; (python_version >= '3.10') and extra == 'mcp'
Provides-Extra: relay
Requires-Dist: cryptography<51,>=50.0.1; (python_version >= '3.11') and extra == 'relay'
Requires-Dist: websockets<18,>=17.1; (python_version >= '3.11') and extra == 'relay'
Description-Content-Type: text/markdown

<div align="center">

# session-peer

[![PyPI](https://img.shields.io/pypi/v/session-peer)](https://pypi.org/project/session-peer/)
[![PyPI total downloads](https://api.pepy.tech/badge/session-peer)](https://pepy.tech/projects/session-peer)
[![CI](https://github.com/abruption/session-peer/actions/workflows/ci.yml/badge.svg)](https://github.com/abruption/session-peer/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abruption/session-peer/blob/main/LICENSE)

**English** · [한국어](https://github.com/abruption/session-peer/blob/main/README.ko.md) · [日本語](https://github.com/abruption/session-peer/blob/main/README.ja.md) · [简体中文](https://github.com/abruption/session-peer/blob/main/README.zh-CN.md)

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

</div>

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.

<a id="see-it-in-action"></a>

## Demo

![Codex sends a request to Claude Code and receives an explicit ACK](https://raw.githubusercontent.com/abruption/session-peer/main/docs/assets/session-peer-live-codex-claude.gif)

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

<a id="installation-options"></a>

### Install

Python 3.9+. The core local/SSH CLI has no third-party Python dependencies.
Source version: **1.3.1**. At the 2026-10-27 preparation checkpoint, the last verified published stable release was **1.3.0**. See the [maintenance release notes](docs/releases/v1.3.1.md) for the Control source dependency fix and the compatibility skill asset in the GitHub release. Neither component is included in the Python wheel or sdist.

Version 1.3.0 adds delivery explanations, local/SSH route presets and recipient addresses, bounded handoff observation, trusted SSH configuration, pairing links and per-version notice preferences. See the [release scope and verification gates](docs/releases/v1.3.0.md) for supported combinations and limits. Package publication and operational deployment are separate.

Check [GitHub Releases](https://github.com/abruption/session-peer/releases) and [PyPI](https://pypi.org/project/session-peer/) for available versions; a source version alone does not establish package availability.

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](docs/handoff-runtime.md) for the shipped scope and remaining acceptance gates.

```bash
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](https://github.com/abruption/session-peer/blob/main/docs/cli-reference.md#install).

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:

```bash
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](https://github.com/abruption/session-peer-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:

```bash
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](https://github.com/abruption/session-peer/blob/main/docs/cli-reference.md#updating).

<a id="documentation"></a>

## Docs

- [Documentation map](https://github.com/abruption/session-peer/blob/main/docs/README.md): user, integration, operator, and development guides.
- [CLI reference](https://github.com/abruption/session-peer/blob/main/docs/cli-reference.md): options, JSON, installation variants, and migration.
- [Diagnostics and replies](https://github.com/abruption/session-peer/blob/main/docs/diagnostics.md) · [Multiple Codex homes](https://github.com/abruption/session-peer/blob/main/docs/multi-home-list.md).
- [AI-assisted setup](https://github.com/abruption/session-peer/blob/main/docs/ai-assistant-guide.md) · [Project site](https://abruption.dev/projects/session-peer/) · [Release notes](https://github.com/abruption/session-peer/releases).
- [Release process](https://github.com/abruption/session-peer/blob/main/RELEASING.md).

[Paired devices / encrypted Relay](https://github.com/abruption/session-peer/blob/main/docs/paired-devices.md)
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](https://github.com/abruption/session-peer/blob/main/docs/mcp.md) requires Python 3.10+
and `session-peer[mcp]`; MCP wake requires both `send` and `wake` capabilities.
[Wake](https://github.com/abruption/session-peer/blob/main/docs/wake.md) runs only when explicitly requested
and can start a turn, consume usage, and change project files.
The [Antigravity bridge](https://github.com/abruption/session-peer/blob/main/docs/antigravity.md) remains experimental.

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

## License

[MIT](https://github.com/abruption/session-peer/blob/main/LICENSE).

## Support and security

Use [GitHub Issues](https://github.com/abruption/session-peer/issues/new/choose) for bugs and features.
Report vulnerabilities [privately](https://github.com/abruption/session-peer/security/advisories/new)
under the [security policy](https://github.com/abruption/session-peer/blob/main/SECURITY.md), 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](mailto: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.
