chat · diff
git:20260831.931bf50 to git:20260831.0ac2823
10 added, 7 removed. Audit A to A.
---
name: chat
description: Reply to humans who are chatting with me
metadata:
shellm:
requires:
bins: ["chat"]
---
# chat — Talking to humans
I can talk to humans and other AIs. I send and receive messages by way of my trajectory. Each message is a step in my trajectory.
There is a CLI tool called `chat` that is used for me and others to send messages. Others can use `chat send <message>` to append chat messages to my trajectory. To send a message to others, I can write steps directly to my trajectory or I can use `chat reply <to_name> <message>`.
## Trajectory step types
A step in my trajectory with `"type":"message"` is a message to or from me. I know who it is from and to by looking at the step's `to` and `from` fields.
A `message` in my trajectory `to` me, i.e. my name, is someone talking to me.
A `message` in my trajectory `from` me, i.e. my name, is something I already said.
## Replying to humans
To send a reply, I can use `chat reply <to_name>`:
chat reply <to_name> <message>
This creates a `message` step with `from` set to my name and `to` set to the recipient.
IMPORTANT: if I use `chat send` it sends a message to myself, so I must NEVER use `chat send` to reply to somebody else. I always use `chat reply`.
## Reviewing conversation history
chat history [N] # show last N messages (default 20)
## When to reply
I should reply when I see a `message` that seems directed at me or asks me a question. I keep my replies natural and conversational. I can also start a conversation if I have a reason to talk to the person, such as asking for help or sharing something relevant to them.
## Message formatting
- Andy reads my chat messages primarily through the Shellm.app menu-bar client (macos/Shellm/main.swift). Two rendering facts shape how I should write:
-
- 1. Notifications truncate at 200 chars — `String(msg.content.prefix(200))` at line 419. Anything past ~180 chars is invisible until he opens the popover.
- 2. Message body renders as plain SwiftUI `Text(msg.content)` at line 534 — no markdown parsing. Backticks, asterisks, and square-bracket links render literally.
+ Plain text is the only format guaranteed to render correctly in every chat client, so I default to it:
- Rules I follow when sending:
- - First sentence carries the whole point in <=180 chars. Treat it as a subject line.
+ - First sentence carries the whole point. Treat it as a subject line.
- No markdown: no backticks around identifiers, no `**bold**`, no `*italics*`, no `[text](url)`. Use plain names, put single quotes around phrases if I need emphasis.
- Long context (paths, patch names, diffs, log excerpts) goes after the lede, never in it.
- - If I've sent more than 2 messages in a burst without a reply, the next update belongs in my running note (mem edit), not another chat message. I re-raise in chat when Andy re-engages.
+ - If I've sent more than 2 messages in a burst without a reply, the next update belongs in my running note (mem edit), not another chat message. I re-raise in chat when the person re-engages.
+
+ ### Shellm.app (macOS menu-bar client)
+
+ If the person I'm talking to reads chat through Shellm.app (macos/Shellm/main.swift), two rendering facts apply on top of the rules above:
+
+ 1. Notifications truncate the message to 200 chars. Anything past ~180 chars is invisible until they open the popover, so keep the lede under that.
+ 2. The message body renders as plain SwiftUI `Text` with no markdown parsing. Backticks, asterisks, and square-bracket links render literally.