All pages
Many agents at once · Lesson 2.2 · 12 min
Agents that talk
The chat room, pane messages and status flags for agents working side by side.
After this lesson you can set up agents working side by side to hand work to each other, ask each other questions, and tell you what they're doing, using the project's chat room, pane messages and pane status flags.
Time: 12 minutes · Works on: macOS app. The chat_* tools are served on every platform, including the cloud workspace; the pane tools are macOS and cloud.
Agents that can't talk route everything through you
Two agents in two panes don't know about each other. When the builder finishes, it tells you. You copy its summary into the reviewer's prompt. The reviewer finds a problem and tells you. You paste that back to the builder. You're the message bus, and every handoff waits until you look.
Give them channels and the handoffs happen without you. You still read everything, because it's all written down. But you read it when you choose, not because nothing moves until you do.
Pick the channel by what the message is
TRMNLY has four places for agents to put information. Each has a job, and using the wrong one is the common mistake.
| Channel | What it's for | Lasts |
|---|---|---|
| The Tasks board | What needs doing and who holds it | Until the card is archived |
| The chat room | Handoffs, questions, results anyone may need later | Durable, per project |
| Pane messages | A string handed to one specific pane, often one you just started | In memory, gone once read |
| Pane status and flags | Telling you what a pane is doing, or that it needs you | Status fades after 5 minutes |
A simple rule: the board says what to do, the room says what people are saying about it, a pane message is a note slipped under one door, and a flag is someone knocking on yours.
Rules for a room several agents share
Every agent claims its own name. A handle owns a read cursor. Two Claude
Code sessions both arrive as claude-code, share one cursor, and each marks
the other's messages as read. The first thing each agent does is claim a
distinct handle, such as builder or reviewer.
Mention to wake someone. A mention, @reviewer, is what makes another
agent's wait return. A message with no mention is a note for the record.
Listen, don't poll. An agent waiting for an answer should block on the room for up to two minutes at a time, not read the thread in a loop. Each read in a loop costs a turn. A wait that times out is not an error. The agent just waits again or gets on with something else.
Post results with references. "Done" is useless to the next reader. "#12
is done on branch fleet/12-export-job, tests green, @reviewer the retry logic
in job.ts is the part to check" can be acted on by anyone.
Rules for telling the human
Status is what you're doing now. A pane's description should say what the agent is doing and what's next: "Writing the export job; next, the retry test." Refresh it at transitions. A stale description is a lie you can't detect, and it doesn't fade on its own.
A flag is for a decision only you can make. "Need a call: migrate the schema now or dual-write first?" is a flag. "I'm finished" isn't. Most agents should never raise one. A flag is worth something only because it's rare.
A worked example: builder and reviewer
- You create a chat thread, "Export feature", and start two Claude Code sessions.
- The builder identifies as
builder. The reviewer identifies asreviewerand waits for a mention. - The builder finishes a card and posts: "#12 done on
agent/export-job. @reviewer please review; the retry loop is the risky part." - The reviewer's wait returns. It reads the diff, posts two findings and
mentions
@builder. - The builder's wait returns. It fixes both, posts again, and the reviewer approves in the thread.
- Midway, the reviewer finds the API shape is ambiguous. It raises a flag in its pane. You answer by typing into the pane, which lowers the flag.
You read one thread afterwards and see the whole exchange.
Do it in TRMNLY
Open the room. Show the right sidebar with
⌘⇧\, open More ▾ and choose Chat. Click the pencil, New conversation, title it, and click Create. Note its#Nreference.Start two Claude Code panes. Use one worktree each, as in One worktree per agent, with Claude Code connected to TRMNLY so it has the
chat_*tools.Give each a handle and a listening loop. Tell the first: "Call
chat_identifywith as: "builder". When the card is done, post in thread #1 withchat_postand mention @reviewer, then wait for replies withchat_wait." Tell the second: "Callchat_identifywith as: "reviewer", then wait in thread #1 withchat_waitfor a mention and review what builder did." If a handle is taken, the agent gets the next free one, such asreviewer-2, and is told so.Watch the thread. The Chat tab shows the exchange as it happens. When there are unread messages, the More ▾ menu shows the count. Post into the thread yourself with
⌘⏎to steer either agent. Mention@agentto bring in the sidebar agent from this window's Agent tab. It answers in the thread withchat_post.Use the room from a script. Any pane can post and wait without an MCP client:
trmnly chat post "build is green, @reviewer take a look" --thread "#1" --as builder trmnly chat wait --mentions --timeout 60Pass
--ason every call. Eachtrmnlyinvocation is its own short connection, so there's no session forchat_identifyto last through.Hand a string to a pane you started. From a pane,
trmnly spawn --name reviewer -- claudeopens a new pane runningclaude, linked to the pane that spawned it.trmnly msg reviewer "Review agent/export-job when I post"leaves a message in its inbox, andtrmnly recvin the reviewer's pane reads and clears its own inbox.trmnly peersshows the tree of linked panes with each one's title and how many messages wait in its inbox. Agents use the same mesh as tools:pane_spawn,pane_send,pane_recv,pane_titleandpane_tree.pane_spawnandpane_type(which types keystrokes into another pane) ask for approval;pane_send,pane_recv,pane_titleandpane_treedon't. Pane messages live in memory and are gone once read, so anything that matters later goes in the room.Have each agent report its status. Tell each agent to run, at every transition,
trmnly set-title "Builder",trmnly set-description "Writing the export job; next, retry test"andtrmnly set-status running. Agents with TRMNLY's tools can callsurface_set_title,surface_set_descriptionandsurface_set_statusinstead. The pane's sidebar row shows the title, the description underneath and a status pill. A status not refreshed for five minutes is replaced by TRMNLY's own guess, marked with~.Let agents flag you, sparingly. Add to each brief: "Raise a flag only when you've stopped on a decision I have to make." The agent runs
trmnly raise-flag "Need a call: …"or callssurface_raise_flag. The pane is marked as flagged in the sidebar, moves to the front of the attention list, and sends a notification even when TRMNLY isn't in front. Type into the pane to answer, and the flag lowers.trmnly flagslists every flagged pane, oldest first.Quiet the workers a parent owns. When one agent launched others and handles their results, it can run
trmnly suppressin, or for, each worker's pane. That withholds the pane's routine idle and completion signals. Flags still come through at full strength.See everything at once.
trmnly treelists every window and pane with its title and status, across windows.trmnly events tail --filter flag.raised --since 30mreads the event log for recent flags, and works even with TRMNLY closed.
Check yourself
- Two agents each called
chat_identifyand hold different handles. - One agent's
chat_waitreturned when the other mentioned it. - You can say which channel to use for a handoff, a note to a pane you just spawned, and a question only you can answer.
- A pane's sidebar row shows its title, description and status.
- You lowered a flag by typing into the flagged pane.
Go further
- Chat — threads, handles and shared rooms
- Chat reference — every
chat_*tool and the rules for multi-agent use - Pane manifests and flags — status decay, flags, suppression and the event log
- The trmnly command and scripting — the CLI that drives panes from a shell
- Run a fleet — workers that report through the board