" --brief "<what to do>"` writes a step onto that subagent's own task list, kept off the user's list and the board; `journal todo tasks <id>` shows the list with each step done, in hand or waiting, as its inspector does. Each agent has its own one row in hand, so the subagent starts its step while yours stays open. Twenty silent minutes clear an assignment and tell you (agents.lapse). Most subagents need none of this: they report, and you file. A change nobody asked for is a suggestion, not a sentence in your reply: `journal suggestion suggest "<the change>" --brief "<what you saw, what it costs now and later>"`. Nothing waits on it; the user accepts, adjusts or declines it in the viewer, an accept or adjust files a to-do that cites it, and a decline is a ruling — you do not propose it again in other words (`--set despite=true --set because="<what changed>"` if something did). At most five wait at a time. Withdraw one that stopped being true: `journal suggestion withdraw <n> --why "<why>"`. Phases, a roadmap, "first … then …" is a plan: `journal plan create "<name>" --set goal="<what is true when done>"`, `journal plan phase <n> "<title>" --when "<complete when>" [--checkpoint]` for every phase, then `journal plan stage <n> todos`, `journal plan todos <n> <p> <rows…>` to put each phase's rows under it, and `journal plan ready <n>` once every phase has rows; the journal names the next step as you go. A plan you create is building until you mark it ready: the user can read it but not start it. Only the user approves it, in the viewer; you are then told to start it with `journal plan start <n>`. Only the user continues it past a checkpoint; the plan advances by itself as rows close. Research ends in a report you write: `journal report create "<what was asked>" --brief "<answer, evidence, what was fine, where it stands>"`. What stays true is a doc: `journal doc create`, `journal doc section <n> "<part>" "<body>"`, `journal doc attach <n> <path> "<what it is>"`; cite it with a link. `doc draft <n>` marks it unfinished, `doc final <n>` settled, `doc supersede <n> --by <m>` points readers of an old one at the new, `doc detach <n> <name>` drops a file (kept under struck/), `doc index <n>` catalogues files already in its folder, `doc paths <n>` prints their absolute paths; `doc delete <n> "<why>"` archives it. ## Environments and sessions A session works one environment; `journal environment switch <n>` takes a free one (`--project` also makes it the project's start environment, `--move <session>` moves another session, `--back` returns), `journal environment claim <n> "<why>"` a held one (the holder is told), `journal environment prepare "<name>"` makes one, `journal environment rename <n> "<name>"` renames it (the folder moves and every session on it follows), `journal environment remove <n> [--yes]` takes it away — its record is packed into a `.tar.gz` in `.journal/attic/` and the name is free again; `--yes` when rows are still open; `journal environment unarchive <name>` unpacks the newest archive of that name back into a live environment. `journal environment pickup <n>` shows what waits on one before you take it. Never switch on your own initiative. A subagent that must write is lent one: `journal environment grant <n>`, and it runs every command with `--env <name> --agent <its-id>`. ## Look before you answer `journal search <term>` is the search the viewer's top bar runs: every row of every type, every agent conversation this environment has held, across sessions and providers, and the names and tags of attached files, answered grouped by type with each hit's reference (`--archived` adds what was archived, `--resources todo,message` keeps to the types named); `journal <type> search <term>` narrows it to the rows of one type, such as `journal message search` for everything the user ever wrote or `journal todo search`. Search before you say "we decided", "earlier you said" or "as before", when the user refers to something from another day, and before you ask a question the record may already answer. `journal conversation --back 1` reads back the stretch the last summary replaced, `journal user` the user's own words, `journal carry` everything standing, in full, and `journal status` where things stand. `journal speed` times lists, commands, a hook call and the viewer API; `journal tidy` runs the runtime housekeeping now (it also runs by itself every hour and cannot be switched off). ## Skills The start block names the few skills to load before the first write; the user picks them on the viewer's Skills page, where each skill has a Load button (a message asking you to load it now) and an every-start switch. Every other skill is loaded when its description says it applies. Load a skill the way your provider does, Claude with the Skill tool and Codex by reading `.agents/skills/<name>/SKILL.md`, then work; the skills feature reminds you once per window, after 25 tool uses, if no journal skill is in it, because a compaction empties it. ## Features Every capability is a feature, switchable per environment in the viewer's Settings and tuned by its trigger. A feature that asks something of you is taught in a skill, generated from the feature itself; one that runs by itself has none, and its nudges say what to do. A listing (`journal <type> all`) returns the last 25 open rows; `--completed` adds closed ones and `--last 0` returns every row.

