Using a Leaf page

Panel, rail and thread cards

Leaf adds controls around the authored HTML. This interface is called chrome: the Leaf panel floating at the window's foot, comment and decision markers, and thread cards. At rest the panel is one row: the leaf, coloured by the agent's state; the comment field, which shows the agent's status while it is empty; and the On Me mark, counting what waits on the user, with a dot while a thread holds a reply they haven't read. The leaf opens a small menu of the page's other controls. Pressing the On Me mark opens its view above the row. A ✕ replaces the mark while the view is open and closes it when pressed. A folded panel shows only the leaf in the window's corner.

The On view shows one list at a time, under a tab named for its actor, with completed items under Done, and a Threads tab listing the open threads under Open, then the resolved ones under Resolved. On Me and the agent’s list defines their membership. Opening a view preserves the page’s text wrapping and reading position.

The page reserves space at the bottom for the panel's row, so the last lines can scroll above it. A view opens above the row and overlays the page without moving its content. Escape or a press on the page closes the view. Phones and touch screens describes the panel on a touch screen.

The rail is the strip to the right of main where Leaf places comment and decision markers. It appears when the window has enough space: about 960px on a column page or about 1920px on a sidebar page. data-rail="right" keeps it visible above 640px, except on a workspace, whose panes scroll on their own. Where no rail fits, and inside a scrolling pane, a small pin appears beside the target on the page. Leaf places it clear of text and controls when space permits. The o shortcut hides pins and passage highlights.

A thread card opens beside its marker in the margin. If the margin is narrower than the card, it overlaps the text's edge. Threads, a thread opened from it, the On view and All pages open as views above the panel's row, one at a time.

Who can open a page

A page's URL carries an access key, which the browser keeps in a cookie. One key covers every Leaf page on the machine that serves it, so anyone with one page's URL and a network route to that machine can read and act on all of them. A page served on loopback opens only on that machine; one served on an SSH destination or another hostname opens from that network. Leaf opens no public tunnel.

On leaf.page, each browser works on a private copy of a page. Its comments, choices and the hosted agent's revisions are visible to no other browser (The leaf.page website).

Offline exports

leaf page export PAGE -o FILE captures a stamped version, its resources and the decisions recorded on its widgets in one HTML file. The file holds none of the conversation with the agent, on screen or in its source: no threads or their attachments, to-dos, plan or changelogs. Reading controls and page-owned code work offline; new Leaf choices, comments and Undo need the served page. An agent need not be running to record a choice on a live server. Pages containing live samples cannot export.

Comments and replies

Select a passage, then use the comment control or press c to write a comment. The thread keeps that passage as its anchor. Its marker opens the conversation beside the passage, where the agent's reply and the reply box appear.

The Threads tab of Leaf's On view, which the panel's On Me mark opens, lists the threads above the panel's row. Select a thread to read its messages and reply in the panel's comment field. Its passage link returns to the anchor on the page.

A reaction records brief feedback on a passage or agent reply without opening a thread. The default reactions request keeping, changing, clarifying, shortening, supporting, or prioritizing content. Packages can declare additional reactions.

Try a thread

This fictional exchange shows an agent's reply after revising the importer policy. Open the marker beside the sentence to read the exchange, or open Threads in the sample's top row. Select the sentence to try a comment. The sample has its own temporary log; no agent answers its practice comments. Reset restores the fictional exchange.

Anchors

A thread's anchor is the place on the page it is about. The first comment records it in the event log, and that record never changes; a reply or a revision can later move the thread to a new anchor. A comment can be anchored in these ways:

An agent opens threads with the same anchors, using leaf thread create with --quote, --section, --part, or none of them.

How a thread ends

The user usually closes a thread with Resolve thread once they have read the answer. Its marker and ink leave the page, and it moves from Threads' Open list to Resolved. Reopen brings it back, as does z when resolving was the user's latest action.

The agent resolves a thread only when the user asks, or when no review could change the outcome; the thread then reads “Resolved by” and the agent's name. A new message from either side reopens a resolved thread. A reaction, a progress message or a failure notice does not.

