How Leaf works

Pages, core, and packages

A page is the document the user reads and acts on. Its HTML includes widgets such as choices, charts, and boards. A passage identifies the words a comment concerns.

Leaf’s core supplies shared state, events, and page lifecycle. Packages contribute widgets, domain behavior, styling, and authoring instructions. A page selects packages and a theme; Leaf combines those with its core declarations and assets into the page’s layer.

flowchart TD
  accTitle: How Leaf composes a page
  accDescr: Leaf core and selected packages compose the layer. The authored page runs with that layer and the serving Leaf's browser runtime.
  Core["Leaf core"]
  Packages["Selected packages<br/>and theme"]
  Layer["Composed layer<br/>Registry, theme, widgets and modules"]
  Browser["Authored page<br/>Running in the browser"]
  Core --> Layer
  Packages --> Layer
  Layer -->|With Leaf's browser runtime| Browser

The layer’s registry gives agents, checks, Python, and the browser a shared description of its elements and capabilities. It declares valid markup and the meaning of widget actions; widget modules implement their behavior and presentation.

Responsibilities and state

Authored content starts the page’s state; the append-only log records changes. Each reading applies the events still in force. Undo records which gesture it withdraws, leaving the original event in history. Focus, scroll, selection, and open disclosures remain browser-local interaction; an unsent draft can be recovered from browser storage.

The Leaf serving, checking, or exporting a page supplies its current runtime and composes its layer from the recorded selection. Historical revisions keep authored content and recorded decisions, while the serving Leaf supplies the code that draws them.

The exchange

An agent proposes queue policies for an importer. A choice or comment the user sends is an update. A comment opens a thread, the conversation about its passage, widget, or the page as a whole. To make this choice yourself, try the queue policy practice in Workflow.

1. The agent prepares the page. It writes the alternatives, checks the page, and opens its link.
2. The user chooses “Pause the producer”. The browser draws that choice immediately. The server validates the action against the registry and appends its meaning to the event log. The server’s next reading supplies the choice’s effect on obligations and work owed.
3. Leaf delivers the update. The harness brings the choice and its context into the agent’s session. Its workflow tracks delivery and work, distinguishing receipt from the agent explicitly starting it.
4. The agent incorporates the decision. It revises the proposal to use backpressure and stamps a version that records the choice in the markup. A revision captures authored content; a version names a revision the user can revisit. If the update was a comment, the agent answers in its thread.

An obligation records an input or answer owed and whose turn it is: first the user’s queue-policy choice, then the agent’s incorporation of that choice. A to-do records work the agent owes, such as measuring the importer’s throughput. Obligations and to-dos supply the On me and On agent lists; threads keep the conversation, and workflows track the handling of updates.

The same link shows the revised proposal. Stable widget ids keep recorded choices attached across edits. When an edit changes what a decision was about, the author explicitly marks it restated and explains why the decision no longer applies. State and records defines these concepts; Revisions explains their continuity.

Find the right guide

Author, hand over, and respond

The harness supplies the agent’s tools and runs its turns. This example follows a queue-policy review from the first page to the answer. Command inventory lists the available operations; Harness connections explains delivery and receipt.

leaf page init --package diagram ./review
# Write ./review/index.html with the harness's file tools.
leaf page check ./review --render
leaf page stamp ./review --text "Queue policy ready for review"
leaf thread create ./review --obligation --text "Which queue policy fits the importer?"
leaf server start ./review

leaf thread reply <answer.ref> --ephemeral --text "Checking the importer's queue policy."
leaf page state ./review
leaf page state ./review <thread-id>
# Revise ./review/index.html.
leaf thread reply <answer.ref> --done --text "The importer policy is updated."
leaf thread create ./review --obligation --text "Does the revised policy match the workload?"

<lf-options id="queue-policy" choose>
  <lf-option id="drop-oldest" chosen>Drop the oldest record</lf-option>
  <lf-option id="block-producer">Pause the producer</lf-option>
</lf-options>

leaf task start ./review <event-id> --text "Recording the chosen queue policy"
leaf page state ./review
# Add chosen to the picked option in ./review/index.html; check and review.
leaf page stamp ./review --text "Queue policy: drop the oldest record"

{
  "handling": {
    "h1": "Read the thread context before answering.",
    "h2": "Write the answer with leaf thread reply using its answer.ref."
  },
  "events": [
    {
      "id": "9d41b20f",
      "kind": "comment",
      "handling": ["h1", "h2"],
      "answer": {
        "kind": "reply",
        "parent": "9d41b20f",
        "responds": "9d41b20f",
        "ref": "6ba31df0:0:9d41b20f",
        "writer": "agent"
      }
    }
  ]
}

