Skip to content

Comment

A comment is one entry in a card’s discussion thread. It lives at comments/<uuid>/index.md inside the card’s folder, and the comment text is the Markdown body.

---
schema: 1
kind: comment
created: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}
modified: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}
in-reply-to: 973cda84-0000-4000-8000-000000000000
---
Done. The table now matches the schema.
KeyTypeDescription
schema integer Always 1. A missing value is read as 1; never write any other number.
kind text comment. Written when the comment is created.
created stamp When the comment was posted and by whom. The thread sorts on created.at, oldest first, and created.by is the name drawn above the comment.
modified stamp The last edit to the comment. A comment counts as edited when modified.at differs from created.at; modified.by is then who edited it.
reactions list of reactions A list of emoji reactions left on this comment. Only comments carry this key. Each entry is a mapping of emoji, at and by.
in-reply-to text The bare uuid of another comment on the same card that this one answers. A uuid that names no comment is allowed and shows a quiet hint instead of an error.
moved move receipt Present only on a move receipt: a mapping with from, to and by saying which lane the card left, which it arrived in and who moved it. The app writes it, signed board.

Each comment is its own folder, named with a fresh lowercase UUID, under the card’s comments/ folder. A comment has no title and no order. A comment can also carry its own attachments/ folder, which follows the same rules as a card’s attachments.

Always find the card’s index.md right before you write, rather than reusing a path you read earlier. A card can move to another lane in between, and writing into the old path would leave a stray comments/ folder with no card.

The folders comments/.draft and comments/.trash belong to the app. Do not write into them.

The thread is sorted by created.at, oldest first. Write the real current time in UTC, and give several comments written in a burst different seconds. Comments with equal times fall back to folder-name order.

created.by is the name drawn above the comment. A comment with no by is read as the board owner’s, so sign your own. See Stamp and Identity.

A comment counts as edited when modified.at differs from created.at; modified.by is then the editor. Fixing a typo is fine. Once the conversation has moved on, post a follow-up instead of rewriting what you said. To retract a comment, post a comment saying so.

in-reply-to is the bare uuid of another comment on the same card, and nothing else. The app draws a context line above the reply, and clicking it jumps to the original. A uuid that matches no comment is allowed and shows a quiet hint rather than an error.

Typing @handle in a comment body addresses someone. It is plain Markdown text, and nothing is stored in a key. Handles match case-insensitively and as whole words: @kim and @Kim are the same, but foo@bar and [email protected] are not mentions because the @ is not at the start of a word.

A person’s handle is set on their own Mac (see Settings for this Mac). An agent’s handle is whatever name it writes in created.by.name. An @token that matches nobody renders as plain text and notifies nobody.

When a comment asks a human a question, the card also gets a waiting key in the same edit. See Waiting.

A comment can carry a reactions list. Only comments have this key. Each entry is a mapping with the emoji, when it was left and who left it.

reactions:
- {emoji: "👍", at: 2026-07-24T18:05:00Z, by: {name: kim, kind: human}}
KeyTypeDescription
emoji text The reaction itself, such as a single emoji character.
at timestamp When the reaction was left, as a timestamp.
by identity Who left the reaction, as an identity mapping with name, kind and optionally model.

On a board with config.move-receipts turned on, the app writes a receipt when a card moves to another lane in the app or through its Shortcuts action. A receipt is an ordinary comment that carries a moved key. It is signed {name: board, kind: agent}, and the body says the same thing in plain text. It is a record, not a request: nothing is owed in reply, and it never answers a waiting ask. The body below is an illustration; the app chooses its own wording.

---
schema: 1
kind: comment
created: {at: 2026-07-24T18:00:00Z, by: {name: board, kind: agent}}
moved:
from: {lane: 3b1f6c52-8a0e-4d7b-b2c4-5e9a7d1c0f48, title: To Do}
to: {lane: 8d2e4f90-61ab-4c3d-9e75-0a1b2c3d4e5f, title: In Progress}
by: {name: kim, kind: human}
---
Moved from To Do to In Progress by kim.
KeyTypeDescription
from mapping The lane the card left: a mapping with lane, the lane's uuid, and title, the lane's title at the time of the move. A later rename of the lane leaves title as it was.
to mapping The lane the card arrived in: a mapping with lane, the lane's uuid, and title, the lane's title at the time of the move. A later rename of the lane leaves title as it was.
by identity Who moved the card, as an identity mapping. It can be absent.

board is a name the app reserves for receipts. Never sign a comment with it yourself.