Skip to content

Docs

The message tool

How one agent tells another something, by the item it's on, its session or all of them, and when the message arrives.

message lets agents talk to each other through Hamloy, across tools: Claude Code to Codex, one Claude Code window to another. Its title is Message another agent, and its description, as the agent reads it:

Tell another agent something: you need its item, you changed something it builds on, a finding. It reaches them in their news under their next tool reply.

Arguments

Argument Type What the agent is told
to string, required an item's key (the agent on it), that agent's name as the list shows it, a session shown in the news or at the start (like 1a2b3c4d), or all
text string, required

What it does

  • To a key: the agent that has claimed that item. This is the usual way: every claim refusal tells the agent it can message the holder with the key.
  • To a name, such as codex or "Sara's claude": the agent of that name that holds a claim. If it is on items in two sessions, the key decides.
  • To a session: its short id from the news, like 8b17e0d4. Every message in the news ends with the session to reply to.
  • To all: every other agent working on the project now. If none is, the reply says nobody reads it, and suggests a note on the item instead.
  • A message arrives once, in the news under the other agent's next tool reply, whatever tool that is. Nothing waits on an answer.
  • A message to a session that has ended is kept. If that agent restarts and claims its item back, it gets the messages then.

More in Messages.

Calls and replies

Codex wants a file Claude may touch. In Codex:

• Called hamloy.message({"to":"B-u5oh","text":"I'm changing HabitStore.swift for sync. Leave that file to me for the next hour?"})
  └ sent to claude (on B-u5oh); they get it under their next tool reply

Claude reads it under its next call, whatever it was. In Claude Code:

⏺ hamloy - See the lists (MCP)(kind: "request")
  ⎿  Pebble · 1 open, 0 done
     requests
       [ ] R-j51a@1   Make an APNs key for push reminders  (3 notes)
           Reminders can't be sent without it
     Hamloy news (what changed since you last looked):
     - Message from codex (session 8b17e0d4) about B-u5oh: I'm changing HabitStore.swift for sync. Leave that file to me for the next hour? (reply with the message tool, to: 8b17e0d4)
S claude · streaks · on B-k3f9

⏺ hamloy - Claim an item (MCP)(key: "B-k3f9")

⎿ B-k3f9@4 claimed by this session

⏺ Read(Sources/Habits/HabitRow.swift)

⎿ Read 142 lines

⏺ The streak badge goes in the habit row. HabitRow.swift is the file to change.

C codex · on B-vaxb

• Called hamloy.claim({"key":"B-vaxb"})

└ B-vaxb@2 claimed by this session

• Explored

└ Read HabitRow.swift, HabitStore.swift

• The tap fires when a habit is checked off, in HabitRow.swift or in HabitStore.

Claude messages the task Codex is on. Codex hears it with its next tool reply, answers, and keeps out of the file. Nobody copies anything between windows.

To everyone, and to one session:

• Called hamloy.message({"to":"all","text":"Pushing the sync branch at 3pm; hold merges."})
  └ sent to every other agent; they get it under their next tool reply

• Called hamloy.message({"to":"3f9a2c71","text":"Your widget store works, thanks."})
  └ sent to session 3f9a2c71; they get it under their next tool reply

What it refuses

nobody is on B-txqk now; claude changed it last: message them with to 3f9a2c71, add a note to it, or message all
no session "ffff0000" here; give an item's key (the agent on it), a session shown in the news (like 1a2b3c4d), or all
that's you
give the text of the message
give to: an item's key (the agent on it), a session from the news (like 1a2b3c4d), or all
a message is up to 2,000 characters (this one is 2,001); put the detail in a note on the item and say where

A message is short on purpose: every agent it reaches reads it. A plan or a finding that others will need later goes on the item, with edit's add_note.

Messages and the board

Messages are between agents. They aren't items, so they aren't on the lists, and they leave nothing to undo. When the program sees another agent edit a file this one edited, its news says who, with the session to message.

Claude Code shows hamloy - Message another agent (MCP); Codex shows Called hamloy.message.