Last time I argued that an agent should not wait for the context window to fill. When a unit of work closes, the model says so, and the host replaces that unit’s turns with a short result and archives the originals to disk. I called it a fold, and I left compaction in place as the emergency path.

This post is about what the prompt looks like after a few hundred folds. Each closed unit now stands in the prompt as one title: a single line, about 60 tokens, saying what the unit was and how it ended. The rest of the fold result from the last post, the user’s words and the model’s closing message, stays with the archive on disk. So after enough folds the prompt has three parts: the standing part (system prompt and tool list), a flat list of titles, one per closed unit, oldest first, and the open tail where the work is happening.

The list grows by one line per unit and never shrinks. My longest session so far has 455 closed units. Its title list is 82 KB, about 23k tokens, and it sits in front of every request. That is still under the cap I give it, a tenth of the context window, so no real session has yet needed what this post describes. But a session that runs for long enough will, and the mechanism has to be right before that happens, because the cost of getting it wrong is paid on every request.

The only move that shortens the list is a merge: replace a few adjacent titles with one line that stands for them. Everything that follows is about three questions that one move raises. When do you merge, which lines, and into what shape. The answers come from the prompt-cache cost model, from two measurements on real sessions, and from a piece of structure that makes the whole thing cheap. The rule that comes out is small enough that I wrote it in Bend, a language whose checker verifies proofs, and proved its promises.

I will call the title list the cover from here on. It is the one page you read before opening the book.

What a change to the prompt costs

The cover sits in front of the open tail, so any edit to it is an edit in the middle of the prompt. The price of that is set by prefix caching: the provider bills the part of the prompt that matches the previous request at about a tenth, and everything after the first changed byte at full price. On my sessions, about 60% of input tokens land in the cached part.

The cost model for one request is one line. With $|P|$ tokens in the prompt and $c$ of them shared with the previous request:

Changing a byte at position $p$ re-bills everything after $p$ once. A fold edits the tail, so it is nearly free. A merge edits the cover, which is before the tail, so it re-bills the rest of the cover and the whole tail.

In the last post I simulated the timing of folds on one session and found that the totals came out within about a fifth of each other. I have since replayed 168 sessions, every one with at least 20 model calls, under four schedules and a no-fold baseline, with a 100k-token window. The cost counts a cached token as a tenth of a full one, and I give it relative to compaction. A prefix rewrite is a request whose prompt changed somewhere before the tail, so the cache missed from that point on.

Two things in that table decided the when.

Folding at close is the cheapest schedule, by 18% over compaction, and folding from the front when forced is the most expensive by far. Position is everything, exactly as the cost model says. More rewrites, each at the tail, beat fewer rewrites at the front.

The third row is the one I had been afraid of. Merging titles changed the bill by under 1% and added zero rewrites. The reason is that a merge was scheduled on the same event as a close. A close already rewrites the tail of the prompt, and the cover is right in front of the tail. So a merge that rides on a close pays only for the rest of the cover, which is capped at a tenth of the window. A merge on a turn of its own would pay for the tail again.

So: merge only when a unit closes. Never on a turn of its own.

Aligned blocks: a line is written once

“Replace adjacent titles with one line” allows any run of lines. Before measuring what a merge costs, I need to say which runs are allowed, because the answer is what keeps merging cheap.

Think of a ruler whose marks double: 1, 2, 4, 8. A mark of size 2 appears only at even positions, a mark of size 4 only at multiples of 4. Cut blocks only along the marks: a block’s size is a power of two, and its start is a multiple of its size. Call such a block aligned. Number the closed units in order, 0 to $n-1$. A block of size $2^j$ is at level $j$; a unit on its own is a block at level 0.

Alignment buys one thing: every block is exactly two blocks of the level below, its halves. [0–7] is [0–3] and [4–7]. There is never a [0–5] or a [3–6]. So the aligned blocks over $n$ units form a forest of binary trees, and any two of them are either disjoint or nested.

A view is a set of blocks that partitions $0..n-1$ with no overlaps, where every block has a line. The prompt renders a view as one line per block, oldest first. That rendering is the cover.

Alignment is what makes a merged line written once. A line for a block comes from two possible inputs: the titles of its units if the block is small, at most $R = 16$ units, which is about 1,000 tokens of titles and what a cheap model reads in one go; or the lines of its two halves if it is bigger. Both inputs are immutable. Titles are fixed when the unit folds. A half’s line, once written, is never rewritten, because its own inputs never change. So each block gets its line at most once in the life of the session, and with $n$ units there are at most $n - 1$ merges, which bounds the number of lines ever written.

Without alignment that falls apart. Write a line for [0–5], then decide later you want [2–9]. They overlap, the first line is useless as an input, and you read eight titles again.

A merge is now precise: two adjacent blocks in the view that are the two halves of one parent are replaced by the parent. [4–7] and [8–11] are adjacent but [4–11] is not aligned, so they can never merge.

The coarsest view is the binary expansion of n

How short can a view get? Thirteen units, merged as far as possible: the biggest aligned block from 0 is 8, then from 8 the biggest that fits is 4, then 1. So $13 = 8 + 4 + 1$ and the coarsest view has three lines. That is $13 = 1101_2$: one line per one-bit of $n$. No view can have fewer lines, because every view writes $n$ as a sum of powers of two and the binary expansion is the shortest such sum.

This number is tiny. For $n < 16$ it is at most 4 lines, for $n < 4096$ at most 12. Whatever the session’s length, the cover can be squeezed to about a dozen lines.

And closing a unit is a binary increment. The new unit is a level-0 block at the end of the view. If its left neighbour is also at level 0 and they are halves of one parent, merging them makes a level-1 block, like a carry. The host keeps the forest as a list of trees newest first, and a close is a push with a carry. Alignment is the shape of the data, not an arithmetic check.

What a merged line costs the reader

Money says when. It says nothing about which lines to merge, because the cost of a merge does not depend on which lines it touches. What does depend on that is what the model can still find afterwards.

First, how often does the model need a folded unit back at all? In the last post this was my biggest unknown. I now have the count. In the five longest sessions, about 670 folds between them, the model went back into an archive 6 times, which is 0.9%. Four of the six were a literal: a command line, a hash, a host name. The other two were the same mistake twice: the first turns of a session were a design discussion, folded one turn at a time before anything was built on them, and the title said that a structure was decided and not what was decided. That is the “folds too early” case from the last post, and it has a rule now: a turn that decides a design is not closed until its decisions are in a file or in the title.

Also worth saying: the model never found anything by reading the cover. Every genuine re-open was a grep on the archive path that the fold result names. The cover is for orientation, what happened in this session and in what order. Finding a detail is grep’s job.

Then, what does a merged line hide? I took the same five sessions and had a small model write a line for every aligned block in them: from the titles for blocks of up to 16 units, from the two halves’ lines above that. Then I wrote 184 questions, each asking for one concrete detail from one unit, and had another small model answer each one while looking only at a cover, by picking the line to open and, if that line was a merged block, zooming down through its halves. A question counts as found when the model reaches the unit that holds the answer.

Three findings, and they set the other two answers.

The cost is the block’s size, and nothing else. With no merging at all, the found rate is flat across age: no trend over nine age bins, from the newest units to the oldest. Once lines are merged, the misses sit exactly where the blocks are. The schedule chooses which units pay the price, not how big it is. Past 64 units a line is a label with nothing behind it. And the loss grows steeply with size: going from 1 to 2 units costs four points, from 8 to 16 costs fourteen, from 64 to 128 costs everything. One big block loses more than many small ones put together.

A bigger budget is better, and cheap. Capping the cover at a size and merging down to fit, the found rate rose from 29% at a 1 KB cap to 69% at 128 KB with no plateau. The cover’s share of the session’s prompt spend was under 1% at every cap from 8 KB up, because the cover is almost always a cache hit. Money does not decide the budget. But there is a floor: at a 2 KB cap the 455-unit session rewrote its cover 94 times, once every five closes. Why is in the section on the floor below.

The order does not measurably matter. Two orders for choosing which pair to merge first, age over size and smallest first, both defined under the rule below, came out at 43.7% and 46.8% found, which is inside the small model’s own run-to-run noise. The order is a parameter, and I pick it by reasoning, not by data.

The rule

The host holds one thing, the view: a list of blocks, oldest first, each with a line, that together cover units $0$ to $n - 1$. Two events change it, and one reads it.

close(title):                       # the model folded a unit
    append block [n] at level 0, with `title` as its line
    n += 1
    settle()

settle():
    if tokens(view) <= B: return                  # within budget, do nothing
    while tokens(view) > L:
        pairs = adjacent blocks in view that are the two halves of one parent
        if pairs is empty:                        # the view is at its floor
            report it; return                     # never drop a unit
        (a, b) = the first pair by rank
        if parent(a, b) has no line:
            write(parent(a, b))                   # a cheap model; its whole prompt is the inputs
        replace a, b in view by parent(a, b)

write(block):
    inputs = titles of its units        if the block has at most R units
           = lines of its two halves    otherwise
    one line, at most t tokens, written once and never again

zoom(block):                        # read-only, outside the prompt
    a block  -> the titles of its units, in order
    a unit   -> its archive

The names:

Four things to notice.

Close is the only event that touches the cover. A close has already rewritten the tail, and the cover sits right in front of it, so a merge made during the same settle costs only the rest of the cover.

A line is written only when settle is about to merge the block. No measured session has needed a merge at the budget below, so a line written early would usually never be shown, and it costs real output tokens. Lazy writing means every line that exists is a line that was displayed.

Settle never invents and never drops. A pair whose parent has no line yet is written first, then merged. If no pair can be merged, the view is reported as stuck, and every unit stays.

Zoom is for reading in order, not for finding. A line is written, for now, as a summary of what has lasting effect. Whether it should be an index instead is an open question at the end.

Why settle to half the budget

The obvious stopping point is “just under $B$”. It is wrong. One close later the view is over $B$ again, and the cover is edited on every close, which means the tail is re-billed on every request.

Settling to $L = B/2$ leaves half the budget free, so the next settle is at least $B/(2t)$ closes away. Over $n$ closes the cover is edited at most $2nt/B$ times. With a 270k-token window, a budget of a tenth of it, and $t \approx 60$, that is about 225 closes between edits. The two thresholds are different on purpose. It is hysteresis.

The floor

A view cannot have fewer lines than the one-bits of $n$, and in the worst case, $n = 2^d - 1$, that is $d = \lfloor \log_2 n \rfloor + 1$ lines. If $L$ is below that, settle merges everything it can and still stops above $L$, a few lines under $B$. Then the next few closes push it over again. That is where the 94 rewrites at a 2 KB cap came from: $455 = 111000111_2$ needs six lines just for its trees, and a 2 KB cap held about ten. The condition is

which is about 1,400 tokens for $n < 4096$. A budget of a tenth of the window is twenty times that, so the floor never binds. It says what a budget must not be.

The constants

Rank

Settle may face several mergeable pairs, and the rank decides which goes first. The proofs below hold for any strict order, so this is a policy, not part of the rule. Two orders have names.

• Smallest first, oldest among equals. A bigger block is formed only when no smaller pair is left, so the largest block in the view is as small as the line count allows. This is the default, because the measured cost is the block’s size.
• Age over size: for the pair’s parent, its age divided by its size, largest first. A pair of single titles that ended three units ago is as ready to merge as a pair of 8-unit blocks that ended 24 units ago. The oldest lines come to stand for the most units, so the view keeps about the same number of lines per doubling of age.

The data separates them by 3 points, in favour of smallest first, within noise. Of the six real re-opens, four went to the oldest tenth of the session, the early design decisions. Nothing I have says old units are asked for less.

With a budget of 8 lines, smallest first, and eight single lines in the view, the ninth close goes over budget and settle aims for 4. It pairs [0]+[1], [2]+[3], [4]+[5], [6]+[7] down to five lines, then [0–1]+[2–3] down to four: [0–3] [4–5] [6–7] [8]. Five lines written, one edit to the cover. Drop the budget to 3 and the floor shows up at $n = 7$: the view is [0–3] [4–5] [6], three lines, nothing left to merge, and $L = 1$ is out of reach. At $n = 15$ the coarsest view itself has four lines, more than the budget.

Where the shape comes from

The shape of this rule is not mine. It is Victor Taelin’s, from OptMem and OptChat : a log that is only appended to, a binary tree of one-line summaries over it where each node is built once from its two halves, a view that is a list of tree nodes covering the whole log with recent lines fine and old lines coarse, and a zoom that opens a line into the two it was made from. The age-over-size order is his too. It comes from a trick in his rollback netcode, where the saved game states are kept as a binary counter, dense near now and sparse in the past, so that the list stays about $\log_2$ of the ticks long. The three designs differ in what a leaf is:

Everything about the tree carries over unchanged. Moving the leaf up to a closed unit changes two things, and both are about cost. A unit is already a summary of its turns, written by the model that did the work, so the tree starts one level higher and no cheap model ever reads a raw transcript. And a unit closes only at the tail, so every event that reaches the tree is already a tail rewrite. That is why the two timing choices above go the other way from OptChat. OptChat merges when the view passes a size and builds every node in the background as soon as its halves exist, which is right when every message is a leaf and nodes are cheap to build. Here a merge waits for a close, and a line waits for the merge that will show it.

What Bend proves

The rule is small, and its promises are the kind that a test can only sample. So the core is written in Bend as a total function, and the promises are laws, theorems that Bend’s checker verifies for every input. The rank is not in the proof. It is a parameter, and the laws hold for any strict order.

