Claude Code Cross-Session Messaging: How to Coordinate Parallel Agents Safely

Claude Code cross-session messaging is a way for separate Claude Code sessions to exchange the decision, change summary, test result, or question that the next task needs. It is most useful when teams keep ownership boundaries, review, and permissions intact.

Anthropic added cross-session SendMessage and ListAgents in Claude Code 2.1.224 for macOS and Linux. The feature lets one session discover and message another session, including across your machines. The important distinction is that a message is a handoff, not shared ownership of every conversation, file, or permission. Anthropic's Claude Code changelog is the primary source for the release details and current behavior.

Key takeaways

• ListAgents identifies Claude Code sessions that can receive a message.
• SendMessage passes a focused handoff such as a change summary, a dependency, a test result, or a question.
• The feature does not turn separate sessions into one shared workspace. Each session still needs to inspect its own repository state and follow its own approval flow.
• Parallel development works best when sessions own different modules or tasks, and a human retains responsibility for review and release decisions.

What is Claude Code cross-session messaging?

Cross-session messaging connects independent Claude Code sessions without requiring a person to copy a status update from one terminal into another. In the 2.1.224 release notes, Anthropic describes ListAgents for discovering sessions and cross-session SendMessage for sending messages to them. The same release notes say the feature is available on macOS and Linux. Read the release entry.

That makes a practical difference when two tasks are related but should remain isolated. One session can inspect a legacy module while another implements a bounded change. The research session can send the findings that matter without forcing the implementation session to replay a long chat transcript.

ListAgents and SendMessage have different jobs

ListAgents finds the right recipient

ListAgents is the discovery step. Use it to identify the session that owns a task before sending a handoff. In practice, the team should still name the task, the repository area, and the owner outside the tool. A list of available sessions is not a substitute for clear work assignment.

SendMessage carries the handoff

SendMessage is for the small amount of context the recipient needs next. The best message is not a stream of consciousness. It states what changed, why it changed, what was verified, and what still needs a decision.

This is especially helpful when a build, migration, or test suite takes a long time. The implementation session can continue with an independent task while a verification session reports the result in a structured handoff.

What cross-session messaging does not share

The feature should not be treated as collaborative editing or an automatic permissions bridge. The release notes describe a session-discovery and message-delivery mechanism. They do not establish that a recipient automatically inherits another session's conversation history, open files, or prior approvals. Anthropic's changelog also notes settings for cross-session inbound messages and expiry when a recipient runs with bypassed permissions.

A safe operating assumption is simple: every recipient should verify the working tree, scope, commands, and access it needs before acting on a message.

A handoff template for parallel development

Use a consistent format so another session or reviewer can act without reconstructing the whole task.

1. Owner and task: Say whether the recipient is researching, implementing, testing, or reviewing.
2. Scope: Name the repository area, module, issue, or files that are in scope.
3. Completed work: Summarize the verified facts, changes, and tests already run.
4. Open questions: Identify uncertainty, compatibility risks, or decisions that need a human owner.
5. Next action: State what the recipient should do and how completion will be checked.

For example:

Owner: verification. Scope: authentication-flow changes. The implementation updated three files and unit tests passed. Open question: invite-link compatibility has not been checked. Next action: test invite, sign-in, and role-change flows in staging. Reply with the result and reproducible steps for any failure.

The format is short enough to be useful but complete enough for the recipient to check the right conditions.

Four useful patterns

1. Split investigation from implementation

Have one session map the affected modules, dependencies, and tests. Have a second session make a narrowly scoped implementation. The investigation handoff should include the files inspected and the uncertainty left behind, not just a conclusion.

2. Separate long-running verification

A validation session can run a slow build or test suite while another session continues with independent work. Send the command, outcome, failed location if any, reproduction conditions, and the next hypothesis.

3. Hand off a specification change

A specification handoff should include the business reason, affected API or screen, compatibility concern, and test cases. That gives the next session a boundary instead of a vague request to "update the feature."

4. Ask for a pre-review check

A separate session can read a change set for missing tests, configuration changes, and permission implications. It can surface questions before a human code reviewer takes the final decision.

Permission and review still matter

Cross-session communication should not widen access. Anthropic's 2.1.224 release notes include crossSessionInbound and dialogExpiry settings so messages sent to sessions with bypassed permissions can be held for approval. The 2.1.225 notes also include fixes for cross-session messages that could remain parked in headless sessions or during startup. Check the current changelog before configuring the feature.

Keep the following controls in place:

• Preserve least-privilege access. Receiving a message is not a reason to grant file, network, production, or secret access.
• Keep existing approval gates for production changes, external sends, and sensitive data.
• Inspect the target repository and proposed commands before execution. A message can describe a task, but it should not bypass review.
• Update Claude Code and confirm the behavior of queued messages and delivery status in the version you use.

Can two sessions edit the same file?

It is safer to avoid it. Two sessions modifying the same file at once can create conflicts and hide review-relevant changes. Divide work by directory, module, or responsibility, then assign one owner to integrate and review the combined result.

The larger principle is that parallelism should reduce waiting, not make the source of truth unclear.

Frequently asked questions

Does cross-session messaging share the full conversation or files?

Treat it as text-based coordination, not automatic history or file sharing. Send the essential context explicitly, then verify the recipient's current repository state before it acts. Anthropic's release notes describe session discovery and messaging, rather than shared conversations or collaborative editing.

Does it work on Windows?

The 2.1.224 changelog entry describes cross-session SendMessage for macOS and Linux. Support can change, so confirm the current release notes before depending on it in a team workflow. See the source.

Does it replace code review?

No. A second agent can identify gaps or summarize a change, but human owners should still approve the specification, security-sensitive access, and production release.

From individual agents to a shared operating context

As teams run more than one coding agent, the hard problem becomes less about starting tasks and more about preserving the decision trail around them. A useful system keeps handoffs, review context, approvals, and institutional knowledge visible to the team.

Kylon is an AI-native workspace where people and agents work in the same channels. Teams can keep agents, shared context, permissions, and approval points together, rather than relying on handoffs scattered across isolated terminals.

For related reading, see How to choose an AI-native workspace in 2026 and Kylon vs Claude Tag.