xsm-agent-message-channel.md

All posts
raw .md

AI / Agent

xsm: A Message Channel for Agent Collaboration

Preserving existing work environments and agent autonomy while organizing collaboration that people can understand and intervene in.

Running several Claude Code or Codex sessions lets you split API implementation and interface development across them. That also creates coordination work: keeping the API contract aligned, getting one session's findings to another, and checking what has actually finished against the overall plan. As the number of sessions grows, a person spends more time connecting them.

I wanted to delegate work to agents while still understanding who was doing what and what evidence supported a finished result. That meant preserving the existing work environment and each agent's autonomy, while keeping the ability to read a session's context and give it a direct instruction when needed. I built xsm, Cross-Session Messaging[1] to connect those sessions.

In Separating the Worker from the Tool, I argued that specialized software should make its capabilities and usage knowledge available to the worker a customer has chosen. xsm applies the same idea to collaboration: an existing agent learns a communication tool and uses it to carry work forward with other agents.

Keep execution and communication responsibilities clear

Claude Code and Codex provide an execution environment in which agents read and edit files, invoke tools, and use the results to make their next decision. xsm connects sessions within those environments. It provides ways to find a collaborator, send a request, read incoming messages, recover an answer, and maintain state that a team can consult.

Connecting existing sessions lets you keep using the work environment you have already built. Agents retain their tools, skills, and working context, while people keep familiar controls and approval procedures. New tools and capabilities adopted in the runtime can become part of that collaboration too.

You describe the work in your current session. The agent reads xsm's skill and usage instructions, then calls the relevant tools. Agents decide how to assign responsibilities and order the work in light of the goal and the situation. The design aims to reduce the work of learning another orchestration language and translating the task into it.

Independent Claude Code and Codex sessions exchange messages and shared state through xsm's logical communication interface
Figure 1. Execution and conversational context remain in each existing runtime. The xsm box marks a communication boundary; it does not represent a separate agent execution server.

The README states the philosophy this way:

All you need is a message channel. The rest is done by agents.

To delegate work to agents, the communication tool needs to report outcomes clearly. It must identify the recipient, distinguish delivery to the recipient's runtime from earlier stages, and make a returned answer recoverable. The agent reads that evidence and decides what to do next.

Teams, boards, worker creation, and handover make that connection usable for ongoing collaboration. They keep track of who is participating, the shared record, and the state of execution and replies. Agents and the user still decide how to divide the work, change priorities, and accept results.

Local Claude Code and Codex connections use their runtimes' native delivery paths. They do not require a shared local xsm daemon to be kept running. Additional runtimes use helpers tied to the host's lifetime, and communication between machines has an opt-in P2P service. Separating communication also means being explicit about who runs each connection and what scope it has.

Describe the organization in natural language

Consider building a notification feature. You have sessions for the API, interface, and verification, plus a session responsible for the overall plan. A request to the lead might look like this:

Lead the development of this notification feature. Maintain the goal, completion criteria, plan, and progress. Assign workers to the API, UI, and verification, and tell each worker its responsibilities and reporting destination. Let workers coordinate directly when needed, and keep shared decisions and progress on the team board.

This specifies who owns the plan, which responsibilities are needed, and who is expected to coordinate directly. Those relationships can change with the work. Peers can review one another's results, or equal members can debate a design under an agreed decision rule. I see no reason for xsm to prescribe a single organization.

Describing a role does not configure the connection. Choosing models and sessions, registering a team, and allowing the necessary communication scope happen through the relevant tools. A natural-language assignment does not itself constitute user approval. Agents interpret the working arrangement; xsm connects their collaboration within the allowed scope.

Give long-running work a lead who owns the plan

For substantial, long-running parallel development, I strongly recommend a lead using a strong model to manage planning and progress, with a shallow layer of workers at the same creation depth. This is also the default recommendation in the organization guide[2].

A possible allocation puts a Fable- or Astra-class model in charge of the plan, with Opus- or Sol-class models doing the main implementation and verification. Haiku Max- or Luna Max-class supporting workers can handle bounded investigation or repeated checks. These are examples of role allocation. Models and reasoning settings are chosen in the runtime; xsm does not select them automatically.

A Fable lead coordinates API, UI, and verification workers at the same depth; workers collaborate directly and consult a shared board
Figure 2. Primary and supporting workers differ in responsibility and can sit at the same creation depth. Model names illustrate an allocation. Goals and current decisions are recorded on the shared board.

The lead checks the overall work against consistent criteria. For notifications, that means deciding what must be complete from creation through listing and marking an item as read, and how those behaviors will be checked. As reports arrive, the lead compares them with those criteria, separates finished work from remaining work, and updates the order of tasks when dependencies block progress.

The lead summarizes progress, decisions that need a person's attention, and the evidence behind them. People can follow those reports and, when details matter, read the relevant worker's session and give it a direct instruction. For example, if a user directly instructs the API worker to change the notification policy, the worker reports the relevant change to the lead, who then realigns the API and UI plans.