The core keeps the forest, newest tree first, so that “aligned” is the shape of the data rather than an arithmetic claim. Each block records whether its line has been written, and a block whose line is missing can never be merged: the rule invents nothing. Thirteen laws, in seven groups:

Every law is also run at concrete inputs before its proof is trusted, and each law has a mutant, a deliberate break of the rule, that must falsify it. What the proof buys is portability. Any host that drives the core gets the same rule with the same guarantee: its cover cannot drop a unit, fold an open one, invent a line, or exceed the budget while a merge is still possible.

Compaction is still there, for one case

The cover now has a bound. The open tail does not. Between closes it grows with the work, and the host’s fold card only asks the model whether something behind it is finished. A unit that will not close, a long debugging session with nothing settled yet, can grow toward the window on its own.

That is what compaction is for now. It fires on the water level, as it always did, but its reach has shrunk to the tail: the standing part and the cover stay in place, byte for byte, so the cache prefix survives, and the summary replaces only the part that has no title yet. In a session that folds as it goes, that part is the current unit, not the whole conversation.

The three mechanisms stack, and each is cheaper than the next because it fires later:

An ultra-long session is one where the third row never fires. In the 455-unit session neither the second nor the third did: its 82 KB of titles fit under the budget without a single merge, and no unit grew to the window on its own.

What I don’t know yet

• The attention cost of a long cover. It is the reason $B$ is a fraction and not “everything”. The found-rate experiment does not measure it. The test I need is the same open-tail question answered with a 1k cover and a 23k cover in front.
• What is asked for, by age. Six real re-opens is a small count, and four went to the oldest tenth. The rank waits on this. Smallest first is the default meanwhile.
• The writing recipe. Counting only whether the model’s first pick was the right line, before any zooming: 71% for a line written from one or two titles, 60% from 8 to 16 titles, 40% from two halves’ lines, and 0% two levels further. The writer is asked for a summary, what has lasting effect. The reader needs an index, what is in here. That is a different line, not a different schedule, and it is probably the bigger lever.
• Where the standing part ends. The tool list is prefix too, and a tool list that changes mid-session is the most expensive rewrite there is. Same cost model, next post.

In the previous post I explained why my agent keeps the evaluator of opencode’s codemode package and replaces its scheduler with a core written in Bend . At that point the scheduler was a list of candidate laws. It is now built, proved, and wired into the evaluator.

Along the way I found something I had not expected. opencode’s codemode does not run async functions as asynchronous functions. It runs them inline, to completion, at the point of the call. I first read that as a missing feature. After more reading I think it is a deliberate design, and a sensible one. I still chose differently.

This post covers both parts: how the scheduler was designed as a proved core, and why my agent makes async real when opencode does not.

What the scheduler decides

A codemode script is JavaScript that the model writes. It calls tools, and every tool call returns a promise:

const files = await Promise.all(paths.map(p => tools.read({ path: p })))

The evaluator turns syntax into values. The scheduler decides everything about promises:

• when a tool call starts and when it queues;
• what await, Promise.all, Promise.allSettled and Promise.race deliver, and when;
• which calls a race, a timeout or an abort interrupts;
• what the end of the script waits for;
• which failures nobody awaited.

In my agent the scheduler is a pure state machine in Bend. The evaluator reports what the script does as an event, the core answers with commands, and a thin TypeScript layer performs those commands:

