Claude Code Message

English | 简体中文

Disclaimer: Claude Code Message is an unofficial community project, not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic, PBC. It relies on undocumented internal behaviors that may change across Claude Code versions.

A group chat for Claude Code sessions, across machines.

• Sessions on your other machines appear as ordinary peers named
  <machine>-<session>. Built-in SendMessage reaches them, and replies come
  back the same way.
• Every session registers what it is working on. The registration comes
  from the user's latest prompt, and agents can update it. New sessions get the
  roster at startup, so an agent can decide whom to @.
• ccm broadcast messages everyone; you can narrow it by machine or name.
• Every join, leave, task change, message, relay and broadcast goes into an
  audit log on each machine.
• It is one stdlib-only Python file plus a Claude Code plugin (a skill and
  hooks). The link runs over SSH, so there is no server and no open port.
• Platform Support: macOS (Darwin) and Linux (POSIX). Windows is supported via WSL (native Windows unsupported due to POSIX socket and path requirements).

 laptop (hub)                                server (Linux)
 ┌────────────┐ SendMessage ┌──────────┐     ┌──────────┐   inbox   ┌────────────┐
 │ web-ui     │ ──────────▶ │ mirror   │ ssh │ ccm      │ ────────▶ │ api        │
 │            │ ◀────────── │ server-  │ ──▶ │ serve    │ ◀──────── │            │
 └────────────┘   reply     │ api      │ ◀── │ mirror   │   reply   └────────────┘
                            └──────────┘     │ laptop-… │
                                             └──────────┘

Quick start

# on the machine you work from (the hub)
git clone https://github.com/leecaa/claude-code-message.git ~/src/claude-code-message
python3 ~/src/claude-code-message/bin/ccm init --label laptop

# Ensure ~/.local/bin is in your PATH (e.g. export PATH="$HOME/.local/bin:$PATH")
# once per other machine; it only needs ssh + python3 + Claude Code, pair installs the rest
ccm pair server --remote-label server
ccm doctor

Note: Keep ~/src/claude-code-message in place (or re-run ccm init if moved), as ccm init registers this directory as the plugin source.

Then, in any Claude Code session: "ask whoever is working on the API whether
they changed the auth endpoints". The agent reads the roster and @s the right
member.

Receipts and bounded resend

Both read_receipts and retry_enabled default to true. They are independent:

ccm config set-read-receipts false
ccm config set-retry false
ccm config set-reliability '{"message_ttl":3600,"max_attempts":128}'
ccm receipts --json                 # sender-side facts, never message bodies
ccm receipts --inbox --json         # only the current owned receiving SID
ccm read-ack DELIVERY_ID            # explicit receiving-session declaration
ccm retry DELIVERY_ID               # only a safely pending original message
ccm retry DELIVERY_ID --inbox       # safe pre-write receiver retry

queued means a private SQLite transaction accepted the message. peer_received
means the paired CCM endpoint committed its inbox and dedup record. Neither means
Claude read it. socket_written_unconfirmed is a native socket handoff, not
queue admission. Native delivered is admission, not reading. The only read-style
fact is receiver_acknowledged: the actual ancestor-owned target session
explicitly declares it after a handoff. Model consumption, human reading and
human approval remain unknown; hooks, queries, idle and Stop never manufacture
that declaration.

New paired endpoints replay the same delivery ID with exponential backoff and
persistent receiver dedup. The defaults are 2–300 seconds, ±20% jitter, a
10-second ACK wait, 512 attempts and a fixed 24-hour TTL. A peer database identity
change pauses old queues. Targets are frozen SIDs, not names; sid:SID can address
a previously observed unique offline route. Broadcast accepts its frozen targets
in one transaction. No live worker means no automatic progress: the existing
ccm up daemon also supports local-only recovery with no peers.

An uncertain native handoff is deliberately not injected again. A crash after
dispatch reservation, partial write or post-write commit failure remains
handoff_unknown; this trades liveness for avoiding duplicate work. A legacy
peer is attempted once and remains unconfirmed, even after a later upgrade.
There is no end-to-end exactly-once or guaranteed eventual delivery claim.
Disabling retry stops new background timer/reconnect/restart attempts, while explicit
safe commands get one durable opportunity. Duplicate ingress never grants another
native handoff; reactive peer_received transport responses use persistent attempts,
lease and backoff even with retry off, not an unmetered ACK exception. First handoff
control facts and the read declaration's generation dependency remain independent
of automatic retry. Held/refused/expired messages are not unlocked.
Disabling read receipts on the receiver suppresses future disclosure, including
pending events; re-enabling does not replay suppressed declarations. IO already
started cannot be withdrawn.

The queue stores raw message bodies, unlike redacted audit previews: keep its
0700 directory and 0600 database private. Active bodies are bounded to 10,000 /
64 MiB; the total store/journal budget is 256 MiB with ACK headroom. Tombstones
cover the immutable expiry plus clock-skew and retention margins. Clock rollback,
corrupt configuration and incompatible schemas fail closed. Do not remove or
restore only part of reliability state to force a resend. See the
architecture and security policy.

Message trust and first delivery

For an agent's ccm send / ccm broadcast, hooks capture its current permission
mode before the first send and subsequent sends. Native SendMessage declarations
are preserved. CCM does not label unknown senders as bypass or change
crossSessionInbound; matching classes deliver under Claude's default policy,
while mismatched/unknown classes may still require approval.

If you see “unidentified session” or “did not attest its permission mode”, see
Message identity and troubleshooting, including upgrade
steps and the limits of “trusted Claude” on a shared OS account.

Docs

• docs/ARCHITECTURE.md: design, lifecycles, audit
  schema, security (single source of truth)
• docs/AGENT-BRIDGE.md: Agent Bridge architecture for
  Google Antigravity, OpenAI Codex, and external autonomous agents
• skills/claude-code-message/references/sop.md:
  procedures for pairing, upgrading, recovery and uninstalling
• docs/PROTOCOL.md: the Claude Code peer protocol this
  builds on
• SECURITY.md: security architecture, threat model, and vulnerability reporting
• 简体中文: README.zh-CN.md,
  docs/i18n/zh-CN/AGENT-BRIDGE.md,
  docs/i18n/zh-CN/SOP.md

Security in one paragraph

SSH carries and authenticates the link. An inbox accepts only frames that
carry its token, which is readable only by your OS user; this is the same
rule as native peers. The permission mode of the sender is passed through, so a
session in a different mode holds bridged messages for its user's approval,
exactly as it does locally. Any member may message any member; the audit log
makes that accountable. See SECURITY.md for full details.

Caveats

Claude Code Message relies on Claude Code's internal peer protocol, tested on
2.1.282. Keep all machines on the same Claude Code version; ccm doctor
warns you when they differ. Routing is single-hop: pair machines directly if
they need to see each other.

Test

python3 -m unittest discover -s tests -v

Community & Acknowledgements

• Discussion & Support: LINUX DO

License: MIT