English · 中文
inter-session
Agent-to-agent messaging for Claude Code sessions on the same machine. Each
Claude Code session connects to a local WebSocket bus and can send messages
to other connected sessions; incoming messages are delivered to the
receiving agent as prompts and acted on as instructions by default.
One session can drive another.
Implemented using Claude Code's Monitor tool: ms-level delivery latency,
no active polling, and no token or performance cost when there are no messages.
Does NOT require claude.ai login. No configuration needed.
Localhost only and Unix-only (macOS, Linux, WSL2) for now.
How does this compare to subagents and agent teams?
Claude Code already has two concurrency primitives:
subagents (the Agent
tool — spawn a worker inside your session for a focused subtask) and
agent teams (a team of
independent CC sessions launched together for one task). inter-session
is a different axis: it connects the long-lived Claude Code sessions
you've already opened across terminals and projects, so they can
message each other.
| Aspect | Subagent | Agent team | inter-session |
|---|
| Context | Own window; results return to the caller | Own window; fully independent | Own window; fully independent; each session keeps its user-driven conversation |
| Communication | Reports back to the main agent only | Teammates message each other directly | Peer-to-peer across every connected session |
| Coordination | Main agent manages all work | Shared task list with self-coordination | Ad-hoc — each session applies its own reaction policy |
| Lifecycle | Spawned per task; exits when done | Spawned by lead for one task | Not spawned — connects sessions you already opened |
| Driven by | Parent agent (programmatic) | Lead agent + shared task list | You — each session is yours; the bus only lets them message |
| Best for | Focused tasks where only the result matters | Complex work needing teammate discussion in one task | Cross-session coordination across long-running, unrelated work |
| Token cost | Lower: results summarized back to the main context | Higher: each teammate is a separate Claude instance | Adds only per-message overhead to sessions you're already running |
Use a subagent when you need a quick, focused worker that returns
a summary. Your main conversation stays clean.
Use an agent team when teammates need to share findings, challenge
each other, and coordinate inside one task — best for parallel research
with competing hypotheses, parallel code review, and feature work where
each teammate owns a separate piece.
Use inter-session when you have multiple Claude Code sessions
running for unrelated long-lived work and want one to drive another —
e.g. delegating a bug fix from one project's session to another's;
running iterative loops where each side's context grows in value
across many rounds; or letting two sessions with hours of accumulated
conversation history share findings or coordinate without restarting
either side. Each session keeps its own project context, conversation
history, and tool permissions; the bus just routes messages between
them.
Transition point: if you find yourself copy-pasting between Claude
Code sessions you already have open, or if your agent-team task spans
multiple projects you're working in separately, inter-session is the
natural fit — your existing sessions become the team.
Prerequisites
- Python ≥ 3.10
- Claude Code ≥ 2.1.105
Install
In any Claude Code session:
/plugin marketplace add https://github.com/yilunzhang/claude-code-inter-session
/plugin install inter-session
Then start using it:
/inter-session:inter-session
Claude handles runtime dependency install automatically on first use — no
extra setup needed.
By default the monitor starts lazily — it spins up the first time
you invoke any /inter-session:inter-session command in a given Claude
Code session. To switch to always-on auto-start at every session open,
run /inter-session:inter-session auto-start on (then /reload-plugins).
Examples