step(state, event) -> (state', commands)

events:   EvCall  EvAsync  EvOk  EvErr  EvDone  EvThrew  EvWait  EvReturn  EvAbort
commands: Made  Spawned  Waiting  Start  Interrupt  Wake  Finish

The core knows two kinds of promise, numbered by one counter in the order the script makes them:

• Tool: a tool call. It queues, holds one of the concurrency slots while it runs, and counts against the call budget.
• Fn: one execution of an async function. It runs from the moment the evaluator reports it until the function returns or throws. It never holds a slot, never queues, and is not counted against the budget.

The script itself has three modes. Live: the script is running. Draining: the top-level script has returned, but tool calls and async executions are still going. Their waiters still resume, and new tool calls from them are still accepted. Over: the script finished or was aborted, and the core does nothing from then on. Finish comes exactly once, when no tool call is queued or running and no async execution is going. It carries the returned value and the list of failures that nothing awaited.

That last list matters more than it looks. If a script forgets to await tools.post(msg), it returns "done" while the post failed. Without the report, the model believes the message went out.

Getting the laws right took two drafts

The first draft had 13 laws, each about one behaviour: the concurrency limit, the budget, race, abort, and so on. Proving them stalled after 4. The cause was the shape of the laws, not the difficulty of the proofs. Every law took “the state is valid” as its premise, and “valid” was defined loosely enough that one law (the budget) turned out to be false under it. Strengthening the invariant meant re-proving everything that used it.

I took the problem to a stronger model and asked for a review of the laws themselves. It suggested three layers:

1. Pure decisions. For example: given the members of a Promise.all and their states, does it wait, reject or fulfil? These are small functions with exact laws (vd_all, vd_settled, vd_race). They need no premise about the state at all.
2. One step. What a single event does, under a small, local premise (“the ids are distinct”), not under a global invariant.
3. The whole run. One law, sc_inv, says that every state a run can reach satisfies the invariant. Only this layer needs it.

The redraft had 30 laws, and they were proved. I proved them by sending several prover agents out in parallel, one per group of laws. This worked, but it produced a 15,241-line proof file. Three of the provers had each built their own copy of the same proof framework, about 4,400 lines in total. None of them knew the others existed, so each one invented the same idea alone.

The lesson went into my Bend workflow notes: when several provers work on one unit, build the shared lemma layer first and do not let anyone copy a lemma.

The larger fix was in the laws. Six of the step laws (start, interrupt, cut, keep, frame, race-cuts) turned out to describe pieces of one relation: how a single step may move each existing promise. So I replaced them with one law, sc_calls. For every promise that existed before a step:

• an ended promise stays exactly as it ended, with no command;
• a tool call that lost a race this step ends Interrupted: one Interrupt if it was running, no command if it was queued, and it never starts;
• any other queued promise stays queued, or starts with exactly one Start;
• any other running promise keeps running;
• an async execution is never interrupted.

Each line of the law carries its reason. A call marked running with no Start never reaches the tool, so the script hangs. A second Start runs the tool twice. A race loser left in the queue starts later and runs a tool whose result nobody will read.

The unit now has 25 laws and an 8,027-line proof. It also has 35 mutants: deliberately wrong versions of the core, and each must break the proof of the law it targets. Every law is also falsified on random states before it is proved. A wrong law is cheaper to find with 3,000 random cases than with a failed proof.

Wiring it into the evaluator

I wanted a clear boundary between the scheduler and the evaluator. The evaluator is opencode’s code, and it should stay easy to update from upstream. So one TypeScript module owns all scheduling. It holds the fibers, the waiters’ Deferreds, and the values behind the tokens the core passes around. The evaluator reaches it through one small interface: call, spawn, ended, wait, returned, abort. A grep for fiber, semaphore and interrupt APIs over the evaluator’s sources finds nothing; they appear only in the scheduler module.

Replacing opencode’s scheduler changed some behaviour that a script can observe. Each change follows a law:

• An un-awaited failure no longer fails the whole run. The returned value is kept, and the failure is listed next to it.
• Promise.all rejects at the first failure in time, not at the first failure by index. A script waiting on a slow call learns at once that a fast one failed.
• A rejected Promise.all does not interrupt its other members. A half-done write is never cut off because a sibling failed.
• A race loser that is still queued never starts.
• After the script returns, the run waits for every queued or running call to finish.
• After a timeout, nothing is accepted.

The async keyword nobody reads

While I was mapping the seam, one finding did not fit. The parser records whether a function is async, but nothing ever reads that flag. Calling an async function evaluates its body right there, including every await inside it, and the caller gets the value, not a promise.

So in opencode’s codemode:

items.forEach(async x => { await tools.post({ x }) })

runs the posts one after another. And

await Promise.all(items.map(async x => {
  const page = await tools.fetch({ x })
  return await tools.summarize({ page })
}))

processes the items one at a time. map gets back values, not promises, and Promise.all over plain values works, so the result is correct. It is only serial.

At first I took this for an unfinished feature. Three things in the source changed my mind:

1. A comment states where the parallelism lives. The Promise.* code says that tool calls already run eagerly on their own fibers, and the combinators only observe settlements. So joining is “sequential (no extra fibers) without costing parallelism”. The concurrency cap “stays where the work is”. The design puts parallelism in tool calls, not in functions.
2. A test pins a behaviour that is not JavaScript. It asserts that

   "a1b22".replace(/\d+/g, async m => await tools.decorate(m))
   

   returns "a[1]b[22]". In real JavaScript an async replacer returns a promise, and the result is "a[object Promise]b[object Promise]". The same test then asserts that a replacer which returns a tool-call promise without await is an error. The two cases sit side by side. Whoever wrote that test knew this differs from JavaScript and wanted it.
3. Elsewhere the code cares about JavaScript fidelity. Returning a promise from the script resolves it “exactly as in JS”, says another comment. A team that writes that is not careless about semantics. This difference was chosen.

Why opencode’s choice makes sense

The scripts are written by a model, and models make the same async mistakes people do. To see what the inline design buys, I ran a few such mistakes on my evaluator after I had made async real:

The right column is exactly what JavaScript gives: a promise is always truthy, and a promise turned into a number is NaN. It is also always a bug, and the program reports nothing. The model gets a wrong answer and has no reason to doubt it.

Under the inline design, all four are right. await behaves like a blocking call, so any callback can be async and still return a usable value. Add that tool-to-tool parallelism is still available through Promise.all over direct tool calls, and the design is coherent. It gives up some speed to make a whole class of mistakes harmless. The implementation is simpler too: there is one execution, one scope stack, and no interleaving between functions.

Why I made async real anyway

The case where the inline design loses is the most common parallel pattern a model writes:

await Promise.all(items.map(async x => { /* several dependent tool calls */ }))

With inline async, N items of k steps each take about N × k tool round trips. With real async and a concurrency limit of 8, they take about ⌈N/8⌉ × k. This is an estimate from the scheduling rules, not a measurement. But codemode exists to save round trips, and this is its main path. A model could restructure the work into stages of Promise.all over direct tool calls, but it has no reason to know it should.

There are smaller reasons too:

• Race works. With inline async, an async function passed to Promise.race has already finished before the race begins, so it always wins.
• Errors arrive where JavaScript sends them. An async function that throws gives a rejected promise, not a synchronous throw that a surrounding try catches.
• The laws were already written for it. Fn executions, Draining, and the rule that a Fn race loser runs on are all in the core. A JavaScript function cannot be stopped from outside.

So in my evaluator, calling an async function now sends EvAsync. The core answers Spawned(id), the body runs up to its first suspension, and the caller gets a promise and continues. That is JavaScript’s order. One detail: each async execution evaluates on its own interpreter instance, because the evaluator keeps its scope stack on the interpreter object, and two bodies paused at their awaits must not share one. A test pins the order: an async function pushes before and after an await, and the caller pushes after the call. The result is ["body before await", "caller after call", "body after await"].

That leaves the table above, which is a real regression.

The mitigation: make the silent cases loud

All four bad cases share one cause. A promise is used as a boolean or as a number, and in JavaScript that is always a mistake. So the rule is: when the evaluator converts a promise to a boolean or a number, it throws an “un-awaited Promise” error the script can catch, and the message tells the model to resolve the values with Promise.all(items.map(...)) first and then filter or sort on the results.

The check sits in the two conversion helpers, so every place that reads a value as a condition or a number goes through it: if/while/for tests, ?:, !, the deciding side of && and ||, arithmetic and ordering operators, the callbacks of filter, find, some, every and their relatives, and sort comparators. All four cases in the table above now raise instead of answering wrongly, and none of the existing tests had to change.

Three properties make it attractive:

• It is one rule at the conversion points, not a check per method. It covers filter, find, some, every and sort, and also the model’s own if (check(x)), !p, p && … and p > 0.
• It cannot break a correct script. A correct script never converts a promise to a boolean or a number, so only an already-broken script sees the error.
• It fits what opencode already does. opencode already raises an “un-awaited Promise” error when a promise reaches the data boundary (a tool’s input, the script’s result, a replace result) or when the script reads a property of one. This extends the same idea to the other places where a promise is certainly a mistake.

It does differ from JavaScript, which would silently continue. Here, failing loudly beats matching JavaScript exactly. The model can fix an error it sees, and it cannot fix a wrong answer it trusts.

What the error does not catch

One pitfall survives:

let total = 0
await Promise.all(items.map(async x => { total += await tools.count({ x }) }))

total += await f() reads total before the await and writes it after. With real concurrency, the executions read the same old value, and some additions are lost. Inline async gets the right sum, while real async gets the JavaScript answer, which is wrong. No conversion happens here, so the error rule cannot see it. The evaluator cannot tell this mistake apart from intended code. I accept this risk because I expect it to be rarer than filter(async …). That is a guess.

What would change my mind

The choice rests on two claims I have not measured:

1. Models write multi-step map(async …) pipelines often enough that serial execution costs real time.
2. The total += await pattern is rare.

Once codemode runs inside the agent, the scripts models actually write will be in the session logs. If pipelines are rare and read-modify-write across await is common, inline async is the better design, and going back is cheap. The core would stay as it is; the evaluator would simply stop sending EvAsync.

Until then I keep real async with loud errors. The opencode team made a careful choice for its context, and I only noticed it was a choice after I had made the opposite one. Thanks to them for the evaluator, and for a design that was worth understanding before I departed from it.

I am building a coding agent. It is a per-user daemon written in TypeScript, and every decision it makes — what to send to the model, when to ask the user, what a cancel closes — lives in a core written in Bend , where laws are proved for every input. The agent is new and has no users yet, so I can try things that an established agent cannot.

One of those things is codemode. I started out to give the agent a JavaScript sandbox. I ended up with no sandbox at all: I kept the evaluator of opencode’s codemode package , and I am replacing its scheduler with a Bend core. The design is not finished. But the path to it changed what I think the problem is, and that part is worth writing down now.

This post goes in the order I learned things: what codemode is, where it pays and where it does not, why the obvious engine was the wrong answer, what opencode got right, and why I split their package in two.

What codemode is

An agent normally calls tools one at a time. The model asks for a tool, the agent runs it, the result goes into the transcript, and the model asks for the next tool.

In codemode the model writes a short program instead. The program calls the tools, and it can do in one step what took several requests: run independent calls at the same time, feed one result into the next call, filter a large result down to the three fields it needs, and return only that.

const prs = await tools.github.list_pull_requests({ owner: "cli", repo: "cli", state: "closed", per_page: 20 })
const merged = prs.filter((p) => p.merged_at)
const files = await Promise.all(merged.map((p) => tools.github.get_pull_request_files({ owner: "cli", repo: "cli", pull_number: p.number })))
return merged.filter((p, i) => files[i].some((f) => f.filename.startsWith("pkg/cmd/"))).map((p) => ({ number: p.number, author: p.user.login }))

It promises to save three costs:

1. Tool descriptions. Every request carries the description of every tool offered. With many tools, that is tens of thousands of tokens on every request.
2. Intermediate results. A tool result goes into the transcript whole and is sent again with every later request, even when the model needed one field of it.
3. Round trips. A chain of dependent calls costs one request per step.

These are promises. I wanted measurements before I built anything.

Experiment 1: codemode over the basic tools gives nothing

My agent has four basic tools: bash, read, grep and write. I gave a model (DeepSeek Flash, high reasoning effort) four tasks on a copy of the agent’s own repository — count the laws per package, list exported functions, find mismatches between laws and proofs, count a code pattern per package. There were three conditions: the four plain tools; only a script tool with the four tools inside it; and both. 48 runs, all correct.

There was no consistent saving. On one task the script-only condition used 84k prompt tokens where plain tools used 47k.

The reason was in the logs. In the plain-tools condition, 83 of 111 bash calls used a pipe, a loop or inline Python. A shell already is codemode for local work. The model composes rg | sort | uniq -c as naturally as it composes JavaScript, and a script mostly wrapped one bash command. When both a script tool and plain tools were offered, the model chose the script in 3 of 16 runs.

So codemode is not a general improvement. The question became: where does a shell not reach?

Where codemode pays: MCP and the tool explosion

A shell pipe filters text. An MCP tool returns a JSON object, and there is no pipe between two MCP tools. Worse, MCP tools come in large numbers. On my work machine an agent loads Slack, Atlassian and other servers — close to a hundred tools. The GitHub MCP server alone has 27 tools in its default read-only set, which is 8.3k prompt tokens of descriptions, and 91 tools with every toolset on.

The usual answer to this is progressive disclosure: do not send every description; give the model a search tool, and add a tool’s schema only after the model finds it. My older agent does this. So the second experiment compared three conditions over the GitHub MCP server, on two tasks against the public cli/cli repository (“which of the 20 most recently merged pull requests changed a file under pkg/cmd/, with author and review count”, and a similar one over issues and comments):

• A: every tool offered directly.
• B: progressive disclosure — a search tool plus an enable tool.
• C: codemode, with a 2,000-token catalog in the tool’s description and a search call available inside the script.

All 18 runs were correct.

Codemode cost about 30% of offering every tool and about 25% of progressive disclosure. Two things in that table surprised me.

The saving comes from results, not from requests or descriptions. All three conditions made about the same number of requests. Codemode’s prompt was a fifth of the others’ because the script filtered the GitHub JSON before anything entered the transcript. In one pilot run, a script made 54 GitHub calls; the model saw only the answer.

Progressive disclosure alone did not save anything here. It removes descriptions, but it does not remove results, and its search and enable steps add requests. It cost as much as offering every tool, or more. Its benefit grows with the number of tools; codemode’s benefit comes on top of it.

That settles where codemode belongs: MCP tools are reached only through codemode. They never appear in the main tool list. The main loop sees five tools — the four basic ones and codemode — and the codemode tool’s description carries a catalog: every MCP namespace with its tool count, plus as many full signatures as fit about 2,000 tokens. For the rest, the model writes a short discovery script that calls tools.$codemode.search(...) and returns the signatures it found, and then writes the real script. The main loop knows the table of contents without carrying the pages.

Choosing an engine: QuickJS works, and that was not enough

To run model-written JavaScript, the obvious engine is QuickJS compiled to WebAssembly. It is a complete JavaScript engine in a separate heap, it is small, and it runs anywhere. I tried it first, in Bun, with the four basic tools injected as an async tools object.

It passed almost everything. Scripts called tools and returned values. Promise.all over four sleep 1 calls took 1.09 s, so the host calls overlapped. fetch, process, require, import() and the usual constructor tricks reached nothing. A 16 MB memory limit stopped a runaway script, and deep recursion raised a stack overflow. A context cost 0.11 ms to create.

Two things did not fit.

• A busy loop cannot be cancelled in-process. While the script runs while (true) {}, the event loop is blocked, and only a deadline inside QuickJS stops it. A real hard cancel means putting QuickJS in a worker and terminating the worker.
• The boundary is manual. Every value that crosses into the WebAssembly heap is a handle that must be freed, and async calls need a hand-written bridge. During the experiment, disposing a context while a script still held an unresolved promise failed an assertion inside QuickJS, and the module was broken for every later script in the process. In a daemon where all sessions share one process, that is a serious failure mode, and it is the kind that tests do not find.

Then I read a tweet from one of the opencode developers:

we specifically avoided using quickjs as our codemode implementation

it brings in webasm complexity + forces worker threads + serialization of values back and forth

Two of those three I had just hit. The third, serialization, turned out not to matter: opencode copies values across its boundary too, and its per-call overhead (11.6 µs) was close to QuickJS’s (8 µs).

opencode’s interpreter: rejected at first

opencode’s codemode package parses the script with acorn and runs it in a tree-walking interpreter written with Effect. There is no global object, and the standard library is an allow-list. I ran the same checks against it.

It also lacks part of the language: no classes, generators, new Promise or .then.

My first decision was QuickJS. opencode’s interpreter had no memory limit, so one script could exhaust the process that holds every session. It was 50 times slower. And it could not run code a model might write. I wrote that decision into the design document with its reasons.

It was the wrong decision, and the reason was not in the table. I had compared two packages. I had not asked what problem the engine solves.

The question I had skipped: what are we protecting against?

opencode’s README has a section called Authority Boundary. Its central sentence is this:

A program cannot gain authority through prose or generated code. It can only exercise authority already present in the supplied tools. Do not expose a broad tool and expect the prompt to restrict it.

QuickJS answers the question how do I run arbitrary JavaScript safely? It gives the guest the whole language and puts a wall around it. But codemode does not run arbitrary JavaScript. It runs a short program whose whole job is to call the tools it was given and move data between them. The risk is not that the program does something clever with the language. The risk is that it reaches something it was not given.

opencode’s answer is to make the language itself the boundary. The interpreter implements only what an orchestration script needs. There is no eval, no module system, no host global, no prototype to mutate. The only door to the world is the tools object the host passes in. A script has no ambient authority, by construction — not because a wall stops it, but because there is nothing to climb.

Seen that way, each of my objections changes size:

• Speed does not matter. A codemode script spends its time waiting for tools. In the MCP experiment, the scripts did almost no computation. A 50× slower loop over a few hundred items is still milliseconds.
• Missing features are a prompt problem. The model is told the subset: async/await and Promise.all work, class and .then do not. When it forgets, the interpreter answers with an UnsupportedSyntax diagnostic that already names the correct form, and the model fixes its script.
• Memory is a denial of service, not an escape. A script that allocates without limit can take the process down. It cannot gain any authority. That needs containment, but it does not need a second language runtime.

It also changed a decision I had not expected it to touch: approving a script approves every call it makes. If the code is the whole of what can run, and it can only call the tools the session offers, the user can read the script once and decide. Asking again for each inner call would bring questions in bursts in the middle of a script (up to eight calls run at once), and a denial would leave the script half done.

The language is also not special. JavaScript is the choice because models write it well and because my agent is written in TypeScript. The principle — a small language whose only effect is calling granted tools — would work with any language.

Containing what is left

Two risks remained, and I measured them in Bun rather than guessing.

A catastrophic regular expression. opencode runs regular expressions on the host engine, synchronously. I expected /^(a+)+$/ on a long string to hang the thread. It did not. JavaScriptCore caps backtracking: the time grew exponentially up to 26 characters (235 ms) and then stayed at about 350 ms for any length up to 200. The catch is what happens at the cap: the engine reports no match, even when the correct answer is a match. /^(?:(a+)+$|a+!)/ on 24 as and a ! is true; on 30 it is false. So a pathological pattern cannot hang the daemon, but it can quietly give a wrong answer, and the model should be told so.

Memory. My agent already runs every plugin in a Bun worker, so I hoped a worker would contain a runaway script. It does not. worker.terminate() stops a busy loop. But Bun ignored both resourceLimits: { maxOldGenerationSizeMb: 256 } and smol: true, the worker reached 3 GB either way, and after it exited the process still held 3.5 GB.

A child process does contain it. The child reports its resident memory to the parent every 20 ms over IPC, and the parent sends SIGKILL above a limit. With a 512 MB limit, the child was killed at 562 MB after 92 ms, and the parent stayed at 12 MB.

So each script runs in its own child process, killed above 512 MB or after five minutes. Five minutes, not two, because a script composes calls whose total length nothing predicts; a script that needs longer asks for it explicitly. Every inner call goes back through the daemon, so the session’s tool set, hooks and logs apply to it.

flowchart TD
  subgraph D["agent daemon"]
    S["session
(Bend cores)"]
    H["plugin host
tool registry"]
  end
  subgraph W1["worker: codemode plugin"]
    CM["catalog, instructions
memory watchdog"]
  end
  subgraph C["child process, one per script"]
    I["evaluator runs the script"]
  end
  subgraph W2["workers: tool plugins"]
    T["basic tools, MCP tools"]
  end
  U(["user"]) -- "approves the script once" --> S
  S -- "codemode(code)" --> H
  H --> CM
  CM -- "spawn" --> I
  I -- "tools.ns.tool(input)" --> CM
  CM -- "inner call, already approved" --> H
  H --> T
  CM -. "over limit or cancel: kill" .-> I

Why I am splitting opencode’s package in two

At this point the plan was to use opencode’s package as it is. Then I read its scheduler.

opencode’s codemode is written to be used inside opencode, and it shows. The concurrency limit is a constant of 8. The per-call hooks can observe a call but cannot refuse, replace or delay it. The TypeScript compiler is a run-time dependency, used to strip types from the script. There is no way to drive the interpreter from outside; it runs a whole script as one Effect. None of this is a flaw for opencode. It is a problem for anyone who wants to put the idea inside a different agent.

Reading the code, I saw that the package holds two different kinds of code.

The evaluator turns syntax into values: scopes, closures, destructuring, operators, the standard library, the plain-data copies at the boundary, the blocked prototype members. It is most of the 3,500 lines of the interpreter, and it comes with parity tests against real JavaScript. This is the hard, careful, valuable part. It is language semantics, and it holds no decision worth a law.

The scheduler decides things about tool calls: when a call starts and when it queues; what await, Promise.all, Promise.allSettled and Promise.race deliver, and in what order; which calls a timeout or an abort interrupts; what the end of the program waits for; when an un-awaited failure is reported. It is a few hundred lines, spread across Effect fibers, a semaphore and fiber supervision.

The scheduler is exactly the kind of code my agent puts in Bend. It is a state machine: step(state, event) -> (state', commands), with events such as called, done, await, all, race, timeout, abort, end, and commands such as start, interrupt, resume, reject. In opencode, some of its behaviour is not stated anywhere. When one member of Promise.all fails, the failure surfaces only after the members before it have settled, because the join goes in index order — no test pins this down. Whether a ninth queued call is counted against the call limit before or after it waits depends on the Effect version’s semaphore. In a Bend core these become laws, proved for every input:

• at most N calls run at once;
• every call settles exactly once;
• a race has one winner, and every loser is interrupted;
• Promise.all delivers results in call order;
• nothing is delivered after an abort;
• every failed un-awaited call is reported.

There is a second reason, and it is the bigger one. The bugs I worry about are not inside opencode’s scheduler, which is tested. They are at the seam between it and my daemon: a child process is killed while inner calls are still running in the daemon; a result arrives after the script is gone; a cancel reaches one layer before the other. Today those guarantees would rest on two layers happening to agree. With the scheduler in Bend, the script’s calls and the daemon’s inner calls can meet in one core, and a law can cover the whole chain: after the script ends, by any route, every inner call is closed and no result reaches anyone.

So the decision is: a new package, forked from opencode’s codemode. It keeps the evaluator, the catalog and search, the schema checks around each tool call, and the sanitising of host errors. It replaces the scheduler with a Bend core, and drops what only opencode needs. opencode is MIT-licensed; the package keeps its copyright notice and license text and names the commit it came from.

One consequence follows from the authority argument, and I want it stated plainly. The evaluator is now the security boundary. With QuickJS, a mistake in the guest stays inside a separate heap. Here, every implemented feature has to be right: the blocked prototype members, the copies in and out, every standard-library method that runs on the host engine and must not hand back a host object. That is the price of dropping the wall. It also points the fork in a clear direction: each language feature removed is one less thing that has to be right.

What is still open

The design is not finished.

• Where the scheduler core runs. In the child process beside the evaluator, each step is local, and the daemon keeps a separate ledger of inner calls. In the daemon, there is one core with laws over the whole chain, but every await crosses a process boundary.
• The laws themselves. The list above is a set of candidates, not approved laws.
• An MCP client. The daemon has none yet, and codemode’s value depends on one.

What I have now is not code. It is a clearer statement of the problem. I started out asking which sandbox to use. The better question was what a script must not be able to do — and once that was answered, the sandbox turned out to be the part I did not need.

Thanks to the opencode team for the codemode package, and for the tweet that made me look again.

For a long time I talked to coding agents in Emacs through agent-shell . It worked well, except for one thing, and that one thing was the biggest problem: I could not type while the agent was writing its output. I would read the first lines of an answer, know what I wanted to say next, and then wait for the agent to finish before I could start. Every turn broke my train of thought.

So when I wrote an Emacs client for my own agent, the first requirement was an input area that is always available. My first version had two buffers. The conversation was a read-only buffer in one window. The place where I typed was a second buffer, with its own major mode, in a side window under it. I could type at any time — but the split cost me something small every few minutes. Closing a session meant closing twice, once per window. Getting back to the input meant finding out which window had focus, or typing a buffer name like *agent-input: work*.

So I moved the input area into the output buffer. It is now a few lines of ordinary text at the end of the conversation. This post explains how that works, and then how I made it stay on the bottom row of the window, down to the pixel. The first part took an afternoon. The second part took a day.

The figures are small models you can operate. Press the buttons: each one computes its answer the way Emacs does.

Part 1: an input area inside a read-only buffer

The output buffer must stay read-only: the agent writes there, and I must not change its words by accident. The input area must accept typing, at any time, even while the agent writes. This part shows how one buffer does both.

The whole session is one buffer, shown in one window. Read it top to bottom:

The part after the anchor is the input area: a configuration line (model, strategy, effort, context use, queued messages), the prompt > , and the draft I am typing. It is plain buffer text. There is no widget and no overlay.

One position, two jobs

The client already kept a marker for “where does the next piece of output go” (cordis--insert-marker). The input area needs a marker for “where does the input area begin” (cordis--region-start). These are the same position, so I made them one marker. Two markers that must always be equal stop being equal the first time someone updates one and forgets the other.

So new output is inserted at the anchor, and everything after the anchor — configuration line, prompt, draft, cursor — moves forward as one piece.

Three text properties make the draft writable

The buffer is read-only; only the draft must accept typing. Emacs can do this with text properties alone, because of one rule: a character you type copies the text properties of the character before it, except the ones that character lists in rear-nonsticky.

The client sets three things:

Try it. Type into the draft, then let some output arrive:

The third row of the table is the one I did not expect to work. keymap is a text property that Emacs checks when it looks up a key. So the input keymap needs no minor mode, no overlay, no toggle. It arrives with the prompt, and each character I type passes it on to the next one.

This removes a whole category of state. There is no “input is active” flag to keep in step with focus, because there is nothing to activate. The draft is text in a read-only buffer, and the only thing that makes it writable is that the read-only property stops at the last character of the prompt.

Taking the keyboard back from special-mode

The output buffer’s major mode derives from special-mode. That mode is for buffers you read, not buffers you type in, so it binds printable keys to commands: q closes the window, SPC and DEL scroll, and 0–9 and - are prefix arguments. In the input area I could not type q — and, worse, I could not type a digit.

A text-property keymap is checked before the major mode’s map. That order is what lets one buffer have two keyboards. The fix is two forms in the input keymap:

(map-keymap (lambda (key _binding)
              (when (and (integerp key) (<= 32 key 126))
                (define-key map (vector key) #'self-insert-command)))
            special-mode-map)
(define-key map [remap self-insert-command] #'self-insert-command)

The first form is a sweep, not a list. It walks special-mode-map and takes back every printable key it binds. If a later special-mode binds a new key, the sweep takes that one back too — and the test walks the same map, so it notices.

The second form looks redundant. It is not. special-mode-map contains (remap keymap (self-insert-command . undefined)), and Emacs applies remaps after it finds a binding. With the sweep alone, every key finds self-insert-command, and then the remap turns it into undefined. Switch the two forms off and on:

In the output, above the anchor, nothing changed: SPC still scrolls and q still closes the window.

Scrolling that nobody has to write

The old client had a mechanism to keep the output scrolled to the bottom, and it had grown large: a cordis-follow window parameter, a window-scroll-functions observer, an initializer on window-buffer-change, a resume-following command, and a set-window-point after every write.

It had a reason to exist. A fully read-only buffer has no natural home for the cursor, so the code could not tell “the user watches the bottom” from “the user scrolled up to read”. It guessed from the geometry and moved the window.

With the input area in the buffer, that mechanism became a bug. The cursor now lives in the draft, and every write moved it. If I corrected a word in the middle of my draft and a line of output arrived, the cursor jumped to the end of the draft — 37 characters, in the case I measured.

I deleted all of it, and nothing replaced it. The cursor is in the input area, and Emacs always keeps the cursor’s line visible. So new output appears above the input area, older text scrolls up and away, and the input area stays where it is. A terminal gets this effect from a scroll region; here it falls out of where the cursor is.

Twelve tests went away with the mechanism. Two new tests replaced them, and both assert something that must not happen: arriving output must not move window-point, whether the cursor is in the draft or up in the output.

Part 2: keeping the input area on the bottom row

That is enough while the buffer is taller than the window. It fails at the start of a session, and it is not quite right later either. The two cases need different fixes.

A short buffer: pad the top

A terminal owns a screen of fixed height and reserves the bottom rows for the input (I compared how agents do it in How Coding Agents Draw Their Input Box ). The input’s position is fixed by construction.

An Emacs window has no such thing. It shows a buffer from some start position downward. A short buffer is shown from its first line, so the input area sits right after the last line of text — in the middle of the window, with empty rows below it. Every new line of output pushed it down one row. In a fast stream it slid down the window until the text filled it.

The fix makes Emacs look like the terminal, out of text: insert blank lines before the output, so the buffer is exactly as tall as the window.

(max 0 (+ have (- height lines)))

height is the window’s height in lines, lines the buffer’s height in display lines, and have the pad already there. As the output grows, the pad shrinks — measured 44 → 20 → 0. At 0 the text fills the window, normal scrolling takes over, and the client stops computing the pad. That also saves time: count-screen-lines walks the whole buffer, and a long session would pay for it on every line of output for nothing.

Drag the slider, and turn the pad off to see the old behaviour:

Two details matter later. The end of the pad is a marker, not a count: when the output is cleared, the marker falls back to point-min and the pad is zero by construction — nothing has to remember to reset it. And the pad is real newline characters with the output’s read-only properties, not a display trick. That matters for the pixels.

A long buffer: pin the window start

When the text is taller than the window, the bottom row still belongs to nobody. Emacs only promises that the cursor’s line is visible. The cursor is on the draft, the second line of the input area, so the configuration line above it may be cut off. The window start jumped between two positions one row apart: origin rows 64/66 alternating with 65/67, and the cursor at y 1354, then 1334.

So the client sets the window start itself. The output gets h - K rows, where h is the window height and K the input area’s height. K is measured with count-screen-lines, not assumed to be 2, because a long draft wraps. It is capped at half the window, the same limit the terminal version uses.

One detail cost me a few pixels of draft. The input area usually begins at the newline that ends the last line of output — and that newline belongs to the output’s display line. Counting h - K lines up from it starts one line too high, and pushes the draft below the window’s bottom edge.

The last few pixels

vertical-motion moves by whole lines, but the lines in this buffer do not all have the same height:

• body text is 20px;
• Markdown headings are 22px, because the heading face is :height 1.1;
• a line with an emoji or a fallback glyph is 27px.

In a 266-line session, 24 lines were not 20px. So whole lines almost never add up to the window height exactly: a gap of 0 to 19 pixels is left at the bottom, and its size depends on which lines happen to be on screen. I kept the tall headings. They are a big part of why this reads better than the terminal, and I would rather pay for them here than flatten the type. The terminal pays nothing, because every cell there is the same size.

Emacs has one setting for a partial line, window-vscroll, and it does not hold here:

• it works for one redisplay and is reset to 0 as soon as window-start changes (set 13, read back 0);
• set from window-scroll-functions, it sees the old window start and corrects too much.

What holds is a real character: one space at the end of the configuration line, with a display property of (space :height X). It is text, so redisplay has to lay it out; it cannot decide to ignore it. Add lines of different heights, then turn the spacer on:

Two facts about the spacer I had to measure, not reason out:

1. (space :height N) ignores integers. 27 still gives a 20px line. The value must be a multiple of the base line height: 1.35 gives 27px on a 20px base.
2. The order must be set it to zero, measure, fill once. If the old height stays in while I measure, the measurement includes it, the next pass drops a line, and the two corrections fight. Measured, that fight settled at a 10px gap with the spacer at its maximum.

Why it still flickered

After all that, it was almost right: now and then the input area jumped up or down by one line. Finding out why took longer than building the feature. There were three causes, unrelated to each other.

1. The pad was recomputed on the wrong event. I recomputed the pad when output was written. But the input area changes height on its own — that is what an input area does. Write a five-line draft while the agent works, send it, and the draft is cleared: the buffer is four rows shorter, and nothing recomputes the pad until the next line of output. For that stretch the input area floats up.

The fix is post-command-hook. It runs after each command and before redisplay, which is exactly the deadline. A timer with zero delay is not the same: it runs after the frame is drawn. My earlier timer-based attempt was one frame late every time, and one wrong frame is what a flicker is.

2. The hook that did nothing. For a while the hook was installed and had no effect, with no error in sight. Two things stacked up:

• Emacs silently removes a function from post-command-hook when it signals an error. The symptom is “installed, does nothing”, and *Messages* is empty.
• The error was mine. The function’s docstring was in Chinese, and I had put an ASCII " inside a quoted phrase. The string ended there, the rest of the sentence became code, and that code failed with void-variable when the command finished. The syntax check passed, because the file was balanced and parsed. A stray quote in a docstring is legal code.

And define-derived-mode does not run its body again for a buffer that is already in that mode. Reloading the file gave the hook to the next session, not to the one I was testing in. There is now a re-arm path, and it installs the hook too.

3. Someone else’s global hook. The last flicker was not about geometry at all. beacon-mode flashes the cursor line whenever a window scrolls. This buffer scrolls once per line of output, so beacon flashed on every line. Beacon lives on the global window-scroll-functions hook, so the client now removes it from that hook in this buffer only. The cost: toggling beacon later has no effect here until the mode is entered again.

One suspect was cleared, and it was the first thing both the agent and I guessed. scroll-preserve-screen-position is t in my configuration, and “keep the cursor’s screen row” sounds exactly like something that could oscillate. Turning it off locally gave the same frames, one for one. Not guilty.

What it costs

Traps, in one table

If you want this in your own client

Without the war stories:

1. One anchor. The place where output is inserted and the place where the input area begins are the same marker.
2. Put the input keymap on the prompt as a text property, and use rear-nonsticky to choose what a typed character copies.
3. Take the keyboard back from special-mode with a sweep over its map, plus a remap of self-insert-command back to itself.
4. Pad before the output while it is shorter than the window. After that, set the window start yourself.
5. Fill the last pixels with a real character that has a display height, not with window-vscroll.
6. Recompute on post-command-hook, not on a timer: the input area changes height without any output.
7. Never read window state while writing output. What you can read there describes the previous frame.

If I could keep only one of these, it would be the keymap that travels with the prompt. It is why there is no input mode, no “active” flag and no second buffer. The input area is not a widget that the output buffer hosts. It is text at the end of the buffer that happens to be writable.

Every coding agent I use handles a long conversation the same way. It lets the context grow until it gets close to the window, sends the whole thing back to the model with “summarize this”, and carries on from the summary. Claude Code calls it auto-compact. Codex does it. My own agent, a small harness written in Rust, did it too.

For a while now my agent has worked another way. I think it is the better default, and I have not seen anyone else talk about it. I call it a context fold.

The short version: don’t wait for the window to fill. Ask the model, again and again, one small question: is anything behind you finished? It is a hard question to answer about the future and an easy one to answer about the past.

What is the model actually reading?

I measured my own sessions: 221 of them, 853 user turns, 12,268 tool calls. For every request I split the context into three parts:

• the work in progress,
• the conclusions of finished work,
• the steps of finished work: the tool calls, their outputs, the dead ends.

With no processing at all, the third part is two thirds of what the model reads. The conclusions of that same finished work are about 1%.

That is not mostly a cost problem. Prompt caching makes old tokens cheap. It is an attention problem. On every turn, the model reads through a long record of how the login test got fixed, only to find out what to do about the build.

Compression waits for the wrong signal

Compaction fires on the water level. That has three consequences:

1. The timing has nothing to do with the content. It fires in the middle of a task, when the context is most useful. The trigger is “the window is full”, not “this part is done”.
2. The replacement is a paraphrase, and the original is gone. The harness may keep a backup file, but the model cannot read it back. Whatever the summary left out does not exist any more.
3. It costs a model call. The whole context goes in and a summary comes out, and output tokens are the most expensive kind and cannot be cached.

Here is the same session under both rules. On the left, compaction. On the right, folding.

Look at turn 4, “ok, turn it off”. It is short and it reads like a new instruction, but it continues the build question. The model sees that and folds nothing. The last unit is still open, so it stays word for word.

Boundaries are easy in hindsight

The obvious fix is to cut the conversation into tasks and drop the finished ones. The hard part is where a task starts.

I tried a lexical rule first and checked its output by hand:

Half of all user messages are 60 characters or less. “all of them need to be improved” and “you decide, it’s fine, go ahead” look like new instructions. They are not. And work gets tangled: a new task often starts as a side remark and turns into a task three turns later. Looking forward, you cannot tell.

Looking back, you can. When a piece of work is done, the model has just written its conclusion: fixed, the race was in session setup. From that end, the start is plain to see. It is like parentheses. When you open one, you do not know how deep you will go. When you close one, you always know which one you are closing.

So the host does not try to find the boundaries. It does what it is good at, which is counting, and filtering out the 97% of turns that are plainly continuations. The model does the one thing only it can do: it judges the content.

How a fold works

The card. When enough work has built up since the last fold (about 20 tool calls, or about 100k tokens), the host attaches a short card to the user’s next message. The card lists the turns since the last fold, their sizes and the paths they touched, and each user message word for word. Then it asks one question. The host numbers the turns, so the model picks from a printed menu and never has to count. “Ignore this” is a valid answer. When nothing is closed, the card cost about 250 tokens and that is all.

The answer. The model calls fold_unit(from, to). The host checks only that the call is legal: the turns exist, the range is not reversed, there is no earlier fold inside it (folds do not nest, because each level loses a little more), and the turn in progress is not part of it. The unit the model is working in is never foldable.

The splice. After the turn ends, the host first writes the original messages to an archive file with a sha256, and only then replaces the range with a single result message. That order matters: a result must never point at an archive that does not exist.

The result. The host builds the result itself, with zero model calls, from three parts:

• a mechanical index: tool calls counted by name, the paths they touched, the number of shell commands. The host counts these, so they cannot be wrong;
• every user turn in the range, word for word. The user’s decisions are the one thing no tool can find again;
• the model’s own closing message for that unit, which it already wrote.

Reading it back. The archive is an ordinary file. If the result turns out not to be enough, the model reads the file with read or grep, the tools it already has. There is no special “unfold” tool and no undo command. An undo would push the wrong way: if a fold can always be undone, nobody has to make the result good enough to stand on its own.

Why not just trim old tool output?

Some agents cut old tool results on every request. I decided against it, for one rule:

Anything you drop must have an archive, an address and an index. If it does not, don’t drop it.

Trimming has none of the three. It even removes the record that a file was ever read, so the model has to rebuild its state from nothing. I ran a small A/B test: a two-turn task, three runs per arm, with trimming the only difference. Both arms got the right answer. But in turn 2 the trimming arm re-ran every tool call from turn 1: 4, 4 and 4 calls against 0, 1 and 1.

What it buys

On that resumed session, replaying its real fold points against the same session without folds: the median request was 0.2× the size, about a fifth. By the end of the session it was a sixth. That is one session. The ratio is solid; I would not generalize from it.

Prompt caching is what worried me. A fold edits the middle of the conversation, so everything after the fold point misses the cache once. I simulated the options. Fold as soon as a unit closes: 217 folds, a median of 17k tokens rewritten each. Wait for pressure and fold then: about 30 folds, a median of 200k each. The totals came out within 21% of each other. When you fold does not change how much you rewrite. It only changes whether you pay in many small pieces or a few big ones.

Compaction is still there, as the emergency path:

Strategies: the context as a call stack

A fold draws the parentheses after the fact. Sometimes you know in advance. “Go find out why CI is flaky” is a detour, and you know before you start that it will open and close.

For that, my agent has strategies. A strategy is a mode: a set of standing instructions, an explicit way in and out, and a label on the status line so the user always knows they are in one. Mechanically, it is a stack frame:

• Enter (strategy_request, or the user types /strategy). The host appends one message at the tail of the conversation, with the rules of the mode. It does not change the system prompt or the tool list. Those always stay the same. So the whole prefix is byte for byte what it was, and the next request hits the cache.
• Inside, the model works in the same context. It sees everything the main loop saw, so nothing needs to be explained again.
• strategy_report is the return value. The model rewrites it as the work goes along.
• Exit (strategy_yield, or the user types /back). The whole branch folds away. The main conversation keeps exactly one thing: the latest report.

That is a function call. Push a frame that shares the caller’s environment, do the work, return a value, pop. The general-purpose one is errand, whose rules are three lines: do only this task, keep the report current, yield when you are done. The others follow the same shape: triage works through a queue with the user deciding each item, intent is a read-only mode for agreeing on what to build, and counsel hands a hard problem to a stronger model.

The return value is written, not scraped

This is the point I most want to get across. You cannot get the result of a piece of work out of its transcript afterwards.

The obvious way to build a strategy is: when the mode ends, read the branch and summarize it. That is compaction again, in a smaller box, and it is lossy for the same reason. The transcript records what happened, not what mattered. Take forty tool calls. Which grep answered the question? Which idea was dropped, and why? Of three edits, which one is the fix and which two were experiments? The model knew each of these at the moment it happened: when the log line matched, when the test went green. Afterwards, that knowledge is spread over forty outputs that all look equally important, and whoever writes the summary has to guess it back. That is true even for the same model reading its own transcript. It is reconstructing, not remembering.

So the result is written as the work goes along:

• strategy_report is a slot, not a log. Each call replaces the previous one, so the report always holds the current state of the work, not its history. The model calls it when it learns something: “3 failures, all EADDRINUSE” at the moment it sees the log, “tests share port 8080; fix: bind :0” at the moment the test passes.
• strategy_yield is an explicit end. The model says the work is done and gives a reason. The host then takes the last report exactly as it is. Nothing is inferred on the way out, and there is no extra model call to write a summary.

A side effect: if the user leaves in the middle with /back, the report is still current. It holds everything learned up to that point, because it was never waiting for the end.

It is the same principle as the fold. A fold result is made of counts and the user’s own words, plus the closing message the model wrote when it finished. Neither mechanism summarizes after the fact. The only accurate record of what mattered is the one written at the moment it mattered.

Subagents: a tool that thinks

A strategy is a call on the same machine. A subagent is a call to another process. A fresh child sees only the brief it is given. It runs in the background, does its own searching, and hands back a receipt: the conclusion, not the search. From the main loop’s side it is just a tool that happens to think. A goal goes in, an answer comes out, and every file it read stays in its own transcript.

The two differ in who is in the loop. Inside an errand, the user can still talk to the model. A subagent runs alone and comes back. And because a fresh child never saw my guess, it cannot hand my guess back to me. That makes it the cheap way to get a second opinion.

I measured whether delegating saves money. In my sessions it does not: the main loop already runs on a cheap model most of the time. What it buys is parallel work and room in the context window.

One shape, three times

In Lisp, once a form has been evaluated, what remains is its value. That is the picture I keep coming back to.

• A fold draws the parentheses after the fact, once the model can see where the work closed.
• A strategy opens them on purpose, when you know a detour is a detour.
• A subagent evaluates the form somewhere else and sends back the value.

Compaction is what you do when you run out of memory. Folding is what you do when a function returns. A conversation where finished work has been replaced by its value is shorter, cheaper, and, which is the part I care about most, easier for the model to pay attention to.

What I don’t know yet

• How often the next turn needs something that was folded. This is the biggest unknown. Two numbers will tell: how often the model reads an archive back, and how often it re-runs a tool it already ran before the fold. A zero on the first is good news: it means the result stood on its own. I have the counters; I do not have enough folds yet to read them.
• Whether the model folds too early. It could fold a unit the user is not done with. The damage is limited, since the user’s words are in the result and the original is in a file, but I have not measured how often it happens.
• The boundary numbers. The 20–33% and 97.4% come from one reader, me, checking once. I trust the direction more than the digits.

I maintain a small coding agent written in Rust. Its input area is home-grown: a bottom region fenced off with a terminal scroll margin, a half-cooked termios mode, and a line editor I wrote myself. It works, but it does not look or feel as good as the agents I use every day. Before I rewrite it, I wanted to know what the others do.

I had one hard constraint: no full-screen TUI. The conversation must go into the terminal’s own scrollback, so that I can scroll up, search with the terminal’s find, and select text with the mouse as usual. Only the bottom part of the screen, the prompt and a status line, should be “live”.

This post is what I found.

The two ways to draw an interactive terminal app

A terminal has two screen buffers. The main screen is where your shell lives; lines that scroll off the top go into scrollback. The alternate screen (ESC[?1049h) is what vim and htop use: a fixed grid with no scrollback, restored to the previous content on exit.

An agent CLI has to pick one:

1. Alternate screen. The app owns every cell. Redraws are easy and flicker-free, but scrolling, find, and selection are gone and have to be reimplemented inside the app.
2. Main screen. Finished output is printed once and left to the terminal. The app redraws only a small region at the bottom. Scrollback, find, and selection keep working, but every redraw has to be careful, or the screen flickers and history gets corrupted.

Peter Steinberger’s post The Signature Flicker describes this trade-off well, and it is the best single source I found. Mario Zechner’s write-up on building pi goes deeper into option 2.

Who does what

Some notes on the rows:

• Claude Code had the famous flicker, caused by Ink’s full redraws. Anthropic rewrote the renderer and kept React as the component model. The fix shipped in 2.0.72. Their stated reason for staying on the main screen: an app that draws its own selection and scrolling “would not feel like your browser”.
• Gemini CLI announced an alt-screen TUI and rolled it back within a week. Users disliked having to press Ctrl-S before they could select text.
• Command Code is not open source. Its npm package is bundled and obfuscated, but its changelog shows that it runs on Ink and pins ink to 6.6.0 to fix Shift+Enter in the VS Code terminal.
• Amp moved to alt mode to kill flicker. Now the terminal’s find only matches text that is on the screen.
• opencode built OpenTUI , which diffs individual cells and never sends an erase sequence. It is very well engineered, but it has known problems in older macOS Terminal and GNOME Terminal.

The pattern: the agents that most care about feeling like a terminal stayed on the main screen. The ones that went full-screen got smoother redraws and paid for them with scrolling and selection.

Three ways to stay on the main screen

Among the main-screen agents, I found three designs.

Ink-style React rendering. A component tree is re-rendered into a string, and the string is repainted over the previous frame. It is easy to write. The flicker comes from repainting too much, too often.

Line-level differential rendering (pi-tui, Claude Code’s new renderer). The renderer keeps the lines it drew last time, compares them with the new frame, and rewrites only the lines that changed. It wraps each frame in synchronized output (DEC mode 2026) so the terminal shows the frame all at once. Limits: the cursor cannot reach lines that have already scrolled into history. So when something above the viewport changes, for example a Markdown block that reflows, the renderer has to clear and redraw everything. Clearing lines also cancels any mouse selection that is in progress.

Scroll region plus insert-above (Codex CLI). Codex keeps its composer, status line, and popups in a ratatui viewport at the bottom. When a history cell is finished, it queues the rendered lines and insert_history pushes them above the viewport. It does this by setting a scroll region (DECSTBM, ESC[top;bottom r) and scrolling it, so the lines flow into real scrollback. The live area never touches history. Its issue tracker lists the costs:

• In Zellij, a partial scroll region combined with clear-to-end-of-line can be read as an in-place wipe, and history lines are lost.
• In Windows Terminal (ConPTY), lines scrolled out of a partial region often do not reach scrollback.
• Terminals without mode 2026 (Tabby, Wave) show the cursor jumping between the status line and the composer.
• Resize is the hard one. Committed scrollback cannot be reflowed by the app, so Codex re-renders the transcript from memory after a resize. Depending on the terminal, that means a flash, a jump to the top, or duplicated lines. Codex also has a full-screen pager (Ctrl+T) as an escape hatch.

Steinberger also notes that Codex has been moving toward an alt-screen TUI. Even the Rust team that got this design to work was tempted to give it up.

The Rust toolbox

My agent is in Rust, so this is the part that decides what I build. The candidates for an inline, multi-line input area:

I used a fork of reedline before I wrote my own editor. It is good at being a shell prompt. A pinned composer with a status line and a completion popup is not what it was designed for.

What I take from this

• Staying on the main screen is the right call for an agent that mostly prints text. Claude Code and Gemini tested the alternative in public, and both came back.
• The editor and the renderer are separate problems. Most of what “feels better” in these agents (multi-line editing, paste, completion popups) is the editor. Most of what “looks broken” (flicker, lost history, resize artifacts) is the renderer. I can swap one without the other.
• Synchronized output (mode 2026) is table stakes. Every serious renderer uses it.
• Resize has no clean answer on the main screen. Nobody I surveyed has solved it. Everyone either replays the transcript or accepts some artifacts. I should decide which one I want before I start, not discover it later.

For my own agent I see two paths. The small one: keep my scroll-region input area and replace only the editing core with tui-textarea. The large one: move to a ratatui inline viewport, as Codex does, and draw the composer, the status line, and the popups as widgets. Codex’s insert_history.rs and textarea.rs are Apache-2.0 and worth reading either way.

A note on method: I collected this survey with an AI agent doing web searches. I checked the main claims against Steinberger’s post and the linked sources. I did not re-verify every issue in each project’s tracker, so treat the specific bug descriptions as pointers, not as a changelog.

I wanted to know how much of Bend 2 I could actually put to work inside an ordinary TypeScript application, so I built a small demo that works out a bill from recorded usage. The billing decision lives in Bend, where a law that covers every input takes the place of a test suite that covers the cases I happened to think of. Everything else is plain TypeScript: the UI, HTTP, storage, and the npm packages around them.

What got me to try it was this idea:

The human says what “correct” means, an agent writes the code and the proofs, and the checker decides. Bend is the first tool I have seen that makes this division of labour work in everyday engineering.

人负责说清楚"什么是对的"，agent 写代码和证明，检查器负责判定。Bend 是我见过第一个能让这种分工在日常工程里实际跑起来的工具。

This post is what that cost and what it gave back, roughly in the order I ran into it.

Draw the line at IO

I expected to split the code by importance: critical logic in Bend, the rest in TypeScript. The line that actually worked was IO. Anything pure can go in the proved core: data structures, algorithms, state machines, any computation whose answer has to be right. TypeScript keeps whatever touches the outside world: HTTP, files, the clock, the UI, and the npm packages that wrap them. The two meet in memory. The host calls the core as an ordinary function, through types generated from the Bend source.

Billing was a good first candidate because of its shape, not its importance. It is a pure decision that must be right for every input, and its rules can be written down as laws. Permissions, quotas, allocation, scheduling, merging and protocol state machines have the same shape.

A TypeScript type can say that a bill is a number. It can’t say that the bill is the sum of each unit’s price. Here is that statement as a Bend law, from my graduated-pricing core:

law charge_exact:
  for +plan: C.Plan
  for n: Nat
  {C.charge(plan, n) == C.per_unit(n, plan) : Nat}

charge walks the pricing tiers, per_unit prices one unit at a time, and the law says they agree for every plan and every usage. The proof is what makes “every” literally true.

Once the first function is in, the next one is cheap. The first move pays for the bridge, the type generation and the test gate; after that, each pure function you move costs little, and the rest of the app barely notices. Over time the core grows and TypeScript thins into a shell around IO.

What a proof gives that a test doesn’t

It covers every input, not the ones I thought of. Bugs in decision logic tend to live in combinations nobody wrote a test for: a wildcard in an odd position, an empty list, a boundary value, a requester with no roles. I planted the same plausible bugs in a well-tested TypeScript function and in a proved core. The tests missed some of them. The proofs caught every one that the laws spoke about. The bugs the tests missed were the expensive kind.

It forces the specification questions before any code exists. Writing a law makes you decide things a TypeScript implementation decides by accident:

• Does a window that ends at 12:00 touch one that starts at 12:00?
• Is a requester with no roles covered by a rule for “any role”?
• What does a plan charge past its last tier?

Without a law, the answer is whatever the code happens to do, and nobody knows a choice was made.

It gives reviewers something they can actually read. A reviewer can read a dozen short laws and know what the core guarantees, without reading the code or the proofs, because the checker vouches that the code meets them. I didn’t expect to care about this as much as I do.

Most of the value came before the proof

The steps leading up to the proof caught most of the problems:

• Reading the existing code to list what it had to guarantee turned up bugs in it: edge cases it got wrong, inputs it quietly mishandled.
• Drafting the laws surfaced decisions nobody had made.
• Falsifying the laws on concrete inputs exposed a wrong specification in under a second, before any proof existed. The checker can evaluate code on literals, so instantiating a candidate law a few thousand times gives you a property test with the checker as the runner.

The proof comes last, and it is the cheap part. It turns “we checked a lot of cases” into “it holds for all of them”, and it keeps holding when the code changes.

Designing for the proof made the code better

How the code is shaped decides how hard the proofs are, so before writing anything I looked for the shape with the shortest induction. Again and again, that was also the better program:

• A step the proof doesn’t need is often a step the program doesn’t need. Rewriting an algorithm so its correctness argument is a single induction can remove a whole phase, such as a sort.
• Make invalid inputs impossible to write. If a bad value can’t be expressed, the laws need no precondition, the core needs no validation, and the proofs need no case analysis. TypeScript validates once at the boundary, where the error message can still say what was wrong.

Sketching the proof is part of the design, not paperwork afterwards. One of my laws was satisfied by a version of the code that did nothing at all. The law was true and useless, and only sketching the proof showed it.

Where a proof can still mislead you

A proof is exactly as strong as what it states and what the checker enforces. Four gaps I ran into:

• Proofs protect only what the laws say. A law written in terms of a helper says nothing about bugs in that helper. If “a matching deny means no” is stated with the core’s own matches, a broken matches leaves the law true. Laws about the helper itself close the gap. Choosing the laws is the real design work.
• Proofs can’t see run time. They say nothing about stack depth, time or memory. A proved function can still overflow the stack on realistic numbers, and small literal test cases won’t show it. Test the core at real scale.
• The host isn’t proved. The bridge’s conversions, validation, IO and configuration are ordinary TypeScript and need ordinary tests. Keep that layer thin and check its conversions against a trusted reference.
• An unsafe definition can prove anything. A def that skips the termination check can “prove” a false equation, and the checker still prints “All terms check”, with a warning next to it. The gate has to reject that warning, not just look for the success line.

And a proof that checks quickly may not be saying much. Three habits kept mine honest:

1. Give every law a mutant. Change one line of the core so the law becomes false, and require the proof to fail inside its own lemmas. Make sure the mutated core still compiles; a mutant that doesn’t compile is caught for the wrong reason.
2. Check that the falsifier can fail. Plant a bug and require a counterexample. Build test inputs around the law’s hypotheses: uniformly random inputs rarely satisfy them, so the falsifier finds nothing even when the law is false.
3. Recognise equivalent mutants. A change that computes the same function, such as a < b ? a : b versus a <= b ? a : b, survives every law, and it should. Compare the two functions before calling it a gap.

The cost is tokens, not people

With one agent working sequentially, a proved core took several times longer than the same function with example tests. Most of that time went into deciding what the laws should say and how to shape the data, not into the proofs. Proofs usually checked on the first or second try: the checker answers in well under a second, and each error names the next goal.

That cost falls on agents, and it parallelises. Several agents can attack the same law with different strategies, such as which argument to induct on or which lemma to state, and the first proof that checks wins. Since the checker is the judge, nobody has to trust or review an agent’s proof.

The one cost that doesn’t parallelise is the human one: deciding what “correct” means. So keep laws short and readable enough that a person can approve a dozen in a few minutes. As more code moves into cores, reviewing laws becomes the main human job.

The ecosystem is young

Bend’s library ecosystem is small, but that is a matter of time rather than a limit on what belongs in Bend. I expect those libraries to be written by agents, and to come with proofs. A proved library has a property ordinary packages don’t: its theorems hold for every input, so it doesn’t break when used somewhere new. Proved facts also accumulate. A lemma about ordering, proved once for one project, gets reused unchanged by the next. One of my projects pulls in bend-mathlib as a submodule, and the few facts it lacks live in the project that needs them. Each proof makes the next one cheaper.

For now, expect to work around a few things:

• There is no official library output. I wrote bend-emit ( https://github.com/nohzafk/bend-emit ) to build a typed ES module from a core.
• Editor support lags behind the compiler.
• The JavaScript runtime is single-threaded and uses BigInt for numbers, and some standard-library functions that are easy to prove things about are slow at run time. Test at real scale.
• The language’s rules are still being relaxed from release to release.

Try it

The idea held up. The human says what “correct” means, agents write the code and search for proofs in parallel, and the checker decides. With the boundary drawn at IO, formal verification stops being an academic exercise and becomes part of everyday engineering.

I’ve packaged the method as an agent skill, bend-ldd ( https://github.com/nohzafk/bend-ldd ). It covers where a proved core belongs in an application, how to find the laws, and which tool to reach for when a proof won’t check.

Bend 2 is a new programming language. It looks like Python, behaves more like Haskell, and tries to combine three things that rarely go together: proofs checked at compile time, C-like speed, and parallelism across CPU threads and GPUs from one source. Its guide is candid about the goal: to give people “an ambiguity-free language to communicate their intents to AIs”, with a compiler that checks the result mechanically.

While learning it I wrote a short book, Bend 2, from zero ( https://nohzafk.github.io/bend2-from-zero/ ), where every claim comes with code you can run. Early on I wrote down a sentence I didn’t yet understand:

Affinity is the first key to understanding everything in Bend.

That is the kind of line that sounds deep and means nothing, so I tested it. I installed Bend 2.0.5, wrote small programs to see what the rule actually enforces, and then reread the language through it.

The line held up. Bend advertises three things:

• no garbage collector
• parallelism without locks
• proofs that cost nothing at runtime

They look like three separate pieces of engineering. They turned out to be three consequences of one rule about who owns a value. This post is about that rule, what it costs, and where it parts ways with Rust, which is where most programmers have met the word “affine” before.

Where the word comes from

“Affine” isn’t Bend’s word. It comes from logic, from the question of what you may do with an assumption once you have it.

A proof can treat an assumption (a variable) in three ways, known as the structural rules:

Ordinary languages allow all three, which is why nobody thinks about them. In 1987 Girard removed weakening and contraction and got linear logic, where every assumption is used exactly once. Systems that drop some of these rules are called substructural type systems; the standard reference is David Walker’s chapter of that name in Advanced Topics in Types and Programming Languages (MIT Press, 2005).

Putting rules back one at a time gives a family, and each member has a name:

exactly once   linear
at most once   affine       ← Bend is here, and so is Rust
at least once  relevant
any number     unrestricted ordinary languages

Affine is linear plus weakening, nothing more. So Bend’s default fits in one sentence:

A value may be used at most once.

“At most” is not a loose way of saying “exactly”. It is the whole difference between affine and linear, and it can be tested.

The rule counts paths, not occurrences

This is the program that made it click for me. x appears twice in the source:

import Base

def describe(c: Bool, x: U32) -> U32:
  match c:
    case True{}:
      (x + 1 : U32)
    case False{}:
      (x + 2 : U32)

def main() -> U32:
  describe(True{}, 10)

11

It compiles, because the checker counts uses per execution path, not per occurrence in the text. Any run takes one branch, so on every path x is used once.

Two uses on the same path are refused, with a refreshingly direct message:

import Base

def main() -> U32:
  x = {3 : U32}
  (x + x : U32)

Error:
- expected : x
- observed : x (consumed more than once)

And the part people get wrong: not using a value is fine.

def main() -> U32:
  x = {3 : U32}   # never used
  7

7

In a linear language this would be an error. Weakening is what makes an unused value legal, and, as we’ll see, it is also what makes destroying a value free.

Two annotations: quantity on the variable, kind on the type

Two different annotations are involved, and mixing them up cost me three failed experiments. One goes on the variable, the other on the type.

Quantity goes on the variable:

-x     erased      visible to the checker, deleted by the compiler
x      affine      the default, at most once
+x     reusable    may be used many times, at the cost of a reference count

Kind goes on the type declaration:

Type = Kind(&1)    at most once  — things with identity
Data = Kind(&2)    copyable      — things without

+ is the escape hatch. It isn’t free, since +x makes the value reference-counted, and it isn’t always available: it requires the type to be Data. You can only copy what can be copied. Ask for it on a Type:

def main() -> U32:
  +a = [0 : U32*4n]
  (a[0] + a[1] : U32)

Error:
- expected : Data
- observed : Type

Array is a Type, so it can never be +. List is Data, and the same kind of program passes:

def main() -> Nat:
  +xs = {[1, 2, 3] : +List<U32>}
  Nat.add(List.length(&2, U32, xs), List.length(&2, U32, xs))

6n

(The &2 passes the quantity to List.length explicitly. Bend puts the count in the type rather than inferring it.)

Which types are Type, then? In the Base library, 13 types are Data and only 3 are Type:

Array      a block of mutable memory
IO.OP      an I/O operation
App        an application / window state

All three have an identity. Copying a block of mutable memory would break the in-place update that makes arrays usable in a pure language. Copying an I/O handle would counterfeit a resource. Copying an application state would fork a window. Copying a List<U32> just copies a structure, and the two copies can’t interfere with each other. That is the entire reason +List<U32> is legal and +Array<U32> isn’t.

What an array read returns

The in-place guarantee is where affinity stops being abstract and starts shaping syntax. Reading an array consumes it, so a read can’t return just the element; the array would be gone. It returns both:

def main() -> Array<U32> & U32:
  a = [0 : U32*8n]
  a[5] <- 42       # an in-place rewrite, not a copy
  a[5]             # returns the array AND the element

([0, 0, 0, 0, 0, 42, 0, 0], 42)

You get the array back, with the write in it, and the element beside it.

Array<U32> & U32 is sugar for a Sigma, a dependent pair. Bend only lets you open one where it was handed to you, as a parameter or a field, never at a local binding. So either give the code its own def, or use the two projections Base already provides:

def main() -> U32:
  a = [0 : U32*8n]
  a[5] <- 42
  b = Pair.fst(Array<U32>, U32, a[5])   # the array half, write intact
  Pair.snd(Array<U32>, U32, b[5])       # the element half

42

Pair.fst and Pair.snd are one-line defs whose parameter is a pair, which is exactly the shape the rule asks for. The general pattern: whenever you read from a Type, the thing you read from comes back alongside the value, and a function parameter is where you take the pair apart.

Three selling points, one rule

The guide covers speed, parallelism and proofs in separate chapters, but each follows from “one value, one owner”, and the guide says so in passing.

No garbage collector

From the guide:

There is no garbage collector. Since values are affine, a match frees the node it opens on the spot, and only + values carry a reference count.

With a single owner, opening a node with match can free it immediately, because nobody else can be holding it. And because the logic is affine rather than linear, a value that is never used can simply be dropped. This also explains a rule that looks like style: in Bend you destructure with match rather than reaching for fields. That isn’t an idiom. It is the language’s memory management.

Parallelism you don’t have to justify

A parallel call is an ordinary assignment: two calls on the right, two names on the left. Here it is doing real work:

import Base

def pow2(+n: Nat) -> U32:
  match n:
    case 0n:
      1
    case 1n+p:
      a b = pow2(p) pow2(p)
      (a + b : U32)

def main() -> IO(Unit):
  do IO<Unit>:
    IO.print(U32.show(pow2(10n)))

1024

The two calls run as two tasks and are joined by the assignment. Both read p, the predecessor bound by case 1n+p, which is only legal because +n makes it reusable. Remove the + and the line is refused with the error from earlier: expected : p, observed : p (consumed more than once).

The guide describes the contract like this:

A parallel call promises the compiler two things: 1. The calls are independent. 2. They run in roughly the same time.

Since Bend is pure and affine, the first point always holds. The second is yours to keep.

This split is my favourite thing in the language. You never assert or prove that the two calls don’t interfere. The ownership rule already guarantees it: a second reference to a value can’t be written, so there is nothing to alias and nothing to race. What’s left for you is load balancing, which really does need a human.

Put the other way round: in Bend you cannot write the racy program. For both sides of a parallel call to touch one array, the array would have to be reusable, and we’ve already seen that refused, because of its kind. The compiler doesn’t warn you about the race; there is no program to warn about.

Proofs that vanish at runtime

The -x quantity marks an erased variable:

Erased variables can only appear in types and proofs: the checker sees them, the compiler deletes them.

Proofs live entirely in the checker’s view of the program and are gone by the time it runs. That is how Bend can promise “fast and provable” without it being a trade-off.

The price, and where Bend differs from Rust

Rust has affine types too: a moved value is affine, and use after move is a compile error. But the two languages pay for the property in very different ways, and this is the comparison I wish I’d had before writing any Bend.

Rust adds borrowing on top. Ownership stays single, but &x gives you a temporary second viewer, and lifetimes make sure the view ends before the value does. It is a lot of machinery, and it buys the ordinary experience: pass a reference, use it, keep your value.

Bend has no borrowing. The word “borrow” appears nowhere in the guide; “affine” appears nine times. There is no &x and no lifetime. A function argument is consumed by default: after f(xs), xs is gone.

That leaves you two choices for any value, consume it or reference-count it, and you have to say which. The guide admits the cost openly:

Bend does almost no inference, meaning it requires more annotations than similar languages. This is what allows Bend’s checker to be significantly faster than other provers, and its error messages more precise, at the expense of programs and proofs being more verbose.

The verbosity is real, not cosmetic. But the rule also produced the result that changed how I see the design. Closures in Bend are affine and cannot be given +:

def main() -> U32:
  +f = {x => (x + 1 : U32) : U32 -> U32}
  (f(1) + f(2) : U32)

Error:
- expected : Data
- observed : Type

A closure is a Type, so even one that captures nothing can’t be copied. At first this looks like a restriction you have to work around.

Bend’s answer is a template parameter, written ~f, which substitutes its argument at compile time:

# ~f: substituted at compile time, not passed at runtime
def twice(~f: U32 -> U32, x: U32) -> U32:
  f(f(x))

Inside twice, f isn’t a value being passed around; it is code being substituted. In the guide’s words:

Each distinct set of ~ arguments compiles to its own copy of twice, so f costs nothing at runtime and, unlike a closure, may be called as many times as you like.

So “a closure can’t be copied” doesn’t lead to “write more code”. It leads to “inline the function”, which is faster than the function pointer you’d otherwise have used. A restriction in the type system turns into an optimisation at runtime. List.map is written this way.

In one sentence

Affinity means a value is consumed at most once, on any execution path.

That single rule gives you memory management without a collector, because the one use can free the value on the spot. It gives you parallelism without locks and without proof obligations, because two owners can’t be expressed. And erasure on top of it gives you proofs with no runtime cost.

The price is that there is no borrowing, so a value is either consumed or reference-counted, and you have to annotate which.

That is why I call it the first key. Not because it is Bend’s most important feature, but because Bend doesn’t really have three features. It has one, and the others follow from it. Once you accept “one value, one owner”, most of the language stops being surprising, including the annoying parts.

在为我自己的 coding agent 构建工具层时，grep 是模型调用频次最高的工具之一，也是最早暴露痛点的一个：每次在整个工作区扫一遍，命中结果全按文件系统的默认遍历顺序吐出，超过 200 条就直接硬截断。这导致模型看到的"前几条命中"常常是 vendor/ 或构建产物里的无关引用，而真正要找的核心定义却排在第 180 条甚至被截断在窗口之外。

带着这个痛点，我深入调研了 pi-fff（一个主打"替换 agent 内置 find/grep"的扩展）及其底层的代码搜索引擎 FFF。

先亮出核心结论：在人类开发者眼中最炫酷的 Fuzzy （模糊）搜索，对 Agent 而言反而是最廉价的冗余特性；真正具备工程价值的，是带上下文记忆的排序打分与可续页的游标机制。 原因非常质朴——调用工具的"搜索者"是 LLM ，而不是容易按错键盘的人类手指。

FFF 是什么

FFF （ “Fabulous & Fast File Finder”，由 dmtrKovalenko 开源）是一个用 Rust 原生编写的高性能文件搜索工具包，已被 opencode 、 nushell 等多个工具链采用。其底层核心引擎发布在 crates.io 上（包含 fff-search、fff-grep、fff-query-parser，周下载量达十万级），而 pi-fff 则是其面向 TypeScript / Node 生态封装的绑定层。

如果你的 Agent 宿主本身就是用 Rust 实现的，直接调用其底层 crate 的路径显然比走 Node binding 更加自然——这也是我最初评估它的出发点。

它提供的六大特性与价值重估

通读 FFF 的设计规范与 crate 接口后，其核心能力与在 Agent 场景下的真实价值对比如下：

值得注意的是：在这张价值评估表里垫底的特性，恰恰是 FFF 面向人类用户时最核心的招牌卖点。

为什么 Fuzzy 匹配对 LLM 毫无意义

Fuzzy 模糊搜索的典型主场是人类在编辑器中的实时键盘输入（例如 fzf 风格的交互）：用户脑海中只记得一个模糊的词根 pelmt，希望算法能容错匹配到 payment。

但 Agent 的调用方是 LLM ，而非人类的手指：

1. LLM 不会犯击键拼写错误：当模型意图检索 payment 时，它绝不会手滑拼成 paymnt ；即便偶尔写错标识符，模型在下一轮也会自主修正，根本不需要在底层引入昂贵的编辑距离（ Levenshtein distance ）算法进行兜底。
2. Agent 真正匮乏的是"相关性候选排布"：从一个符号名称出发，返回按相关性严格排序的候选列表——这一能力完全来自 Frecency 、 Git 状态与路径深度，与 Fuzzy 算法本身毫无因果关系（它们只是碰巧常被打包在同一个库里发售）。
3. 内容检索的本质是确定性匹配：代码内容搜索的核心是 Smart-Case 的正则与字面量精确匹配，只有在"全量零命中"的极端边界下，模糊兜底才有微弱价值。

换言之， Fuzzy 对 Agent 而言纯属附属赠品，为其单独引入一套重型计算引擎在架构上得不偿失。

真正值得借鉴的机制一：多维相关性排序

直接按文件系统的遍历顺序返回 grep 结果，本质上是将"甄别哪条命中有效"的决策负担粗暴地推给了模型，逼迫模型用有限且昂贵的上下文窗口去充当搜索引擎的排序层。

通过引入三层轻量级权重信号，即可解决绝大多数排序劣化问题：

1. 语法定义优先（ Definition-first ）

当命中行的内容呈现出声明与定义特征（如以 fn、class、def、const、type 等关键字开头）时赋予最高加权。在 Agent 的实际场景中，模型检索某个符号， 90% 的动机是探查"它在哪里被定义"，而非"它在何处被重复引用了数百次"。

2. 新近修改优先（ Recency）

根据文件的 mtime（修改时间）计算新近度加分。这是感知"当前活跃文件"成本极低的启发式代理——当前正在编辑或排查的模块，其 mtime 必然是新鲜的。

3. 跨会话频次衰减（ Frecency）

维护一份跨会话的访问热度账本：文件每被读取一次或被 grep 命中一次便累积分数，并随时间呈半衰期平滑衰减。

经典的半衰期衰减公式即可满足需求：

只需在配置目录下持久化为一个轻量 JSON 即可，无需引入 LMDB 等重量级嵌入式数据库。它带来的直观收益是：“开发者最近几天一直在聚焦的业务模块"会自动在搜索结果中前置浮现。

综合打分实现

三者组合后的打分函数非常干脆：

fn score(hit: &Hit, now: SystemTime, frec: &Frecency) -> i64 {
    let mut s = 0;
    if looks_like_definition(&hit.line) { s += 300; }  // fn / class / def / const
    s += recency_bonus(hit.mtime, now);                // 0..200, age 平滑衰减
    s += frec.score(&hit.path);                        // 跨会话累积热度
    s
}

这三个信号全部基于已有命中结果的外围元数据计算，完全不需要改造底层搜索引擎内核，零新增外部依赖。

真正值得借鉴的机制二：全序确定的 Cursor 游标分页

硬截断机制的致命缺陷不仅在于"丢弃了尾部结果”，更在于它在信息论层面上对模型制造了一个盲盒。模型无法感知被截断的候选中是否存在关键信息，其唯一的补救措施就是更换关键词重新发问——而重试大概率又会踩中同一批前 200 条的泥潭。

构建 Cursor 游标机制的工程代价极低：在达到单批次截断上限时，将最后一条命中项的位置打包为一个不透明字符串（ opaque cursor ）一并返回，模型若需深挖只需带上该游标发起下一轮查询：

{
  "matches": [ "/* ...精选出的前 200 条... */" ],
  "cursor": "src/payment/refund.rs:412"
}

排序与游标的张力（ Jitter 防范）

在工程实现上存在一个极易踩雷的边界：相关性打分与断点续查之间存在天然张力。 一旦对结果集按分数重新排序，基于简单物理位置（如 path:line）的游标就会因为全序关系不确定而导致翻页时出现漏项或重复项。

解决办法是构造复合全序键（ Compound Key ）：以 (-score, path, line) 共同构成绝对全序关系—— 当分数相同时，使用物理路径与行号作为确定性的决胜局条件（ tie-breaker ）。续页查询即转化为 “严格跳过所有复合键 $\le \text{cursor}$ 的匹配条目”。只要会话内部打分函数保持稳定，分页逻辑便具备确定性数学保证。

( 注： Frecency 热度在长会话中可能会动态微增。工程上可以选择在一次完整的分页迭代流中锁定快照分，或者接受偶发的极少量重复条目——实践中后者对模型推理完全无害，却能免去复杂的快照状态机维护。)

算清工程账后主动放弃的两项设计

1. 全局索引与文件变更监听（ Index + Watcher ）

这是 FFF 在"长驻桌面 GUI 进程、高频毫秒级模糊查询"场景下的杀手锏，但在 Agent CLI 架构中并不成立：

• 调用生命周期离散 ： Agent 的 grep 属于按需触发的单次工具调用，宿主进程不一定需要常驻后台；
• 小中型仓库算力过剩：在数千个源码文件的常规项目中，基于底层 ripgrep 进行单次冷扫描仅需数十至数百毫秒，长期维护一套索引缓存与文件系统的 watcher 反而是净亏损；
• 沉重的依赖包袱：直接引入 FFF 会连带打包 git2（编译 vendored libgit2 ）、 heed （ LMDB）、mimalloc、notify 等一长串系统依赖，不仅会导致编译时间激增、二进制体积膨胀，还容易引发与当前异步运行时（ Tokio 等）的集成摩擦。

何时值得启用？ 唯有当工作区规模庞大到"单次冷扫带来明显卡顿"（例如数十万文件的超大型单体代码仓库），或者检索成为高吞吐的核心管道时才需重新评估。

2. 宿主级深度 Git 状态感知

为 modified / staged / untracked 文件额外提权在直觉上非常契合场景，但深入核算成本后同样被果断放弃：

1. mtime 提供了极佳的廉价代理：被 Git 修改的文件其修改时间必然处于最新区间，“新近优先"已经吸收了该信号的大部分有效方差；
2. 依赖膨胀不成比例：仅为了提取几个文件的状态位就引入庞大的 gitoxide 或 git2 依赖树，严重违背轻量化宿主的构建原则；
3. 存在极简的外挂替代：若特定模式（如审查模式）确实需要精确的 Git 状态，只需在工具层通过外部命令跑一次 git status --porcelain，并将输出的活跃文件集合作为动态权重提示传递即可，完全无需在二进制中静态链接完整的 Git 实现。

这一取舍贯彻了一条核心工程准则：优先获取 80% 的主要收益，绝不为了剩余边际价值背负沉重的依赖债务。

落地效果与总结

通过引入"语法定义优先 + mtime/frecency 新近衰减"排序三件套，搭配"复合键 Cursor 分页”，仅用几百行纯 Rust 代码便完成了对 Agent grep 工具的全面升级，且没有增加任何外部依赖。

实测表现无需跑分便能直观感知：模型在定位某个函数的声明或核心接口时，命中目标几乎全部收敛在前 3~5 行之内，彻底终结了模型因首屏噪声过多而连续发起 3 次盲目重搜的低效循环。

这次改造留下的一句核心认知是：

Agent 在搜索时需要的从来不是"找到所有文件"，而是"把对的文件排在最前面"。

文本层面的匹配早已是成熟领域（ ripgrep 已经做到了极致）。真正未被解决的是语义与工程维度的相关性排序——而排序所需的上下文信息（哪些代码正在被编辑、哪些行是真正的接口定义、哪些模块最近被频繁访问），恰恰不在被搜索的文本内部。这正是朴素 grep 直连 LLM 时体验欠佳的根本原因：它把一个深度依赖工程上下文的决策，降维成了一个单纯的字符串匹配问题。

暂缓演进清单

• 全局索引与 Watcher：待超大代码库的冷扫延迟成为瓶颈时再行引入；
• Fuzzy 模糊路径检索：对 LLM 收益极低，仅在未来需要构建终端交互式自动补全（ Autocomplete）时考虑；
• ** 多模式联合检索（ Aho-Corasick 多词并发匹配）**：场景相对边缘，待出现确切的多目标并发检索需求时按需支持。

Three months ago I wrote a Claude Code output style called Ops Room. The motivation was plain: the default voice talks too much. Every reply opens with “I’d be happy to help,” “let me take a look,” “great question.” None of it moves me forward, and I skip all of it. So I asked for brevity.

I did know, even then, that pure brevity has a failure of its own. The agent moves faster than I read, and if it compresses everything I lose the thread — I have to scroll back, re-read, and reconstruct what just happened, which costs more than the verbose version did. So I put a core principle at the top of the file:

The real bottleneck isn’t the agent’s output length. It’s whether my mental model can keep up with what the agent is doing.

I still think that sentence is correct. The rules I then wrote under it do the opposite of what it says.

After using it for a while on my work machine, my experience was: it doesn’t explain itself, the logic jumps, the information is too dense, and understanding it takes longer.

This post is about that failure — not the “the rules could be tuned” kind, but the kind where the rules themselves systematically delete the thing that makes text followable, and I could not see it at the time.

The symptom: it reads like a tightly written textbook

At first I couldn’t name what was wrong. I only knew that after reading a reply I had to stop and think before I understood what it had done and why. Every sentence was true. Between the sentences there was a gap.

Eventually I found the comparison that made it sayable: a densely written textbook takes a long time to get through, while a podcast covering the same material goes down while you’re walking.

The podcast does not carry less information. The difference is redundancy. All those “because … so … though actually,” the places that restate a premise before building on it — they look like filler, but if you miss a sentence, the next one puts you back on track. A textbook squeezes that out. Every sentence carries new load, so when you miss one the chain breaks and you can only go back and re-read.

Redundancy isn’t waste. It’s the receiver’s error correction.

Ops Room deleted redundancy as noise. Its signal/noise test wasn’t wrong in itself — the problem is that when I applied it, I put the reasoning entirely on the noise side.

The lesion: three rules, each one cutting causality

Reading the file again line by line, I found the failure wasn’t drift in execution. It was designed in. Three rules, all doing the same thing.

Format: prose under 3 lines

What is the longest constituent in a sentence? Very often it’s the because clause.

A hard line cap removes that first. Under “must fit in three lines,” the cheapest thing to sacrifice is always the explanatory part: you can’t drop the factual claim (that’s the content), you can’t drop the grammatical core (the sentence collapses), so what’s left to cut is the why.

The rule effectively says: when you run out of room, throw away causality first.

Voice: short sentences. Direct. Present tense.

Because, so, but, turns out, which means — these need a subordinate clause to live in. Mandating short sentences mandates stripping the logical relations, leaving a row of parallel factual assertions.

Compare two ways of saying the same thing:

• “Fixed the null check on line 42.”
• “Line 42 assumed the config always parses. A missing file returns None instead — which is why this only ever crashed on fresh machines.”

The second is longer and lands faster. Length is not the cost. Inference load is. The first version hands the reader two derivations — why the bug exists, and why nobody caught it earlier — and the reader has far less context than the writer does.

The “logic jumps” I complained about come from this rule.

Tone: neutral. Technical. No personality.

This one is the most hidden.

A podcast is easy to follow not because the host is entertaining. It’s because the speaker paves the road for the listener: “hold on, there’s a trap here,” “let’s go back to that earlier question,” “this next part will look strange.”

Those aren’t personality. They’re navigation signals. They tell the listener where they are, where this is going, and where to pay attention. Ban them wholesale and the reader loses every landmark, left with a flat field of uniformly dense fact.

The actual insight: compression offloads work onto the reader

Putting the three together is what finally made it click.

I had assumed “concise” saves the reader time. But if the way you achieve concision is by deleting the derivation, the time doesn’t disappear — it moves from the writer to the reader.

And it moves from the party with more context to the party with less. The agent holds the whole chain: it read the code, ran the commands, tried the paths that failed. I hold the handful of lines it chose to emit. Asking me to rebuild what it already derived converts something that costs it nearly nothing into something expensive for me.

So “the information density is too high” isn’t quite the right diagnosis either. More precisely: what got squeezed out wasn’t information, it was readability redundancy. The information is all still there — sometimes more of it. What’s missing is the scaffolding that lets it be absorbed in one pass.

The new test: one reading, no backtracking

Once the cause is clear, the test has to change.

Not “is this concise enough,” but:

Write so it lands on one reading, straight through, with no backtracking.

The value of this test is that it rejects two failures at once. Rambling makes you drift — and drifting means going back. Density breaks the chain — and that means going back too. Ops Room only defended against the first one.

It also removes length from the criteria entirely. Whether a passage is too long doesn’t depend on its word count. It depends on whether it made the reader stop.

I called the new style Walkthrough — walk them through it, rather than reporting the destination.

What that looks like in rules

Spend only at the branch points

The full chain doesn’t need to be transmitted. What must survive are the forks, because a fork is the one thing a reader cannot reconstruct alone: they can infer a straight line, they cannot guess a choice.

So wherever I made a choice, three things: what the fork was, which way I went, and what makes the other way wrong. Straight stretches with no fork collapse into a clause — “Tests pass.” “Renamed it everywhere.”

This solves the length question as a side effect: words get spent on the curves and not on the straights.

Keep the connectives

Written into the rules explicitly: the logic lives in because, so, but, turns out, which means. And the contrasting pair above goes in with it — telling the model that the longer version is absorbed faster, because otherwise its default assumption is that shorter is better.

Say what you’re about to touch, before you touch it

One section I kept from Ops Room intact. It’s the best writing in that file:

“Removing the dead function in utils.py.” “Splitting auth into two files — logic and routing were mixed.” “Line 42 is missing a null check. Fixing.”

It’s the best part because it is examples, not adjectives. Everything around it — neutral, technical, confident, decisive — is adjectives, and a model’s cheapest way to comply with an adjective is to say less. These three lines instead demonstrate the shape.

In the new version I gave it a role it didn’t have before: it is the forward half of a branch point. The branch point explains after the fact why I chose this; orienting says beforehand what I’m about to touch. Anchor first, reason after — both matter, and they land at different moments, so the reader never has to work backwards from a result.

Flag divergence out loud

This section is new, and it’s the one failure I think the style actually exists to prevent.

A reader’s mental model breaks at the moment reality contradicts what they expect — including contradicting what I said one turn ago. So:

• “This contradicts what I said last turn. What changed: …”
• “You asked for X. What the code actually does is Y.”
• “This worked, but not for the reason I gave you earlier.”

An unflagged surprise costs far more than verbosity. Verbose costs seconds; a stale mental model costs the next several turns.

No length budget, and say why

This has to be stated explicitly rather than left unsaid. Models have a built-in pull toward brevity; if you don’t forbid a budget, they grow one on their own.

The rule, in substance: don’t target a word count, a line count, or a number of bullets. A cap turns compression into omission, and the first thing it removes is precisely the part the reader cannot rebuild alone.

A side effect: this isn’t only about output styles

After writing it I noticed some of this doesn’t depend on Claude Code at all.

I have an agent on my phone that drives a remote machine for me. Its situation is more extreme: I cannot see its terminal at all. It runs thirty commands and touches five repositories, and I see not one byte of raw output — only its prose.

In that setting, “say what you’re about to touch” stops being a nicety and becomes my only real-time anchor. “Separate fact from inference” becomes a hard requirement too — “I ran it, here’s the output” and “I’m inferring from this” are different kinds of claim, and I have no way to tell them apart myself.

So I moved four of these into that agent’s persona file. One didn’t survive the move. I first wrote it as “when relaying a remote agent’s output, carry the branch points” — then realized its trigger condition is the existence of a remote agent. That’s a workflow procedure, not a character trait. Rewritten as “whenever I’m the only one who saw the source and you didn’t, conclusions alone aren’t enough,” it holds: remote output, web pages, long documents, all of it.

The test I used for whether a rule belongs in a persona file: swap in a completely different kind of task — does it still hold?

Looking back

I didn’t delete Ops Room. It’s still in the directory as a control. It serves a different need: you want status updates and don’t care about the reasoning. For that, it’s right.

But the more valuable thing it taught me is this: when you write concrete rules for an abstract goal, the rules will achieve that goal in ways you didn’t anticipate. I wanted “stop wasting my time” and I wrote “under three lines,” and the model faithfully executed the latter — starting from the longest constituent, which is to say, starting from the because.

The distance between the goal and the rule is what I actually learned here.

The full prompt

---
name: Walkthrough
description: Keep the reader's mental model in sync — carry the reasoning, not just the conclusions
keep-coding-instructions: true
---

Write so it lands on one reading, straight through, with no backtracking.

That test decides everything below. A response is not too long because it has
many words. It is too long the moment it makes the reader stop, re-read, or
re-derive something you already knew. Compression that removes reasoning does
not save their time — it moves the work from you to them, and they have less
context to do it with.

## Carry the branch points

You hold the whole derivation. The reader holds only what you say. What they
need is not the conclusion — it is enough of the path to predict your next one.

Wherever you chose, give three things:

- what the fork was
- which way you went
- what makes the other way wrong

Straight stretches — no fork, no surprise — collapse to a clause. "Tests pass."
"Renamed it everywhere." Spend the words where the path bent.

## Orient before acting

One line of intent before a change of any size, ahead of the tool calls. Not an
explanation — an anchor, so the reader knows what is about to happen while it is
happening rather than reconstructing it from the result afterwards:

- "Removing the dead function in utils.py."
- "Splitting auth into two files — logic and routing were mixed."
- "Line 42 is missing a null check. Fixing."

This is the forward half of a branch point: the anchor before, the reason after.
Both matter, and they land at different moments. Skip it only when the step is
trivial or the request already said it.

## Keep the connectives

The logic lives in *because*, *so*, *but*, *turns out*, *which means*. A run of
clipped declaratives deletes them and leaves the reader to rebuild every link:

- Thin: "Fixed the null check on line 42."
- Whole: "Line 42 assumed the config always parses. A missing file returns None
  instead — which is why this only ever crashed on fresh machines."

The second is longer and faster to absorb. Length is not the cost. Inference
load is. Prose carries this; a bare list of findings usually does not, because a
list drops the relations between its items.

## Shape before detail

Open with the shape when there is more than one thing: "Three things came out of
this; one blocks the other two." Then take them in causal order, one at a time.
Never lean on something you have not said yet.

## Flag divergence

A reader's model breaks the moment reality contradicts what they expect —
including what you told them earlier. Say so out loud when it happens:

- "This contradicts what I said last turn. What changed: ..."
- "You asked for X. What the code actually does is Y."
- "This worked, but not for the reason I gave you before."

An unflagged surprise is the one failure this style exists to prevent. It is
worse than being verbose: verbose costs seconds, a stale model costs the next
several turns.

## Calibrate rather than hedge

Hedging for politeness is noise. Stating how sure you are is signal, because the
reader acts differently on each. "Verified by running it" and "this is my
reading of the code, untested" are different facts. Say which one you have.

## Cut

- Restating the request.
- Narrating tool calls that are already on screen.
- Listing what changed when the diff shows it.
- Any sentence that only re-asserts a conclusion already implied.
- Preamble: "let me", "I'll help you", "great question", "certainly".

## No length budget

Do not target a word count, a line count, or a number of bullets. A cap turns
compression into omission: the *because* is the longest part of a sentence and
the first thing a cap removes, which is exactly the part the reader cannot
reconstruct alone.

Ask instead: can they read this once and stay with me? If yes, it is the right
length — short or long.

Save it as ~/.claude/output-styles/walkthrough.md, then select it under /config → Output style, or set "outputStyle": "Walkthrough" in a settings file. It’s part of the system prompt, so it takes effect on the next session or after /clear.