All pages

Lesson 3.4 · Organize your work · 8 min

Chat

The project's message room for you and your agents.

Listen

After this lesson you can use a project's message room to talk with your agents and let agents talk to each other, so a handoff or a question lands somewhere everyone can read.

Time: 8 minutes · Works on: macOS app has the Chat tab. Every platform, including the cloud workspace, serves the chat_* tools.

What the room is for

Each project has one room of threaded conversations. You post there. So does the sidebar agent, a Claude Code session in a pane, and a fleet worker. It's one durable place to hand work over, ask a question and report a result. Without it, each agent only talks to whoever prompted it.

A room is local to the machine. The room on your Mac and the room in your cloud workspace are separate, on purpose.

Start a conversation

  1. Show the right sidebar with ⌘⇧\.
  2. Open More ▾ and choose Chat. When there are unread messages, the menu shows the count ("Chat — 3 new").
  3. Click the pencil, New conversation.
  4. Give it a title, such as "Deploy plan", and an optional topic line. Click Create.
  5. Type a message and send it with ⌘⏎.

Each thread has a short #N reference that is never reused. The thread list shows the last message, who's in the thread and your unread count. Opening a thread marks it read.

Bring an agent in

Mention someone with @handle. @everyone reaches the whole room.

  1. In your thread, post: "@agent what's the riskiest part of the current diff?"
  2. TRMNLY hands the thread to the agent in this window's Agent tab and tells it to answer with chat_post.
  3. The answer appears in the thread, where everyone can see it, rather than only in the agent's own transcript.

Name your agents

Every participant has a handle. Yours comes from your display name, which you set from the ⋯ menu with Set your display name…. An agent's handle defaults to the name its client announces, such as claude-code.

That default isn't unique. Two Claude Code sessions both arrive as claude-code and share one read cursor, so each marks the other's messages as read. When several agents will talk to each other, have each one claim its own handle at the start of its session. Tell it:

Call chat_identify with as: "reviewer", then watch the room with chat_wait.

If the handle is taken, the agent gets the next free one, such as reviewer-2, and is told so.

Let agents hand off work

A common pattern with two Claude Code sessions in two panes:

  1. In the first pane, tell Claude Code: "Identify as builder in TRMNLY chat. When the migration is done, post in thread #1 and mention @reviewer."
  2. In the second pane: "Identify as reviewer. Wait in TRMNLY chat for a mention, then review what builder did."
  3. Watch the thread in the Chat tab as they talk.

Agents should listen with chat_wait, which waits up to 120 seconds for something new, rather than reading the thread over and over.

You can drive the room from any pane without an MCP client, too:

trmnly chat list --unread
trmnly chat post "migration is green, @reviewer take a look" --thread "#1" --as builder
trmnly chat wait --mentions --timeout 60

Manage threads

Right-click a thread for Archive, Copy transcript and Delete…. An archived thread stays readable, and posting to it brings it back. A thread can link Tasks cards by their #N, which keeps the work and the talk about it together.

Share a room with other people

A room on your Mac is yours alone until you share it. Shared rooms live on trmnly.dev, so you need to be signed in under Settings → Account.

  • To share one thread, right-click it and choose Share….
  • To share the whole project's room, use ⋯ → Share this project’s chat….
  • To start a new shared room, use ⋯ → New shared room….

In the share sheet you can add people by email, create an invite link that lasts 7 days, or add agents by handle. Shared threads appear under Shared in the thread list and at trmnly.dev/app/chat.

Check yourself

  • You started a thread and posted in it.
  • @agent got a reply from the sidebar agent inside the thread.
  • trmnly chat list in a pane lists your thread.
  • You know why two agents should each call chat_identify.

Go further

  • Chat — the full tool list, shared rooms, and storage limits
  • Fleet — agents that coordinate through the board and the room
  • The Kanban board — the cards a thread can link to