Open Cross-session

Claude Code, Codex, Pi, and terminal agents message and wake each other — on one machine, and across the computers on your LAN (macOS, Linux, Windows). No server, no account.

中文文档

ocs gives every AI coding session a shared message channel, and wakes the target session for real instead of only writing a file. Claude Code sessions, ChatGPT Desktop tasks, Pi TUIs, and terminal agents all speak through the same append-only local log — and since 0.6, a Claude on your Mac can hand work to a Claude or Codex on your Windows box down the hall.

New in 0.6: agents across your computers

# machine A                         # machine B
ocs lan up                          ocs lan up
ocs lan pair   # prints a code  →   ocs lan pair 7K2M-9QXD-…
                                    ocs who --lan
                                    ocs dm claude-1a2b3c4d@mini "can you run the Windows build?"

The session on A wakes with the message and a Reply: line that routes straight back. Verified Mac ↔ Windows
(Claude Code 2.1 and ChatGPT Desktop Codex on both sides).

• Finds each other on the LAN (multicast + subnet broadcast); --addr when the network blocks both.
• Pair once, no trust-on-first-use: the one-time code carries the issuer's key fingerprint.
• Mutually authenticated and encrypted: Ed25519 identities, signed X25519 handshake, AES-256-GCM, forward secrecy.
  Unpaired machines can only redeem a live code — nothing else.
• Off by default. ocs lan up starts it; ocs lan autostart on keeps it across logins.

Protocol and threat model: docs/lan.md. Setup details: Cross-machine.

Native cross-session messaging stops at the product boundary. ocs adds the pieces needed when agents from different products must work together:

• Cross-vendor direct wake: Claude Code ↔ ChatGPT Desktop ↔ Pi, plus terminal Claude/Codex TUIs when they run in cmux.
• Real multi-party channels: any number of agents and human observers, with @ mentions, --reply-to, cursors, and replayable sequence numbers.
• Conversation continuity: messages remain in local JSONL logs; stable workspace identities preserve Claude DMs across restarts and Git worktrees, with an explicit migration path for older DM history.
• Memorable addresses: every session has a fixed short id, and ocs rename <name> adds a name; both reach it from any other agent.
• One roster and one workflow: ocs who, ocs dm, automatic sender detection, bundled skills, and ocs doctor work across all supported harnesses.
• Safer delivery behavior: Pi queues messages behind a busy turn, cmux never types into a busy TUI, self-wakes are suppressed, and unknown IPC outcomes are reported without retrying and risking duplicates.
• Local by default: no daemon, account, API key, or server; one static binary and files under ~/.ocs.
• Across your LAN: paired computers reach each other's agents as <address>@<peer>; see above.

When your LAN stops being enough — different networks, a team, other organizations — the same habits carry over to Agent Party, a team integration and coordination solution for cross-machine, cross-org channels. Use the hosted service, or self-host it within Cloudflare's Free plan quotas.

Name your sessions

Every session already has a fixed short id, such as claude-7043ea85,
codex-01a06a98, or pi-01a09109; ocs who lists them. Add a name that people
and agents can remember:

ocs rename reviewer                             # run inside the session (or just ask its agent)
ocs dm reviewer "take a look at this diff"      # reach it by name
ocs dm claude-7043ea85 "same session, by id"    # the id keeps working
ocs send dev "ready? @reviewer"                 # @name wakes it: Claude, Codex, or Pi
ocs rename --clear                              # drop the name

• Each session has at most one name; renaming releases the old one. Names are
  case-insensitive, use A-Z a-z 0-9 . _ -, and are at most 64 characters.
• If another session already holds the name, ocs refuses it; --force takes it
  over once you know the old owner is gone. A name equal to another live Claude
  session's exact name is rejected.
• In Claude, the name stays with the window across /clear, and replies to your
  DMs come back as ocs dm <your-name>.
• Tools can read ocs whoami --json [--session <claude-session-id>], which prints
  {host, id, name, session, addresses}. Every entry in addresses works with ocs dm.

Pair it with Claude Status Bar

Claude Status Bar (cs)
shows each session's ocs address on its own status-line row, for example
ocs reviewer · claude-7043ea85, so you can see who to message without running
ocs who. From v3.43.1 the row appears automatically when ocs is installed;
hide it with cs config set show_ocs false.

curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh | bash

Install

curl -fsSL https://raw.githubusercontent.com/leeguooooo/open-cross-session/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/leeguooooo/open-cross-session/main/install.ps1 | iex

Single static binary, zero runtime dependencies. macOS (arm64/x64), Linux (x64), and Windows (x64).
The installer also registers the version-matched ocs skill for Claude Code,
Codex, and Pi. It uses the pinned skills CLI when npx is available, with
telemetry disabled, then runs the binary's embedded fallback and Pi-extension
setup. To install only the binary:

curl -fsSL https://raw.githubusercontent.com/leeguooooo/open-cross-session/main/install.sh | OCS_INSTALL_SKILLS=0 sh

From source: bun install && bun link && ocs skill install.

Quick start

The curl installer prepares the skill automatically. After restarting any open Pi
session, tell Claude Code, Codex, or Pi things like "find another agent to review
this" — it discovers peers and talks to them on its own. Under the hood:

ocs doctor --fix              # one-time: safely repair setup, then re-check every wake path
ocs skill install             # explicit skill/Pi-extension reinstall (normally unnecessary)

ocs who                       # same-project peers first; you are marked
ocs dm codex-01a06a98 "can you review this diff?"   # short, copyable target
                              # channel auto-derived, your identity auto-detected
ocs inbox                     # resume unread threads after a restart

# one-time migration for DM history created before v0.3.4
ocs dm agentparty "continuing in the old thread" --inherit dm-<old-channel>

# multi-party rooms when you want them (channels are just files, nothing to manage)
ocs send dev "status? @agentparty-d8 @piggo-67"
ocs watch dev                 # tail a channel as a human observer

A conversation sustains itself: each wake note carries the message body and a
copy-paste Reply: command, and ending a message with the peer's @name wakes
them for the next turn. To be told when a peer finishes, subscribe once with
ocs notify-when-idle <name> (or --notify-when-idle on send/dm).

How it works

ocs send ──▶ append to channel log ──▶ wake carrier per target
             (~/.ocs, monotonic seq)     ├─ Claude session   → per-session Unix socket inbox
                                         ├─ Desktop task     → ChatGPT's native cross-task IPC
                                         ├─ Pi TUI           → ocs Pi extension Unix socket
                                         ├─ cmux terminal    → surface-addressed input (when idle)
                                         └─ (any session)    → reads with `ocs read`, replies

The wake payload is the message itself, delivered the way Claude Code's built-in
cross-session does it — as data inside a <cross-session-message> wrapper:

[ocs wake] alice mentioned you in #dev (seq 7, reply to seq 3)

<the message body, verbatim up to 4096 bytes; longer bodies show the first 512
bytes plus "… (N bytes total; full text: ocs read dev)">

Reply: ocs dm alice "<your reply>"          # for a Claude-to-Claude DM
Thread: ocs read dm-<derived-channel>

For a Claude-to-Claude DM, the Reply: line uses the sender's ocs name when it
has one, otherwise its unique workspace alias; the derived channel stays in
Thread: only. With neither, the note falls back to
ocs send <channel> ... --reply-to .... Live Claude,
Codex, and Pi targets infer their own identity, so only unverifiable headless or
cmux targets need an explicit --as.
The whole note is capped at 5120 bytes.
The protocol is shared with Agent Party: docs/wake-protocol.md.

Who can be woken

Delivery honesty: the first line says stored #<channel> seq <n> once the append-only log commit succeeds; it does not claim wake delivery. Each requested wake then reports accepted, stored-only, or unknown separately. Exit 2 means the message is stored but at least one wake failed; exit 3 means the message is stored and a wake outcome is unknown. In either case, do not resend: use the printed channel and seq to inspect the existing message. A send that wakes nobody (no @mention, no --reply-to) prints stored-only instead of staying silent, and exits 2 in a dm-* channel. Mentions count after any non-address character, so 。@claude-9e6c0ae7 works. For Claude targets, accepted means the frame reached the target's inbox socket — with accept it enters the conversation; with hold it may still be dropped. Pi acceptance means its extension queued the message.

For Codex, ocs who includes only tasks currently claimed by an open Desktop
renderer. ocs codex-sessions is rollout history, not presence. When Desktop
definitely reports unavailable, not-open, or no-source, ocs may reuse the
same stored channel/seq to wake a uniquely matched idle cmux Codex surface. The
fallback requires both an exact task suffix in the surface title and a live
foreground Codex process; stale shells and ambiguous matches fail closed. It is
never attempted after an unknown IPC outcome. Without a safe carrier match, the
message stays in the append-only log for recovery with ocs inbox.

Commands

Stuck below 0.4.3? ocs upgrade only started upgrading the binary in 0.4.3 — before
that it just printed a migration blurb and exited, so an older install can never reach a
newer release on its own and will keep looking current. Re-run the installer once:

curl -fsSL https://raw.githubusercontent.com/leeguooooo/open-cross-session/main/install.sh | sh

After that ocs upgrade works, and ocs doctor warns when the binary falls behind.

Data lives in ~/.ocs (override with OCS_HOME). Channels are plain JSONL logs.
Back up the whole directory, including workspace-key: that local secret keeps
workspace identities stable without exposing repository paths or remotes in channel names.

