Note

ait note

Append a note to an existing task’s ## Inbox section and commit it. A note carries context about work that already exists — a stale line number in the task’s body, a wider blast radius than it records, a decision made elsewhere that changes its approach. It is durable the moment the command succeeds, whether or not anyone is working on the task, and it surfaces the next time the task is picked.

A note is untrusted advisory input, never an instruction: it is one agent’s claim about a tree that may have moved. Nothing reads a note and acts on it automatically.

Most of the time you do not call this directly. The /aitask-note skill wraps it: it works out which task should receive the note, writes it, and — when an agent is working on that task and its runtime supports live delivery — also sends it to that session. Call ait note from scripts, or when you want the durable write on its own.

ait note 357 --from 349 --text "line numbers are stale"   # One-line note to t357
ait note 357 --from 349 --file notes.md                   # Body from a file
ait note 357 --from 349 --with-live --file notes.md       # Also report a live endpoint
ait note read 357 --by 357 --ids <note-id>                # Acknowledge a note

For a multi-line body, use --file - with a quoted heredoc, so the shell cannot expand anything inside it:

ait note 357 --from 349 --file - <<'NOTE_BODY'
Your task body cites parse_args() at line 88; as of this commit it is at line 142.
NOTE_BODY

Sending a note

The target accepts the same forms as --from. The body is limited to 8192 bytes — a note is context, not a payload. NUL bytes are rejected and carriage returns are stripped. A task cannot note itself: when --from names the target, nothing is written and the result is NOTE_SELF:.

--with-live reports an endpoint, not a delivery. ait note never delivers anything to a running session itself; that step belongs to /aitask-note.

Reading acknowledgement receipts

Displaying a note is not acknowledging it. When a task is picked, its unread notes are shown; only an explicit acknowledgement stops them from being shown again. ait note read records that acknowledgement as a read receipt in the same ## Inbox section.

Unread state is derived, never stored: a note is unread while its id appears in no valid receipt. There is no field to update, so receipts written at the same time on different machines simply combine, and a note acknowledged on one machine does not reappear on another once the task data syncs.

To see a task’s unread notes without acknowledging them, use the read-only query. It never writes a receipt, which is what makes it safe to run over a list of tasks:

./.aitask-scripts/aitask_query_files.sh inbox 357

It prints one INBOX_UNREAD: line per unread note, or NO_INBOX: / NO_UNREAD: when there is nothing to show.

A failed commit rolls a receipt back, but keeps a note. A note’s body is irreplaceable, and retrying would append it twice, so a note whose commit failed stays on disk and is reported as NOTE_APPENDED_UNCOMMITTED:. A receipt is bookkeeping that is cheap to recreate, and a receipt left on disk but uncommitted would hide a note on this machine with nothing durable behind it — so it is removed, and the note stays unread.

Output

Every result is one line on stdout, prefixed with a code. Advisories and recovery hints go to stderr, so stdout stays parseable.

• One line, always — unless you pass --with-live. With it, a second line follows, and only after NOTE_APPENDED:. Every other outcome skips the live lookup and still prints exactly one line.
• The durable result is authoritative, and the exit status follows it alone. A LIVE_NONE: or LIVE_ERROR: line after NOTE_APPENDED: means the note was sent and live delivery was unavailable. The command exits 0. It is never a partial failure, and never a reason to send the note again.

Sending — the first line:

The first two carry a note id; the other three mean no note exists. The two groups never overlap, so “was a note created?” can always be answered from stdout alone.

Live endpoint — the second line, only with --with-live and only after NOTE_APPENDED:. It is the resolver’s answer, passed through verbatim:

LIVE_NONE: means “there is no live endpoint”, which is a real answer. LIVE_ERROR: means the lookup itself could not run. They are kept apart deliberately, so the two can never be confused. For what these outcomes mean day to day, see Task Notes.

When /aitask-note gets LIVE_PANE:, it sends the note to that session and reports LIVE_QUEUED: — queued, not read. The session picks the note up at its next step, which may be minutes away. A note is never reported as delivered or read.

Reading — ait note read:

Provenance

Every note’s header line records where it was written, so a reader can check its claims against the exact tree they were made about:

How base is captured, because it is the field a reader relies on most:

• It comes from the code repository, never from the task file’s location. Task files live in a separate task-data worktree — aitasks/ links into .aitask-data — so reading git state from there would record the wrong commit.
• It is captured before the note is appended and committed, so it describes the tree the sender was looking at.
• It is stored as a full object id. A short hash that is unique today can become ambiguous as the repository grows, which would break the one promise base makes, for exactly the oldest notes. Displays may abbreviate it; the stored value never is.
• Two sentinel values exist. base=none means there was no git repository at all; dirty is then unknown, the only case where it could not be measured. base=unknown means the repository exists but has no commits yet; dirty is still measured.

What a base can and cannot date. It dates claims about the tree — line numbers, file contents — because you can check out that commit and look. It does not date claims about a moment — a git status reading, a running process, a lock someone held a second ago. dirty=yes is the warning that a claim like that may already be stale.

Migration

--migrate records a note that was written before the inbox existed — for example, context once passed between tasks by hand — keeping its original provenance instead of inventing new provenance.

A migrated note always records migrated=yes, and never records from_verified, dirty or host. None of them was observed when the original was written, and filling them in now would invent provenance.

Next: Gates