z takes back the user's latest action, a message they just sent included: a comment, reply or reaction. A reaction's mark also has an undo control of its own. The log gains an undo naming the message, and the message leaves the page, with any thread it started. Where something has already answered it, it stays in its place instead and reads Deleted. To delete an older message, the user rewrites it to no words.

Words typed but not sent are kept after their box closes. If a new version removes the content they were about, Resume writing (g i) opens them, unsent, in Comment on the page, after any words already there.

Progress on an update and the page

Leaf distinguishes progress on one update from the page’s status. A busy agent has not necessarily started every comment. The agent names the update or to-do it is handling and the work it is doing, in one line. That line appears beside the relevant thread or widget and in the panel; replies carry the results.

A session is the agent conversation attached to the page; a turn is one run within it. A watcher receives updates between turns. The illustrative sequence below follows a request to shorten a lede; its times are examples, not delivery guarantees.

1. 0s observation Queued for Claude The comment appears in its thread immediately, reading Queued for Claude until the agent has it.
2. 1s observation Delivered The hook puts the comment into the agent’s turn, and Claude Code's transcript then confirms it reached the agent. Until the agent names its work, the panel shows its leaf in the working tone and no words.
3. 5s intervention On it The agent says what it is doing: Cutting the lede to two sentences. The comment reads On it, and the same sentence becomes the page’s status.
4. 1m intervention Each new phase gets a new line When the work moves from editing to checking, the agent starts the same update again: checking the page at phone width.
5. 2m observation Answered The revision goes live, the agent's reply reports it, and the status returns to Ready — select text to comment.

Stages of an update

A label beside each comment or widget update records its delivery and handling. Leaf changes it only on recorded evidence and clears it when the required answer arrives. Harnesses skip stages they do not report. Only On it, Replying and Answered relay an act of the agent's own, so only they read in its voice; every other label is what Leaf observed of the update, set in italic.

A comment needs a thread reply; a page-widget obligation needs a version recording its answer. Resolving a thread, editing a draft, or moving a card requires no answer, but the agent still receives the event. A draft edit or card move’s label clears when a version records or replaces it; inside a thread message, it clears when the agent next writes there or the thread resolves. A choice with a Done button gets no label until Done submits it.

Thread readings

A thread appears in several places at once: its card in Threads, its entry in the margin, its row in the Page Map, its row in On Me, and its line in an activity feed. Each place says the same thing about it, so a thread never goes by two names or shows two statuses.

On Me and the agent’s list

The On view gathers outstanding work across the page, using the obligations, to-dos and workflows defined in How it works. A status sentence alone creates no obligation.

On the page, an item On Me is answered only in the widget or thread that asks it, and Leaf adds no control of its own to end one. A widget’s obligation is answered by the actions its x-awaits declaration names, such as a pick, or the Done a multi-select choice offers as its own control. A question in a thread is answered by the user’s reply there or a settling reaction, such as 👍. The agent ends its to-dos with leaf task end, and records the same way an answer the user gave elsewhere, such as in chat. Done history records the outcome, including withdrawn obligations and failed or dropped to-dos.

A thread’s attention identifies which side it awaits, using its updates, questions, and to-dos. The page-wide lists collect that work across threads and widgets. While a thread about a decision awaits the agent, its unanswered update represents the work on the agent’s list; the decision returns to On Me when it needs the user again.

What the panel's line says

The panel's comment field, while empty, is Leaf's one line of words about the page. It says one thing at a time, the first of these that applies:

With a thread open, the field is that thread's reply box. It says whose turn it is beside the leaf, such as Your turn, and Reply with the key that enters it at the line's end; a notice takes their place for its four seconds, and a walk's position follows whose turn it is.

A middle dot joins separate facts, as in In Draw mode · Thread 2 of 5, and a dash attaches a detail to the fact before it. Only words the agent wrote, such as the line it gave its work, read in its voice; what Leaf says itself, such as Stopped 3m ago, is set in italic. Words the user is writing hide the line, while screen readers still hear notices and changes of status. A press the line offers, Reply or the selected words, reads in full ink with the key that makes it, and everything else reads dimmer. The leaf and the tab's icon keep the status's colour throughout, and the leaf's menu holds the status's full sentence. A folded panel shows notices beside the leaf.

