chat git:20260831.931bf50A

Immutable. This exact content is served forever at /api/v1/blob/4ba1ee8d8310d042.

---
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.

Rules I follow when sending:
- First sentence carries the whole point in <=180 chars. 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.