leaf data set ./review queue-metrics --file ./metrics.json

leaf task create ./review page --title "Check the importer policy"
leaf task start ./review <todo-id> --text "Checking the importer under load"
# Run the check and put its result on the page.
leaf task end ./review <todo-id> done --text "The load check is recorded on the page"

flowchart TD
  accTitle: Checks before a turn ends
  accDescr: Check in order, taking the first match. A new update needing an answer with no later watcher is delivered into this turn. Otherwise an already extended turn ends. Otherwise an unanswered update not started this turn, or an open page with no watcher, continues the turn. All other turns end.
  New["New answer needed<br/>No later watcher<br/>Deliver update; continue"]
  Extended["Turn already extended<br/>End turn"]
  Pending["Delivered update unanswered<br/>Not started in this turn<br/>Name update; continue"]
  Watching["Page open, no watcher<br/>Arrange delivery; continue"]
  End([End turn])
  New -->|otherwise| Extended
  Extended -->|otherwise| Pending
  Pending -->|otherwise| Watching
  Watching -->|otherwise| End

Agent instructions and notices

The workflow, including what the agent records for the user, lives in the skill, which the agent reads at the start and again after a compaction. A rule for one element or one kind of update travels with it, so the agent reads it when it acts. Problems the agent can't see for itself, such as an update it hasn't answered, arrive from Leaf's hooks.

leaf page instructions ./review --use lf-diagram | jq -er '.author'

This prints how to author a diagram. The repository scores each change to the skill and the packages' instructions with evals: cases a headless agent completes in Claude Code and Codex, run on the old and the new instructions.

Agent command inventory

The table groups Leaf's commands by what the agent uses them for, with arguments omitted. Running leaf alone lists them all, and each command's --help gives its syntax. The examples above show commands for publishing a page and answering updates.

Harness connections and receipt

Claude Code’s background Stop hook watches between turns and wakes the agent; its prompt hook puts the update into the new turn. Codex’s adapter queues the update as the next message, or starts a turn when Leaf is an App Server client. Pi’s experimental extension runs inside Pi. Each route supplies the same delivery format and says who confirms receipt.

1. Confirm receipt separately from transport. Leaf counts an update as received only when the agent or harness confirms it. A harness discards output from a timed-out hook, so the hook confirms well before its deadline and passes a complete delivery into the turn only after confirmation.
2. Use a pointer when the whole delivery cannot fit or be confirmed. A delivery too large for the turn’s context, or one the hook could not confirm in time, arrives as an id. leaf delivery read <delivery-id> confirms nothing; the agent follows every next command, then runs leaf delivery ack <delivery-id> as the envelope’s acknowledge field directs.
3. A direct wait confirms on its next call. A Codex task running its own wait uses leaf delivery ack <delivery-id> && leaf wait. Until then, the events remain available to the next wait, in case output was lost or cut off. Stages of an update names the evidence for Delivered on each route.

On every route the agent can answer with leaf thread reply <answer.ref>. One task can receive updates by several routes, and each delivery says how to confirm it and how to answer.

Revisions

When Leaf reads changed, valid page source or dependencies, it captures an immutable revision and makes it live. Identical captured inputs reuse a revision. leaf page stamp adds a changelog entry, a version number and a stable address such as /versions/v2.html. The live URL follows revisions; a tab displaying v1 stays on v1.

An open tab installs a live revision while preserving reading position and active controls, waiting where it would interrupt the user (Live revisions). A comment follows its passage, or its surviving section if the passage disappears. If neither can be identified, the thread detaches rather than choosing unrelated text.

A request to permit an action is an ordinary decision: an lf-options group whose options take the action its heading and prose describe or keep things as they are, so declining is an answer too. Its pick answers the widget's obligation on On me, and choosing it again reopens it. Each request is independent of other unanswered widgets and page stamps, and the pick persists with the widget's id across unrelated edits. When the action or evidence changes enough to invalidate that permission, the author explains the change and marks the widget restated. A request that depends on another decision is presented after that decision, once the action to permit is concrete.

Choose Publish the report, then choose it again. The request changes immediately, and the activity feed records the pick and its withdrawal.

Checks before a revision goes live

Before making a revision live or stamping a version, Leaf validates the HTML structure, element declarations, dependencies, and recorded user decisions. An invalid save keeps the last valid revision live and reports the error. leaf page check --render additionally opens the page in Chrome in both color schemes to check for console errors, invisible widgets, and horizontal overflow.

Decisions across revisions

A pick or drag records a structured action, shown immediately and delivered alongside comments. Once accepted into the log, it survives reloads, other tabs, and later revisions. The event log reference shows how actions and undo determine current state.