Status readings

The server combines the agent’s latest start or status with observed session, turn, and watcher activity. Browser tabs and leaf page state read that same result. All pages uses each serving page’s published activity summary.

• The turn. The harness integration records when a turn starts and ends. Leaf treats it as active while its opening, a start, a status declaration, or a reported step is less than 15 minutes old. Claude Code also reports the session's activity directly, including permission dialogs and interrupted turns. An interruption can therefore mark the turn ended as soon as the user presses Escape.
• The watcher. Claude Code's watch hook, leaf wait, or Codex's adapter registers with Leaf while watching for updates. Leaf treats the agent as available for updates while a watcher runs. A running Claude Code turn can also receive updates through its hooks. With no watcher after a turn ends, Leaf messages a Claude Code session when the next update arrives, so the agent is available too where that message starts a turn: a background job whose worker has retired is resumed with it, and a running session takes it at once where Claude Code's crossSessionInbound setting is accept.
• The start. A start stops counting as active once it is 15 minutes old, or once the turn that wrote it is seen to end, unless Claude Code reports the session still busy with background work, such as subagents it started.

flowchart TD
  accTitle: Activity status by first matching condition
  accDescr: Test each rule from top to bottom and stop at the first match. Otherwise continue to the next rule. An idle page is done, a stopped owner is not on this page, active work is working, stale input is stopped or last checked in, available input is awaits, stalled input needs a terminal nudge, otherwise the agent is away.
  Idle["Page idle<br/>Status: Done with this page"] -->|otherwise| Owner["Owner stopped<br/>Status: Not on this page right now"]
  Owner -->|otherwise| Work["Work active<br/>Status: Working"]
  Work -->|otherwise| Stale["Takes input, start stale<br/>Status: Stopped /<br/>Last checked in"]
  Stale -->|otherwise| Input["Takes input<br/>Status: Awaits"]
  Input -->|otherwise| Stalled["Input stalled<br/>Nudge in the terminal"]
  Stalled -->|otherwise| Away["Status: Away"]

Leaf shows work as active when a start is still current, when the harness reports a step in an active turn, or when that turn has received input requiring an answer. The freshness rules above determine when a start or turn stops counting as active. Input is stalled if it remains queued for two minutes, or if the turn that received it ends without answering. The status doesn't date the agent's line: its hooks remind it to restate a line that has stood two minutes, and the menu's full status says when the line was written.

Notices

A notice stands in the panel's line for four seconds and is announced to screen readers. Simultaneous news shares one notice, such as Not answered · New On Me. Some news is only announced, since something on the page already shows it: an agent message the user hasn't read, which the On Me mark's dot and its margin marker show, and the user's own gesture, which the widget draws where it was made. Opening a page announces only unread agent messages, not its existing activity. The agent starting or stopping work is no notice: the status in the same line says it.

Navigation

Leaf's shortcuts act where focus is. A thread, its passage and its margin card count as one place. Text fields keep typing and caret movement; native controls keep their activation keys. Escape leaves one interaction, browser Back returns to a reading place, and Undo withdraws a recorded action.

? opens the command reference for the current context; menu rows show their own shortcuts. On touch screens, use thread titles, markers, Page Map and the leaf’s menu. The movement rules distinguish walks that wrap from lists that stop.

Named destinations and visible hints

Reading and text search

Threads and work waiting on the user

t / Shift + t walk open threads in page order. Focus on a thread or its accompanied passage makes that thread the origin. Moving elsewhere changes the origin; Leaf keeps no separate “last thread” cursor.

Resolving and replying

r resolves the focused open thread. A thread opened from Threads advances to the next open thread in page order, or the previous at the end; with none left, it returns to the list. A margin card moves on to the next thread at its passage, or the one before, and closes onto its passage with none left. An embedded thread folds in place.

Panels and Escape

Back and Forward

A successful navigation step to a destination that is not fully readable adds a return stop where the user stood, so Back returns to the item they were on: after t then m, Back returns to the thread, and Back again to where they were reading before t. A fully readable destination adds no stop.