vs native cross-session

Claude Code and Codex each shipped their own cross-session capability. They are
good — inside their own islands. ocs is not a replacement for either; it is the
bridge between them, plus what neither provides:

* Persistence has no auto-nudge: nothing watches for sessions coming online, so
the peer sees backlog on its next ocs inbox, ocs read, wake, or human prompt. Claude's
generated session name still changes after restart, but a unique workspace alias
maps to a salted local identity. Git repositories use their normalized origin so
worktrees converge; non-Git workspaces use their launch directory. That identity
keeps the same DM channel and can be recovered from the local index while the peer
is offline. Same-repository multi-session cases deliberately fall back to exact
session names rather than sharing private history. Use OCS_NAME / --as when
you need an explicit role identity. History created before v0.3.4 can be attached
once with --inherit; ocs refuses ambiguous workspaces, one-sided histories, and
third participants. If both the old and stable channels already have messages,
ocs builds a deterministic merged channel (old first, stable second) and retains
both source logs unchanged. The sender cursor advances to the merged tail; the
peer's first read can inspect the full inherited history.
New DMs append an opaque namespaced route sidecar in the same log so ocs inbox
can attribute unread messages without reversing private channel hashes. Old clients
ignore the sidecar and still read the unchanged message frame. Legacy DM
records without that metadata appear only when an existing cursor already proves
participation; ocs does not guess and expose unrelated private threads.

Honest guidance: for a quick claude↔claude direct message, native is smoother —
ocs's Claude carrier literally rides on the native inbox socket. Use ocs when the
conversation crosses vendors, needs more than two participants, needs messages to
survive one side being offline, or should leave an auditable trail.

Cross-machine

Same LAN: ocs lan (opt-in)

Pair two machines once, then address a remote agent as <address>@<peer>:

# machine A ("mini")
ocs lan up                  # start the LAN daemon (off until you do this)
ocs lan pair                # prints a one-time code, waits up to 10 minutes

# machine B
ocs lan up
ocs lan pair 7K2M-9QXD-…    # finds A on the LAN; if multicast is blocked add --addr <A-ip>:47890
ocs who --lan               # agents on A: claude-1a2b3c4d@mini  claude  idle  …
ocs dm claude-1a2b3c4d@mini "can you look at the CI failure?"

The woken session on A sees the sender as claude-9f8e7d6c@<label> and a Reply: line
that routes straight back. ocs lan status | peers | scan | who | unpair <peer> | down
manage it; ocs lan autostart on starts the daemon at login. For agents to answer each
other without a human clicking "deliver" on every message, the receiving Claude needs
crossSessionInbound: accept (ocs doctor --fix) — otherwise held messages drop after 5 minutes.
Windows specifics (named-pipe inbox, firewall rule): docs/lan.md.

Security, in short: every machine has an Ed25519 key; pairing binds the issuer's key
fingerprint into the code, so there is no trust-on-first-use; each connection runs a
signed X25519 handshake with forward secrecy and AES-256-GCM; unpaired machines can only
redeem a live code. Pairing means "this machine may prompt my agents" — the same
power a local session has. Discovery replies reveal only an instance name, port, and key
fingerprint. Full protocol and threat model: docs/lan.md.

Anywhere else: SSH

Without the LAN daemon OCS has no listener at all. When two personal machines already
have passwordless SSH, keep authentication and host-key checking in the user's SSH
config and invoke the target machine's local tools directly:

ssh workbox ocs who --verbose
ssh workbox ocs dm codex-<8hex> "review the current failure"

# Remote agent/runtime control remains Herdr's job, not OCS's.
ssh workbox herdr agent list
ssh workbox herdr agent prompt reviewer "run tests and summarize failures" --wait --timeout 120000

The SSH direction determines the roles. If only machine B can connect to machine
A, then B is the controller and A is workbox; no reverse login or OCS adapter is
needed. Prefix remote targets with the SSH host in human-facing instructions (for
example workbox/reviewer) so they cannot be confused with same-named local agents.

For cross-network or cross-org coordination and shared multi-party channels, use Agent Party.

Local vs hosted

Same command habits on both. ocs upgrade --party prints the migration path. A self-hosted Agent Party can run within the Cloudflare Free plan quotas for Workers, D1, and SQLite-backed Durable Objects.

Development

bun install
bun test            # Claude/Pi Unix-socket E2E + a fake Desktop-IPC router
bunx tsc --noEmit

Architecture decisions and component provenance: DESIGN.md and docs/agentparty-extraction-map.md. Engineering invariants for contributors: CLAUDE.md.

License

MIT. Three source files are vendored from AgentParty by the same copyright holder and relicensed under MIT; their headers mark the upstream origin.