An edit preserves recorded choices unless it explicitly changes their basis. The agent marks an affected element restated and explains why in the version note. Otherwise the choice still applies. Wording, labels, placement and vocabulary can change; the log keeps each action's original meaning.

z withdraws the user's latest action, naming that action and how long ago it was made. Where that action is out of view, or the agent has already picked it up, the first press shows it and the second takes it back. Either way it leaves the user at what it took back, so undoing a resolve opens the thread again where they had it open. Each undo appends an event naming its target, so the recomputed result survives reloads.

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. Its progress message or leaf task start names the update or to-do it is handling and the work it is doing. 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 posts leaf thread reply <answer.ref> --ephemeral --text "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 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.

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 State. 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.

Any widget can ask, whether bundled, from a package or the page’s own, by declaring x-awaits in its registry entry, which names the actions that answer it. To ask about content that asks nothing, such as a paragraph or a chart, or to leave the user a step such as trying a build, the agent opens a thread on that content or the page with a message sent with --obligation, and the user’s reply answers it. Nothing goes On me that neither a widget nor a thread answers, so no item carries a generic Done, and Leaf adds no answer to a widget beyond those the widget declares.

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.

Where the agent's messages appear

The agent writes progress messages, statuses, replies, and version notes. Leaf adds observations about delivery and activity. These commands reach different surfaces; starting work places its line both in the panel and beside the update or to-do.

Written by the agent

• leaf thread reply <answer.ref> --ephemeral Names the upcoming work in the user’s thread before reads or edits. It sets the page’s status and the comment’s Working label, then folds behind Show 1 progress message when the answer arrives.
• leaf task start … <id> --text "…" Names the current operation for an update or to-do, such as running the browser suite. Its line remains beside the thread or widget until answered or ended. The panel’s leaf and tab icon take the status’s colour; All pages repeats its line.
• leaf page open … Leaves feedback open and clears starts while keeping to-dos. It creates no obligation. Questions that need an answer belong in a thread message with --obligation, so On me opens the conversation.
• leaf page close … The agent has finished with the page, and the status reads Done with this page (Wait for updates or finish says when Leaf refuses it).
• leaf thread reply <answer.ref> Answers the user’s comment and clears its label. --done delivers the result; --obligation asks the user back; --todo promises work that stays on On Claude until ended.
• leaf thread reply <page> <thread> A later message in a thread already answered, such as the result of work the first reply promised.
• leaf thread reply … --obligation Opens a question on On me and makes the thread read Your turn. A reply or settling reaction answers it at once, so On me clears without waiting for the agent. A step the user is to take, such as trying a build, is asked the same way. The agent can end it with leaf task end as answered elsewhere or withdrawn.
• leaf thread reply … --obligation message:<id> Puts a question the user's reply left standing back on On me, such as when they asked something back. It keeps its id and words, so a plan step naming it reads open again, and stands on this message.
• leaf thread create, leaf thread edit, leaf thread resolve A thread the agent opens on a passage, a message it corrects, marked edited, or a thread it closes (✓ Resolved by Claude).
• leaf page stamp --text "…" Names a version and its note in Versions. The live page updates and the panel says Updated to v4. A tab on an earlier version stays there; its version notice offers Latest.

leaf page report records a widget state change. A widget supplied by an optional package can use these reports to show a background worker's progress.

When the agent says what it is doing

• When an update arrives. The agent names the requested work before starting it, or answers immediately when no work is needed. Each delivery repeats this instruction beside the applicable events.
• When the work changes. A new subject or phase—reading, editing, testing, or waiting on a result—gets a new line by starting the item again. Every start names its operation.
• During long work. Background workers keep the agent free for the user’s next comment. The start names the running work beside its update; the agent renews it when a worker reports (Stop hook checks).
• When it is the user’s turn. A waiting status names the answer or decision wanted.

The conversation loop reference is the agent's copy of these rules.

The work plan

For work with several steps, the agent can publish an outline, which the On view's list of the agent's work discloses from the plan's progress and On me can group by. It shows the goal, the current step, and later steps, including those waiting on the user. A step can name an existing to-do or obligation and follow its title, owner, and state, or carry a title and state the agent maintains.

leaf task plan ./review <<'EOF'
[{"depth": 0, "title": "Review the queue policy", "state": "working"},
 {"depth": 1, "item": "<todo-id>"},
 {"depth": 1, "item": "widget:queue-policy"}]
EOF

Browser runtime

The browser runtime upgrades Leaf elements, draws threads and shared controls, sends updates, and keeps the page current. Its inputs meet in one read-only state.

