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: 1kind: commentcreated: {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.| Key | Type | Description |
|---|---|---|
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. |
Where a comment lives
Section titled “Where a comment lives”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.
Order of the thread
Section titled “Order of the thread”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.
Who wrote it
Section titled “Who wrote it”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.
Editing
Section titled “Editing”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.
Replies
Section titled “Replies”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.
Mentions
Section titled “Mentions”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.
Reactions
Section titled “Reactions”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}}| Key | Type | Description |
|---|---|---|
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. |
Move receipts
Section titled “Move receipts”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: 1kind: commentcreated: {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.| Key | Type | Description |
|---|---|---|
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.