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
ait note 42 --project mobile --from 349 --text "..."       # Note to t42 in another repository
ait note read 42 --project mobile --by 42 --ids <note-id>  # Acknowledge it there

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.

Sending to another repository

--project <name> sends the note to a task in a sibling project — another repository registered with ait projects. The target id then names a task in that repository; --from still names your task in this one. Everything else — the body options, --with-live, the output codes — is the same.

ait note 42 --project mobile --from 349 --file - <<'NOTE_BODY'
t349 renames the /v1/sessions endpoint; your API client in t42 still calls the old path.
NOTE_BODY

For a task you do not own, a note is usually the right tool: it adds context to that task’s ## Inbox without editing its description, metadata or status. If the content is itself work, create a task there instead (ait create --batch --project <name>).

The other repository does the write. ait note runs that repository’s own installed ait note, from inside it. The inbox lock, the task-data branch, the commit and the push are all that repository’s; nothing in your repository changes. The path in NOTE_APPENDED: and the other id-bearing lines is absolute, because it names a file in the other checkout.

How the project name is resolved. The name is looked up the same way as for ait projects resolve — a live tmux session for that project, the project registry, then an AITASKS_PROJECT_<name> environment variable — with one difference: ait note checks every source rather than taking the first match. If they point at two different checkouts, or a source could not be read, the note is refused instead of guessing where to write.

How the sender is recorded. The note stores from=<your-project>#t<id>, never a bare t<id> — a bare id would read as a task in the recipient’s own repository. Your project’s name comes from the project registry or an AITASKS_PROJECT_<name> variable pointing at this checkout; a tmux session name is never used for this. If the registry lists this checkout under several names, pass --from-project <name> to choose one. Your task must exist; it is checked before anything is written. from_verified=yes is recorded only when your session holds your task’s lock, exactly as for a local note — see Provenance.

Refusals. Each one is a single NOTE_ERROR:<reason> line (READ_ERROR:<reason> for ait note read), exits 1, and happens before anything is written in either repository:

A target task that does not exist in the other repository is reported there, as NOTE_TARGET_MISSING:<id>.

Live delivery works the same way — the other repository’s live-endpoint lookup runs after its note is committed, and it only finds sessions on this machine.

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. If removing the receipt fails too, the receipt stays on disk, uncommitted, hiding the note on this machine. No automatic step can settle that, so it is reported on its own as READ_ERROR:rollback-failed:, and stderr names the block: remove it from the task file, or commit it.

How the inbox is stored

Notes and read receipts share one ## Inbox section in the task file. Everything in that section is written by the framework except a note’s body, which is free text from another session — the one part an untrusted writer controls. It is stored so that it cannot pass for anything else:

• Every body line is stored behind a > | prefix. A block header is recognised only at the start of a line, so no line of a note body can parse as one. A note therefore cannot forge a read receipt — for itself or for any other note in the file — and cannot open a new section heading that would swallow what follows it. The prefix is added when the note is written, so every reader is protected without doing anything.
• Receipts use the reserved name read. A note’s header always names its sender’s task, so no note can take that name.
• A receipt that does not validate is skipped, so a malformed receipt can never hide a real note. The read-only inbox query reports any block that failed validation as INBOX_MALFORMED:, so it is not silently ignored either.

Change the section only through ait note.

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.
• For a note sent with --project, it is the recipient’s checkout — the tree the note was written into, and the one its reader can check out. The sender’s own repository is not recorded; a commit from there would not exist in the recipient’s history.
• 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