flowchart TD
  accTitle: One state feeds every renderer
  accDescr: Authored initial values, the server's reading and this tab's pending gestures combine into one current state. Renderers select the parts they read and draw the interface.
  Inputs["Authored initial values<br/>Server’s recorded state<br/>This tab’s pending gestures"] --> State["Current state<br/>Values · threads · obligations"]
  State -->|selectors| Renderers["Widgets · threads<br/>Leaf panel · page marks"]

The server supplies actions in effect for the displayed revision, threads, obligations and activity (Current state). The browser applies them to authored values and adds only what pending gestures decide by themselves.

Loading the runtime

Startup prepares a stable page before enabling its controls. Page loading distinguishes usable controls from the arrival of saved state.

flowchart TD
  accTitle: Prepare the page before controls arrive
  accDescr: Before first paint reserve geometry and capture early keys. Then start the state request, load the registry, capture authored values and upgrade the page's elements.
  Reserve["Before first paint<br/>Reserve space · capture keys"] --> Prepare["Start state request<br/>Restore arrangements<br/>Load registry"]
  Prepare --> Capture["Capture authored values"]
  Capture --> Upgrade["Import widget modules<br/>Upgrade elements"]

Pending browser updates

A pick, drag or comment enters an ordered pending list. Its result appears in the sending task, before the next frame: the option is selected, the card moves, or the comment appears reading Queued for Claude (Stages of an update). Sent words leave the input but remain in the draft store until accepted.

flowchart TD
  accTitle: A gesture reaches the shared record
  accDescr: Draw a gesture's local result immediately, send it in order, receive the accepted record and state, then release the pending entry only after that state is presented.
  Gesture["Gesture<br/>Draw its local result"] --> Send["Send in order<br/>POST /api/event"]
  Send --> Accepted["Server accepts<br/>Record + current state"]
  Accepted --> Presented["Present server state"]
  Presented --> Release["Release pending entry"]

Freshness checks and state reads

flowchart TD
  accTitle: A changed freshness token triggers a state read
  accDescr: A finite news request checks freshness. A changed token triggers a state request; an unchanged token keeps the current reading without another state request.
  News["Check freshness<br/>GET /api/news"] -->|token changed| Read["Read current state<br/>GET /api/state"]

Drawing current state

Computing state and drawing it are separate. Widgets, threads, the obligation view, panel and page marks register as renderers. Each state has an epoch number. Renderers report when they have presented it; those reports stay outside state, so a slow or failed paint cannot change the facts.

flowchart TD
  accTitle: Presentation follows the DOM it needs
  accDescr: Page marks may add text; threads locate passages in that text; obligations may live inside those threads. These presentation dependencies establish the drawing order.
  Marks["Page marks<br/>May add text"] --> Threads["Threads<br/>Locate passages in that text"]
  Threads --> Obligations["Obligations<br/>May live inside those threads"]

A renderer may defer paint during an active drag or edit. These operations wait for presentation, not merely computed state:

Browser-owned state

Focus, scroll, selection, open disclosures, unsent text and active drags live outside shared state and the log. DOM nodes hold them; Data lifetime names browser stores preserving some across reloads.

Live revisions

flowchart LR
  accTitle: Executable identity chooses the revision path
  accDescr: A revision with the same executable identity patches the document, preserving unchanged nodes. A changed identity starts a fresh document with the new executable graph and current state.
  Same["Same<br/>identity"] --> Patch["Patch the<br/>document"]
  Changed["Changed<br/>identity"] --> Fresh["Load a fresh<br/>document"]

Installation waits during comment or reply writing, passage selection, card dragging, a pending update’s server response, or an open version menu. Latest in the version notice installs the waiting revision immediately.

Server lifetime

The HTTP server exposes the page directory to browsers. A session-started server stops when no live session claims the page; a claim names the recipient of its updates. A server started from a bare shell or with --lifetime persistent runs until leaf server stop.

On leaf.page, a private browser session gets a hosted agent environment using the same page and event machinery (How leaf.page works).

Addresses and access

A local session binds to loopback; an SSH session uses its SSH destination. A local server's URL includes an access key shared by every Leaf page on that machine. The browser keeps it in a cookie. Anyone with the key and network access can read and act on those pages.

For an unreachable address, restart with leaf server start PAGE --host NAME, naming a host the browser can reach. Leaf uses existing networks and creates no public tunnel. The serving reference covers addresses, authentication and lifetime.

Offline exports

leaf page export PAGE -o FILE captures a stamped version, its resources and recorded state in one HTML file. Reading controls and page-owned code work offline; new Leaf choices, comments, Undo and thread interactions need the served page. An agent need not be running to record a choice on a live server. Pages containing live samples cannot export.