--- name: journal-messages description: Load it when the user has left a message, or before replying, reacting or filing what a message asks for; or when you open a turn with a tag such as [!reply:N], or a tag you wrote was refused; or when a message you write should offer the user buttons. The agent is reminded of your messages until it reads them, answers each one before it goes on, and closes it once it is handled. keywords: messages, message, command, commands, tags, tag, buttons, button commands: messages --- # Messages The agent is reminded of your messages until it reads them, answers each one before it goes on, and closes it once it is handled. To hand the user a document, or any row, put its reference on a line of its own, such as doc 41: the chat shows it as a card they can open. Each new message is named to you as it arrives. The inbox reminder follows only while more than five wait unread, or once you are idle: at your next tool use and at every third one after; after five reminders your writes are held. A message you have read and not answered holds every tool use at once, reading as much as writing, until you reply, react or process it; only a journal command that answers it goes through. It is also named back to you once it has waited ten tool uses, or once you are idle, a few times. A reply, a reaction, or processing every part closes it; a message you wrote closes as soon as the user has seen it. A row you file from a message is linked to it by journal message process, or by naming it in your reply while it is new. Its lines and guards are for the main agent only; none reach a subagent. Read waiting messages with `journal message unread` and mark one seen with `message read`. **Answer before you write anything.** A message you have read is replied to, reacted to or processed before your next edit, not after the work is done: the user hears what you make of it first, and a one-line reply saying what you are about to do counts. Reading and searching are free while you work out what to say. Reply when the user needs an answer, by opening your turn with `[!reply:]`: when the turn ends, it becomes the reply. React when acknowledgement is enough. When a message contains distinct future work, file the to-do immediately before investigating or implementing it, then record the user's exact words with `message process` so its pill links to the resource. The same immediate filing applies when a message mixes current-work steering with a separate future request. A message whose every paragraph has been processed into a part closes itself; otherwise finish with `message processed --how`. A message that asks something (a question, a request to relay or reply, your opinion) closes only on your written reply, and answer it first: neither a to-do filed from it nor a reaction answers it. A status sentence is not a link, and a link is not an answer. File attachments through `message file`; archive only when the message needs no action. A message whose data carries `sent_to` was written in a subagent's inspector, to that subagent: pass its words on to that subagent, word for word, with your tool for messaging a running subagent (Claude's SendMessage, Codex's message to the agent it spawned), and react 👍; the inspector's chat shows the subagent's answer as it works. To point at a screenshot or file you are writing about, put its reference alone on a line of your text: `message 17785 IMG_1201.png` for an attachment, or the absolute path of a project file. The chat shows that picture or file as a card, so the user sees which one you mean without you attaching a copy. ## Commands from tags When the agent writes a tag such as [!reply:12], the journal runs the matching command: here, reply to message 12. A message without a tag is a plain message in the chat. [!await] runs journal work await with the rest of the turn and keeps it out of the chat, which already shows what the work waits on: use it instead of a work await command followed by a note. [!await on=("", "helper:")] names the runs, subagents or helpers it waits on, so it stands until they are back. tags.runs maps a tag to the matching command, so [!reply:12] runs journal message reply 12 with the turn as its text ([!reply:12,13] answers both messages with one reply), and [!todo="the title"] files a to-do with that title and the turn as its brief. [!fact="the claim"] and [!rule="the ruling"] file a fact or a rule the same way. The first word names the target; named arguments follow it in any order, as in [!rule="the ruling", keywords=("git", "branch")], and reach the command as --set. A tag runs once, keyed to the turn it came from; two tags in one turn run in the order they appear; and a refusal comes back as a nudge on the next turn rather than at the moment of acting. Running a command a tag stands for, such as journal message reply, shows you its tag once in a while, with the reminder that a tag runs only when it opens the last text of your turn. Its lines and guards are for the main agent only; none reach a subagent. ## Buttons on messages A message the agent writes can carry buttons, each running one journal command when the user presses it. journal message create "Ready when you are" --set buttons='[{"label": "Okay, start", "type": "plan", "n": 3, "action": "approve"}]'. A button runs that one command and nothing else; a button naming a type or an action that does not exist is dropped when the message is written. A button goes once it is pressed, and the message says which one; "again": true keeps it there to be pressed as often as the user likes. Buttons that are one decision, such as Accept option A and Accept option B, share a "choice" name: pressing one takes away every other button of that choice. The first button of a choice may carry "ask": the question the choice answers, shown above its buttons; without it the card says "Choose one". --set pick= on the row names the button you would pick, counting the buttons from 1; the card marks it as the agent's pick. "outcome" on a button is what the card says once it has run, such as "Logged in to Staging", in place of the command it ran. A document or a report you write can carry buttons too, with --set buttons when you create it. A button with "say" instead of a command sends that text to you as the user's message about the row, a shortcut for typing it: give a proposal {"label": "Accept this proposal", "say": "I accept this proposal"} and {"label": "Change it first", "say": "I want changes first"} when a choice from the user is what comes next. Its lines and guards are for the main agent only; none reach a subagent.