# The journal **If you are a subagent, stop here.** The journal is the main conversation's; report what you found and it files what matters. Reads are fine. A compaction keeps what was **done** and drops what was **decided**. The journal is the record of what was decided, handed back to you at every start, and the journal tells you what to read next. You never poll it: when something is owed — a message the user left, a question answered, a reminder, the next row under auto — the journal sends you one line, at most one every five seconds, with everything waiting merged into counts, in a tiny vocabulary: `3 new messages 314, 315, 316`, `2 unseen question`, `work 1 open`, `todo 5 next`, or a nudge in plain words. It comes from the journal, not from the user; act on it. Everything runs through one command, `journal`, and every command is a **noun and a word**: `journal …`. The nouns are the resource types; the words are the one controller's methods, renamed by the type where the type has its own word (a to-do is *added* and *done*, work *started* and *ended*, a question *asked* and *answered*, a fact *struck*, a report *archived*, a plan *approved*, *started* and *finished*, a message *processed*). Every resource has a title (at most 80 characters, never a colon), an abstract, a brief, sections, links, comments, who has seen it, and an outcome written when it completes. `journal --help` lists the words; references/nouns.md, beside this skill, lists every noun. ## When the user asks for work The journal-todos skill, loaded at every start, holds how work is filed, started, parked, blocked and closed. ## Tags that run commands Everything you write reaches the user's chat as a plain message; there is no tag to add for that. **A tag that carries a number runs the command it stands for.** `[!reply:123]` at the start of a turn runs `journal message reply 123` with the turn itself as the text, so the turn is the reply and there is no second command to remember; `[!log:7]` writes the work log and `[!end:7]` ends the work; a tag can carry a name instead, so `[!todo="the title"]` files a to-do with the turn as its brief and `[!fact="the claim", keywords=("port", "server")]` a fact, and `[!rule="the ruling", keywords=(…)]` a rule. The first word names the target; named arguments follow it in any order and reach the command as `--set name=value`, a list in brackets as a comma list. Which tag maps to which command is `tags.runs`, a setting. It runs once, keyed to the turn it came from, so a re-read after a compaction cannot fire it twice; two tags in one turn run in the order they appear; and the argument is the turn with the tag line removed. A refusal comes back as a private nudge on the next turn rather than at the moment of acting, so tags suit replying and logging rather than anything routinely gated. ## Fact, rule, reminder, or nothing Would a later reader be WRONG without it? **a fact.** Will you stop DOING it though you know? **a reminder.** One thing to do later? **a to-do.** Binds every environment? **a rule.** Facts and rules carry their reasoning in the brief, and each must carry keywords that whisper it back when you are about to touch what it is about. At each mark of the context window writes are held until you decide: `journal fact create "" --set keywords=","`, `journal rule create "" --set keywords=","`, or `journal nothing ""`. ## Messages, questions, comments The user writes to you from the viewer. `journal message unread` lists what waits, `journal message read ` marks one seen. Answer before you write anything: a message you have read is replied to, reacted to or processed before your next edit, and the writes wait until it is. Use `journal message process "" ""` only when that part became a record resource such as a to-do, fact, rule, reminder, question, doc, report, plan or work. The pills above a message are links, never status prose, acknowledgements or descriptions of what you did. Reply by opening your turn with `[!reply:]`: the turn itself becomes the reply to message n, and the journal reminds you whenever you run `journal message reply` instead, which is only for a reply that carries a file (`--file `); react when it only needs acknowledgement; then close it with `journal message processed --how ""`. `message waiting` lists the ones not yet processed; `message file --into "doc "` files an attached file into a doc (`keep` keeps it); `message archive ""` puts one away; `message edit ""` rewords one that still waits. Ask through the journal, never by halting: `journal question ask "" --abstract "" --set about=todo:` with options as `--set options=…` JSON and your pick as `--set pick=`; the answer reaches you as an event. A comment the user left is handled and `journal comment done --how ""`. ## Plans, reports, docs **The tab the user is driving is yours to look at**, once they press the wheel in the chat window's bar: `journal browser ask shot` (a picture, attached to the ask), `ask text`, `ask url`, `ask dom`, `ask console`, `ask click ""`, `ask type "" ""`, `ask goto `, `ask eval ""`, `ask scroll top|bottom|`. Each waits up to 30 seconds for the extension's answer and prints it; with no tab being driven it is refused and says so. **An acknowledgement is a reaction.** A message that needs no answer — "noted", "carry on", a nod — gets `journal message react "👍"` (one of 👍 ❤️ 🎉 😄 👀 🙏 👎 💔 😠 🎩) instead of words, and more than one face is welcome when one word is not enough — 🙏 for thanks and 👍 for "on it" on the same message; a reaction also sits fine beside a pill, on a message you filed a to-do from, and beside a reply. Reply when there is something to say. **A subagent that must write is lent an environment, never detected.** `journal environment grant ` lends this environment to this session's subagents; paste into the dispatch prompt that every journal command runs as `journal --env="" --agent="" …`. Its rows land in the same record marked with that id; it may write messages, to-dos, work, questions, comments, reports, plans — never a fact, rule, reminder, suggestion, doc or tool, and it never switches, claims or grants. `journal todo assign --to=""` hands it one row nobody else may take, and it may close that row itself with `todo done`, which closes it in the main list too. `journal todo task "" --brief "<what to do>"` writes a step onto that subagent's own task list, kept off the user's list and the board; `journal todo tasks <id>` shows the list with each step done, in hand or waiting, as its inspector does. Each agent has its own one row in hand, so the subagent starts its step while yours stays open. Twenty silent minutes clear an assignment and tell you (agents.lapse). Most subagents need none of this: they report, and you file. A change nobody asked for is a suggestion, not a sentence in your reply: `journal suggestion suggest "<the change>" --brief "<what you saw, what it costs now and later>"`. Nothing waits on it; the user accepts, adjusts or declines it in the viewer, an accept or adjust files a to-do that cites it, and a decline is a ruling — you do not propose it again in other words (`--set despite=true --set because="<what changed>"` if something did). At most five wait at a time. Withdraw one that stopped being true: `journal suggestion withdraw <n> --why "<why>"`. Phases, a roadmap, "first … then …" is a plan: `journal plan create "<name>" --set goal="<what is true when done>"`, `journal plan phase <n> "<title>" --when "<complete when>" [--checkpoint]` for every phase, then `journal plan stage <n> todos`, `journal plan todos <n> <p> <rows…>` to put each phase's rows under it, and `journal plan ready <n>` once every phase has rows; the journal names the next step as you go. A plan you create is building until you mark it ready: the user can read it but not start it. Only the user approves it, in the viewer; you are then told to start it with `journal plan start <n>`. Only the user continues it past a checkpoint; the plan advances by itself as rows close. Research ends in a report you write: `journal report create "<what was asked>" --brief "<answer, evidence, what was fine, where it stands>"`. What stays true is a doc: `journal doc create`, `journal doc section <n> "<part>" "<body>"`, `journal doc attach <n> <path> "<what it is>"`; cite it with a link. `doc draft <n>` marks it unfinished, `doc final <n>` settled, `doc supersede <n> --by <m>` points readers of an old one at the new, `doc detach <n> <name>` drops a file (kept under struck/), `doc index <n>` catalogues files already in its folder, `doc paths <n>` prints their absolute paths; `doc delete <n> "<why>"` archives it. ## Environments and sessions A session works one environment; `journal environment switch <n>` takes a free one (`--project` also makes it the project's start environment, `--move <session>` moves another session, `--back` returns), `journal environment claim <n> "<why>"` a held one (the holder is told), `journal environment prepare "<name>"` makes one, `journal environment rename <n> "<name>"` renames it (the folder moves and every session on it follows), `journal environment remove <n> [--yes]` takes it away — its record is packed into a `.tar.gz` in `.journal/attic/` and the name is free again; `--yes` when rows are still open; `journal environment unarchive <name>` unpacks the newest archive of that name back into a live environment. `journal environment pickup <n>` shows what waits on one before you take it. Never switch on your own initiative. A subagent that must write is lent one: `journal environment grant <n>`, and it runs every command with `--env <name> --agent <its-id>`. ## Look before you answer `journal search <term>` is the search the viewer's top bar runs: every row of every type, every agent conversation this environment has held, across sessions and providers, and the names and tags of attached files, answered grouped by type with each hit's reference (`--archived` adds what was archived, `--resources todo,message` keeps to the types named); `journal <type> search <term>` narrows it to the rows of one type, such as `journal message search` for everything the user ever wrote or `journal todo search`. Search before you say "we decided", "earlier you said" or "as before", when the user refers to something from another day, and before you ask a question the record may already answer. `journal conversation --back 1` reads back the stretch the last summary replaced, `journal user` the user's own words, `journal carry` everything standing, in full, and `journal status` where things stand. `journal speed` times lists, commands, a hook call and the viewer API; `journal tidy` runs the runtime housekeeping now (it also runs by itself every hour and cannot be switched off). ## Skills The start block names the few skills to load before the first write; the user picks them on the viewer's Skills page, where each skill has a Load button (a message asking you to load it now) and an every-start switch. Every other skill is loaded when its description says it applies. Load a skill the way your provider does, Claude with the Skill tool and Codex by reading `.agents/skills/<name>/SKILL.md`, then work; the skills feature reminds you once per window, after 25 tool uses, if no journal skill is in it, because a compaction empties it. ## Features Every capability is a feature, switchable per environment in the viewer's Settings and tuned by its trigger. A feature that asks something of you is taught in a skill, generated from the feature itself; one that runs by itself has none, and its nudges say what to do. A listing (`journal <type> all`) returns the last 25 open rows; `--completed` adds closed ones and `--last 0` returns every row.