The plan also needs to be recorded outside conversational context. Goals, completion criteria, assignments, current decisions, and verification evidence belong in the board and work artifacts. If a session is replaced or hands work over, the next session should be able to read those records and continue. The arrangement uses a strong model for planning while keeping decisions and verification evidence in external records.

A primary worker can ask a supporting worker for help without increasing creation depth. The API worker might request a code investigation or ask verification for reproduction conditions. The lead resolves conflicts in ownership or priority.

Deeper chains of workers increase the cost of passing along context, collecting results, and tracking responsibilities and progress. They also make it harder for a person to trace how a decision led to a result. If a faulty premise enters the process, it should be possible to trace who received it, which results it affected, and what needs checking again. I recommend keeping creation depth shallow so those relationships remain understandable.

A task that ends with a single request and result can use the harness's subagents. A collaborator that needs independent context and repeated exchanges is better served by a persistent worker with its own address and progress state.

Separate direct requests from shared state

Suppose the notification API worker wants to change the representation of read status. It can send the proposed change to the UI worker and ask about the impact. The UI worker replies with its requirements, while the verification worker checks the case where marking an item as read overlaps with a reconnection. These requests and responses travel as DMs to the relevant recipients.

Agreements that apply to the whole team go on the board. The current API contract, ownership, blockers, and verification results should remain available to a session joining later. When a changed decision requires action, a DM can point to the relevant board item and ask for a specific response. The board holds current shared state; DMs carry requests for action and answers.

This allows workers to coordinate details without making the lead relay every exchange. Changes that affect the overall plan still come back to the lead. A shared board does not imply broadcasting every message or automatically reading another team's state. Recipients and the allowed communication scope must remain clear.

The communication record also needs clear interpretation. A stored message, delivery to a runtime, an acknowledgement after reading, and an actual reply are different events. Even a reply does not establish that the assigned work is complete. The lead checks results and verification evidence against the agreed criteria. The board does not independently estimate how much development is complete or treat an incoming reply as proof that a task is complete.

Let independent teams share a coordination team

A larger service may have teams responsible for storage or deployment as well as the API and interface. Each can maintain its own lead, workers, board, and plan. This reduces the need to bring every implementation detail into one lead's conversational context.

Teams share information that affects one another: API contracts, data models, dependencies, and integration timing. Their leads can belong both to their working team and to a separate coordination team. Agreements made through that team's DMs and board are then reflected in each working team's plan.

Independent API and UI teams have their same leads participate in an overlapping coordination team
Figure 3. The coordination team contains the leads of the working teams. The same sessions have multiple memberships and coordinate shared contracts and dependencies. This arrangement does not require an additional commanding agent.

The leads can deliberate as peers in the coordination team. They share what is relevant and each updates the responsibilities and schedule of their own team. As a project grows, this arrangement aims to keep individual team responsibilities and cross-team agreements understandable.

The scope of delegation and operational responsibility

When delegating more work, I think we also need to consider whether people can understand and verify the results. Even with extensive messages and logs, a person may struggle to follow which decision produced a particular outcome. I recommend this shallow organization and shared records for xsm when people can still follow ownership and the evidence behind decisions.

Running many workers unattended for long periods, or centrally managing work for several people, can make authorization history, formal task states, automatic recovery, deployment, and auditing central requirements. In that setting, infrastructure with clear responsibility for those functions becomes important. The appropriate arrangement depends on the execution, verification, and operational requirements of the work.

Connecting xsm to an existing operations tool also requires deciding who owns worker creation and termination, retries, and completion judgments. If several tools independently manage the same execution, responsibility and state can be duplicated. Choosing a tool is also a decision about where those operational responsibilities belong.

Start from the agent you already use

The interactive replay[3] shows this arrangement through team setup, direct collaboration, plan updates, and coordination between teams. It is a scripted illustration of the collaboration, not a recording of a development project or a performance measurement. Each scene links to documentation for the same topic.

Version 0.6.0 centers on Claude Code and Codex, and also provides experimental connections for Pi, OpenCode, Hermes, and OpenClaw. Wake behavior, question interfaces, and gateway behavior differ across the additional runtimes. The runtime guide[4] describes connection methods and the supported scope.

If you use Claude Code or Codex, you can start by sending the current session this request:

text
Install xsm from https://github.com/ysys143/xsm for Claude Code and Codex on this machine.
Verify the installation and tell me if any steps still require my direct action.

After installation and the necessary approval steps, ask the agent to find a collaborator and explain the work you want to hand over. Installation and first collaboration[5] covers the starting procedure.

Existing runtimes will keep improving how agents execute work and use tools. I want xsm to benefit from those improvements while providing a communication base for delegating more work that people can still assess. The organization built on that base, and the way it works, remain the user's decisions.

References · 5

  1. [1] xsm, Cross-Session Messaging — github.com
  2. [2] organization guide — github.com
  3. [3] interactive replay — ysys143.github.io
  4. [4] runtime guide — ysys143.github.io
  5. [5] Installation and first collaboration — ysys143.github.io