Appearance
Context
The context spine. Every turn pays for whatever sits in the window, so this module's whole job is to keep that window small and deliberate across a session's entire life: inject a project's context files at startup, stamp the wall clock into every turn, compile a per-task bundle for print mode, read a slice of code instead of the whole file, generate the primers a fresh agent reads instead of the tree, capture a stray idea or a backlog item into its log without derailing the task, carry a handoff across a compaction or a blown token budget, arbitrate whatever wants a word at the end of a turn, and meter the lot so a session cannot quietly balloon.
It ships as eleven parts under one module id, all grouped under context in the install picker. injection-engine (SessionStart, drawn as engine) and nudge (turn end) sit together under the injectors subgroup, engine, modes, and backlog under capture, writer and cleaner under handoff, and clock, files, budget, and lookup sit directly under the group. Capture folded in on 2026-08-25 as one appender behind every log the harness keeps, instead of three commands each growing its own copy of the same append-a-line logic, backlog landed on top of it, and the turn end injector landed last as the layer the six hand-rolled Stop hooks had been doing badly one at a time.
The turn end layer is armed in this repo as of M6.B, 2026-09-10. nudge.nu (Stop) and prime.nu (PostToolUse) are both merged into .claude/settings.json here, and backlog-nudge.nu, the last of the six hand-rolled Stop hooks still standing, is gone; the backlog entry in nudge/defaults.nuon replaced it. mod-doc-nudge.mjs and telemetry's own notify hook still run standalone alongside nudge.nu, because their turn end entries (mod-doc, telemetry-spend) ship disabled, they count through modules that never install into a project. Read the sections below as live behaviour in this repo, not as a shipped design still waiting on an install.
In Practice
Start a session with the standard context files in place. At SessionStart, inject-project.nu hunts .claude/ then the project root for PROJECT.md, STYLE.md, DESIGN.md, and ROLE.md, and injects each one whole, wrapped in its own xml tag. Where PROJECT.md sits only at the root, the injector leads with the shipped root preamble:
<context>
project context, full file, no distilled cache exists yet:
...file contents...
</context>A project missing a file gets the bare missing line instead, no empty tag pair left behind, and the TASK*.md and HANDOFF*.md listings print their multiple preamble and a summary row per file, untagged, telling the agent to ask which to pick up rather than reading every one of them. The tag is built into the injector itself, not a pre/post hook: those fire once per matched file and each half spawns a Nushell subprocess, so an all: true entry like TASK*.md would pay two subprocesses per row if it tried to wrap itself that way. The tag wraps the whole entry instead, one pair round the preamble and every file under it, for free.
Stamp the turn with the time, and the date when it moves. clock.nu runs on every prompt (a UserPromptSubmit hook, the one turn boundary the api allows) and writes a bare time: line most turns, but the full time & date: stamp on the session's first prompt and on any day change, so a line that changes shape reads as an event where the same line every turn would read as wallpaper. A day change also fans out whatever events.nuon lists, a line to inject or a script to run.
Let one hook decide who speaks at the end of a turn. With the nudge part installed and its hooks merged, a stop runs nudge.nu once. It folds nudge/defaults.nuon and the project's nudges.nuon through the injection engine's loader.nu, keeps the entries whose trigger is turn-end, works out which signals are live this turn (always unconditionally, wrap-up when finn's last real message matches a pattern in the wrap_up table, todos-done when the last TodoWrite call reads every item completed), drops whatever refire says has nothing new to report, asks each surviving ledger entry's own script for a count, ranks the survivors, caps at max_per_turn, and emits one blocked stop:
turn-end injectors, 2 item(s) want a word before you stop.
1. wiki, the generated wiki is stale, 64 source file(s) pending
-> run `nu "<project>/.claude/hooks/wiki/wiki-recap.nu"` for the regen brief, only once he has greenlit it
2. handoff, a wrap-up signal matched n the leftover-work gate has not been worked this turn
-> read the gate in `.claude/commands/handoff.md`, work it, n if it passes ASK him in a plain message first, do NOT write the doc til he says yesThe numbered lines are built from each entry's own say and do strings with {n} filled from its count and {project} from the forward-slashed project dir, and the tail tells the agent to put the items to finn as one AskUserQuestion call rather than acting on any of them. Set ask: false and the same items come out as the written form instead, for print mode and cloud sessions where nobody is there to answer a picker.
Capture a stray idea instead of derailing the task. Something worth keeping surfaces mid session, so it goes to its log in one line and the task carries on:
/capture style e.g. n i.e. should keep their fullstopscapture.nu resolves the mode's scope (harness, project, or home) and dest off the two-tier mode list, the harness's own store/capture-modes.nuon first, then a project's own .claude/capture-modes.nuon overriding a same-named record. It renders the entry in whichever shape the mode declares (bullet, block, or row), creates the file with its title header on first write, and appends. The harness ships five modes: style (a finn-style change, drained later by /apply style), installer (an idea for the harness manager, capture-only, kept out of the general backlog), backlog (routed by backlog.nu rather than called directly), decision (a settled fork, wrapped as /decision), and term (a glossary row, wrapped as /term). A mode may name a pre and a post script: pre can re-render the entry, replace it outright, or skip the capture, post runs after the write for side effects, and both fail open, a missing or broken hook reports itself on stderr and the capture still lands unmutated. /decision and /term are generated wrappers over the exact same engine, rebuilt with capture.nu wrapper <mode> rather than hand edited, so the logs cannot drift into three different shapes.
File a backlog item without deciding which log it belongs in. A project holds a BACKLOG.md at its root, plus an opt-in one per folder (globbed in backlogs.nuon, tools/* and tools/*/* are the typical pair) and one per running session, and each of the three carries a DONE.md and a DEFERRED.md beside it:
nu .claude/backlog/backlog.nu add "**wire the retry into the client too**" --near src/client.nubacklog.nu walks up from src/client.nu to the nearest folder that owns a backlog, falls back to the project one when nothing does, and hands the resolved path to capture.nu as --dest, so the routing lives with the half that understands folders and the appending stays with the one script every log in the harness goes through. list shows the open items by line number, and line numbers ARE the addressing, they shift after every close so list gets re-run rather than an old one reused. close <line> moves an item into DONE.md beside it, marked done or --stale when it was dropped rather than built, and nothing is ever deleted. --stale also covers an item absorbed into another: with no amend or merge verb on backlog.nu, and a hand-edited BACKLOG.md banned outright, folding one item into another is two closes and one add, close the absorbed item --stale, and when the surviving item's own text has to change to carry the note, close and re-add that one too, with the pair sitting next to each other at the top of DONE.md recording the merge.
An item finn can't call yet goes to the maybe-keep-maybe-drop pile instead of sitting in the live list or being dropped outright:
nu .claude/backlog/backlog.nu defer 7 --why "keep if the tools folder actually happens"--why is required, it is the condition that would turn the item back into a keep and the question check asks when it resurfaces the item. deferred lists the pile the same way list does, with the condition and how many times it has already been shown, and revive <line> brings one back at the bottom of the live list, defer state cleared. check runs both clocks in one pass: ask_after days in the top 3 gets reported for finn to answer, drop_after days moves an item from the live list into DEFERRED.md rather than closing it outright, and a deferred item only drops once it has actually been shown drop_asks times, sat deferred_after days, and gone a further ask_deferred days since that last showing, all three and never any one alone. Counting showings rather than calendar days is what stops a month nobody opens the project costing a deferred item anything, and the third gate is what stops the final showing being a formality, without it an item was dropped by the very next check after the one that filled its quota, minutes later.
An example outcome. top is the nudge payload, the top 3 open items plus the total, and count folds in whatever's due a showing in DEFERRED.md too, so a backlog that's empty on top but has a full deferred pile waiting still reads as nonzero and still gets surfaced.
Compile a bundle for one task, for print mode. compile-context.nu assembles a per-task system prompt and prints it to stdout:
claude -p "the task" --append-system-prompt (nu .claude/context/tools/compile-context.nu "the task")It stacks the role bare, then the project rules and the global rules each wrapped in <rules>, then asks the lessons store which domain the task routes to and folds in that slice wrapped in <lessons>, and finally appends whatever a .claude/context.nuon manifest lists, bare. With no .claude/ROLE.md set, the bundle carries a one line ## suggested role note naming whatever role-route.nu ranked highest, a suggestion to adopt with /role, never an automatic adoption. Any missing piece skips silently.
Read a slice, not the whole file. read.nu pulls the enclosing block and nothing else:
nu .claude/context/tools/read.nu symbol scan-script --path .claude/context/tools/script-registry.nuIt prints a # <file>:<line> block lines X-Y header then just that block. sig lists the signatures as an outline, grep <pattern> --context 2 returns matches with context as a table, and --dedup remembers what it already showed this session, so a repeat read hands back a pointer instead of the dump again (forget clears the cache). It is pure Nushell by design, no rg, probe, or ctags, so it never dies on a missing tool.
Meter the hot tier when a session feels heavy. context-stats.nu checks each always-loaded file against a soft line cap:
nu .claude/context/tools/context-stats.nuA breach reads warning, <file> is fat, <N> lines against a soft cap of <cap>, its paid on every turn, move detail to cold storage behind a pull rule, and the full table of lines, tokens, and caps comes back either way. The caps are advice, it never edits anything.
Survive a compaction with intent intact. Just before the window compacts, precompact-handoff.nu has sonnet read the transcript and write .claude/HANDOFF-compact.md, a repo diff summary appended so the fresh session knows what changed on disk. The compact-matched SessionStart hook inject-compact-handoff.nu then injects it back wrapped in <handoff>, leading with "written seconds before this compaction, treat it as the freshest statement of intent, it beats the compacted summary where they disagree, verify claims against the actual code before acting on them," and archives the file into archive/context/ dated so it never leaks into a later session.
An example outcome. Arm the budget gate with harness config --part budget and a session that climbs past occupancy_soft gets one nudge on its next tool call, naming the meter that tripped and telling the agent to finish the piece it is on and offer a handoff, while the call itself still goes through. Past occupancy_limit the same gate writes HANDOFF-budget.md, refuses every tool bar a write to a HANDOFF-*.md sitting directly in handoff_dir, and tells the agent to echo the configured banner and end its turn. Set weekly_soft instead and the same nudge reads the subscription's own numbers rather than the session's, for example the weekly rate limit is 31% full against a 5% soft limit, it resets in 4d 22h – the reset clause is what makes it actionable, the percent alone doesn't say whether that wait is two hours or five days. There is no process kill either way, restarting the session is a hand action, and any detection error fails open to exit 0 so a broken meter never bricks a session.
Backlog Scopes
| scope | the file | who opts in |
|---|---|---|
| project | .claude/BACKLOG.md | always, the fallback every unrouted item lands in |
| folder | <folder>/BACKLOG.md | a glob in backlogs.nuon, so most folders never get one |
| session | .claude/backlogs/<session id>.md | automatic, renamed to a handoff's slug on the way out |
Each of the three carries a DONE.md beside it (all items ever closed, newest at the top, a session's own items close into the project DONE.md rather than a per-session one nobody reads) and a DEFERRED.md (the undecided pile, one clock's worth of days and showings away from a keep or a drop).
The Injection Engine
The part is injection-engine and its folder is still injectors/, because the rename moved the name and not the files. It draws in the picker as context/injectors/engine, off a display-only label in the manifest.
inject-project.nu
The SessionStart hook – hunts .claude/ then the project root for PROJECT.md, STYLE.md, DESIGN.md, and ROLE.md, injects each whole, and lists every TASK*.md and HANDOFF*.md it finds as a one-line summary row rather than the file. An entry's field set is name kind where custom enabled recurse depth ignore all inject tag pre post msgs, plus trigger, which says when it fires and reads as session-start when absent, so this hook filters the table down to its own trigger and every shipped entry is untouched by the field existing. kind defaults to file and can instead be text (a literal string), script (run and inject its stdout, regenerating and injecting in one act so nothing sits stale on disk), or nuon (a pointer at another table under .claude/inject/, expanded through a loop with a four-deep cap so two pointers cannot hang a session on each other). A glob name is matched case sensitively via a rebuilt regex, so HANDOFF*.md no longer catches a lowercase handoff.md template on Windows the way it did before 2026-08-07. A frontmatter block is stripped from every injected file and that strip cannot be switched off; pre and post run either side of it, per matched file. The entry registering this hook in settings-fragment.json sets timeout: 15, generous room for a kind: script entry that runs the project's own code at session start, and pairs it with .claude/scripts/nu-note.nu, the bundled-nushell interpreter note. The part also declares read-front, nu-note, and strip-frontmatter as hard-needed generic scripts, so one shared copy of each lands at .claude/scripts/ however many parts want it.
loader.nu
The extracted entry fold – reads a shipped defaults table, merges a project-owned diff over it by name, expands kind: "nuon" pointers, drops whatever is enabled: false, and hands back the entries for one trigger. It ships with this part and the turn end half calls it by path, never through a use: a use resolves at parse time, so a missing loader would take the whole hook down rather than costing it its entries. Note the session start hook still runs its own inline copy of the same fold – inject-project.nu keeps read-table, merge-in, merge-entry, and expand-nuons as private defs (its version carries a per-entry warning label the loader's does not), so loader.nu is the shared rule as written down rather than the one code path both triggers actually execute. The manifest and the part's USAGE.md describe it as the fold both triggers read through, which is the intent rather than the wiring on disk today.
defaults.nuon
The shipped context-file table – one record per file, PROJECT.md through HANDOFF*.md, plus two trailing kind: "nuon" pointer entries, inject-scripts and inject-resume, living beside the hook so the set is editable without touching a script. It ships tag: "context" for PROJECT.md (finn's naming, it is THE project context block), tag: "style", tag: "design", and tag: "role". The TASK*.md and HANDOFF*.md entries carry no tag and ship inject: false, because they emit a summary row per file rather than the file itself. A pointer entry ships here rather than in the project-owned contexts.nuon because this file is the one an update refreshes, so its wiring reaches every install already on disk and not just a fresh one: inject-scripts resolves inject/scripts.nuon, below, and inject-resume resolves resume.nuon, the resume module's own session-start offer, folded in this way so resume lands without registering an eighth hand-rolled SessionStart hook. A project missing the pointed-at file, resume.nuon when resume isn't installed, resolves to nothing and says nothing, costing one path exists a session.
contexts.nuon
The project's diff over the defaults – merged by name, so naming one field on an entry changes only that field and an entry never mentioned ships exactly as the default. enabled: false is the only way to drop a shipped entry; deleting its row here just brings the default back. It ships as commented worked examples only, and is where a project retags a shipped entry, adds a context file of its own, injects a text or script body, or hangs a pre/post hook on one.
inject/scripts.nuon
The script-injection family – the one file defaults.nuon's inject-scripts pointer resolves, so a project's kind: script entries live in one findable place instead of sprawling through contexts.nuon. It ships wired with one entry, script-index, which runs context/tools/script-registry.nu light and wraps the result in <scripts>, the hot-tier pointer at the project's own .nu tools.
The Turn End Injector
The same entry table, read at the other end of a turn. It exists because six modules had each hand rolled their own Stop hook, 839 lines between them, and none of them could see the other five, so at the end of a turn they either all stayed quiet (this repo sat on 64 pending wiki files while nothing surfaced them) or several spoke at once at the exact moment finn was stopping. Arbitration is the thing only a shared layer can do.
The part draws as context/injectors/nudge beside context/injectors/engine, and that pairing is why the old injectors part was renamed: a subgroup cannot share a name with a part, and engine on its own was already taken by context/capture/engine. That is one rename migration row and not one dest moved, so an installed project re-keys on read rather than reinstalling.
Armed in this repo, 2026-09-10. nudge.nu and prime.nu are both merged into .claude/settings.json here. wiki-stale.nu, cleaner-hook.nu, and plan-close-hook.nu are gone, replaced by the wiki, handoff-cleaner, and plan-close entries in nudge/defaults.nuon. backlog-nudge.nu is the last of the original six to migrate: it ran standalone outside arbitration while M31.A was open, and once that window closed the hook was retired in favour of a backlog entry on the todos-done signal, the only entry that signal serves, since a backlog is offered when the session's work is through rather than when finn is winding down. mod-doc-nudge.mjs and telemetry's own notify hook still run standalone, unaffected: their turn end entries (mod-doc, telemetry-spend) ship disabled because they count through modules that never install into a project, an entry nothing can answer is noise in a table people read.
nudge.nu
The Stop hook – asks each candidate entry how many things its module is holding, ranks by kind then size (ledger entries first by count descending, judgement entries last), caps at max_per_turn, and emits once. There is deliberately no weight field: a wrong number is silent, an entry just quietly stops being heard. Any surviving block: true blocks the whole emit, because asking requires blocking, a non-blocking note lands as context for the next turn, and at a real end of session there is no next turn. The emit instructs the agent to put the items to finn as one AskUserQuestion call, which is where the cap of 4 comes from, that is the tool's own limit. It never opens a module's pending file and never writes one; each module keeps its own ledger in its own format and answers a count command through its own script, which is what leaves the wiki ledger's per-page pruning alone. A count that is missing, non-zero-exit, or not a bare integer reads as zero, so an entry for a module this project does not have costs one path exists. Every failure path exits 0, and the refire rows are banked to .claude/nudge/state/<session id>.nuon before the emit so a blocked-then-re-entered turn does not read as a fresh fire.
prime.nu
The PostToolUse hook – matched on Edit|Write|MultiEdit|NotebookEdit, it hands each edited file to whichever entry declared a prime, and each of those calls the owning module's own append with the file as its last argument. O(1) per edit, never speaks, never blocks, stdout and exit code both ignored so a broken prime costs its own ledger and not the edit. This is what pays for the Stop half being cheap: wiki-stale.nu used to rediscover what the session had changed on every single turn, re-walking the transcript and globbing the whole generated site to do it. backlog ships with no prime, its count is read live off BACKLOG.md and DEFERRED.md rather than accumulated as the work happens, since there is no ledger to accumulate against.
defaults.nuon
The shipped turn end entry set – wiki, plan-close, handoff-cleaner, handoff, and, as of M6.B, backlog ship on; mod-doc and telemetry-spend ship off because they count through local modules that never install into a project. An entry carries class (ledger with a count off disk, or judgement, a prose gate only the agent can evaluate), signals (a list, OR-ed, wrap-up / todos-done / always, because the clients do not all share one trigger), refire (on-change by default, comparing the session's edit count against the count it saw when it last fired, once opted into by the entries that already behaved that way), block, why, count, prime, say and do. backlog's count sums the open items in BACKLOG.md with whatever's due a showing in DEFERRED.md, and its do points at hooks/backlog-recap.nu for the brief, the same split every entry uses: the signal is a guess so a wrong one costs one line rather than a page.
nudge.nuon
The config, and the existence gate – enabled, max_per_turn (4), ask (false emits the written form for print mode and cloud sessions), and wrap_up. Both hooks test for this file first and return silently when it is absent, so a project without the part pays one path exists a turn. The wrap_up list is the point of the file: 17 patterns, the union of the two lists that were in the tree. wiki-stale.nu carried fifteen and backlog-nudge.nu eleven, and they disagreed, so the same session-ending message fired one hook and not the other depending which phrasing finn happened to use. It is data here and deliberately not a const in the script, since that duplication is the drift the whole part is about, and it is the one key with no fallback baked into nudge.nu.
nudges.nuon
The project's entry diff – merged over defaults.nuon by name through the same fold contexts.nuon uses, so a record reusing a shipped name updates that entry in place and a new name adds one. It ships empty, meaning take the shipped set as it is, and turning a shipped entry off is { name: "wiki", enabled: false } rather than a deletion. The harness repo is where the two off-by-default entries get switched back on.
Clock
clock.nu
The UserPromptSubmit hook – stamps the wall clock into every turn, and the date as well whenever the work day has rolled since the last prompt, so a session running past midnight does not keep thinking it is still yesterday. Only the session's first prompt and any day change carry the full time & date: stamp, everything else gets the bare time: line, a shape change that reads as an event where the same line every turn would read as wallpaper. A day change also fans out whatever events.nuon lists, a line to inject or a script of your own to run. It never parses the transcript to find its own last stamp: the previous one is a session-keyed marker in the temp dir, the same shape budget.nu uses.
clock.nuon
The clock's config – enabled, mode (auto/full/time), boundary (the HH:MM local time the work day rolls at, so a boundary of 05:00 stops a 3am prompt firing new-day events), weekday, offset, the label/time_label prefixes, and events (turns the day-change fan-out on or off without touching events.nuon itself). It ships on, mode: "auto", boundary: "00:00". The displayed time is always the honest wall clock, boundary only moves the day the hook compares.
Capture
capture.nu
The one appender – resolves a mode's scope (harness, project, or home) and dest off the two-tier mode list, the harness's own store/capture-modes.nuon then a project's .claude/capture-modes.nuon overriding by name, renders the entry in the mode's entry shape (bullet, block, or row), creates the file with its title header on first write, and appends, never rewrites, reorders, or deletes. add accepts fields split on | (a one-field mode takes bare text) and an explicit --dest/--title pair that lets one mode serve a family of files, which is exactly how backlog.nu reuses the backlog mode against whichever BACKLOG.md it resolved. modes lists every registered mode and where it lands, path resolves a dest without writing, read hands the raw log to the apply half, and wrapper <mode> prints a dedicated command file so /decision and /term cannot drift from the mode they wrap. A harness-scoped mode resolves the harness root through HARNESS_DIR, then the install registry, then HARNESS_BIN one dir up, and errors clearly naming what to set rather than writing to the wrong place if all three miss; a project or home mode needs none of it.
modes.nuon
This project's own mode list – installs as .claude/capture-modes.nuon, a same-named record overrides the harness global list, a new name adds to it. Ships empty, meaning use the global modes as shipped.
commands/capture.md, commands/apply.md
/capture <mode> <text> appends one entry through the mode it names; /apply <mode> drains that log with a per-entry confirm (list, clarify ambiguity once in a batch, then apply/skip/defer each), --yes skips the confirm but not the clarify. Neither command writes the log by hand, both shell capture.nu.
Backlog
backlog.nu
The router and lifecycle over three BACKLOG.md scopes – project (.claude/BACKLOG.md, the fallback every unrouted item lands in), an opt-in per-folder one (a glob in backlogs.nuon), and a per-session one (.claude/backlogs/<session id>.md, renamed to a handoff's own slug on the way out via absorb). It owns no appender itself: add resolves which file an item belongs in and hands that to capture.nu as --dest, so the folder logic and the entry logic never share a script, which is why the part hard needs engine. route prints the resolved target without writing, list shows the open items by line number (they shift on every close, so list gets re-run rather than an old number reused), top is the nudge payload, the top 3 items then the open count, close <line> moves an item to DONE.md marked done or --stale, never deleting it, and promote re-derives the [top3 since] stamp off position alone, so an item that falls out of the top 3 has its clock stripped rather than carried forward. --stale also covers an item folded into another: there is no amend or merge verb here, so absorbing one item into a second is documented as two closes and one add, close the absorbed item --stale, re-close and re-add the survivor if its own text has to change to carry the note, and let the pair sitting together at the top of DONE.md record the merge. defer <line> --why <condition> moves an undecided item into DEFERRED.md instead, carrying the condition that would turn it back into a keep, deferred lists that pile the same way list does, and revive <line> brings one back at the bottom of the live list. check runs the clocks over both files: ask_after days in the top 3 gets reported, drop_after days moves the item into DEFERRED.md rather than closing it, and a deferred item drops only once it has been shown drop_asks times, sat deferred_after days, and gone ask_deferred days since that last showing, all three together, so a month unopened costs it nothing and its final showing is still a question rather than a formality. count sums the open items and whatever's due a showing in the deferred pile, the number the turn end injector's backlog entry reads. Every verb shares the same target flags, --dir <d> exact, --near <path> walk up to the nearest owning folder, --suite the next owning folder above that, --session this session's own; nothing given is the project backlog.
backlogs.nuon
This project's own folder set and clocks – owns and except are globs relative to the project root (tools/* every tool and suite, tools/*/* a tool inside a suite), ask_after/drop_after/ask_deferred/drop_asks/deferred_after are the five clocks (14, 28, 7, 2, and 28 as shipped), and sessions names the folder under .claude/ holding one backlog per session id. The part bakes all eight defaults, so the file ships {} and runs correctly deleted. Two spellings of a multi-value field are both read, a hand-edited nuon list (owns: ["tools/*" "tools/*/*"]) or the comma-separated string harness config's form writes instead, since that form has no list type, and the two are not meant to be mixed in one file.
hooks/backlog-orphan.nu
The one hook still standalone at SessionStart – reports, only reports, any session backlog left behind by a session that ended without writing a handoff to absorb it. The live session's own file is never flagged, since the id it checks against comes off the environment rather than an mtime guess at the newest file. Folding an orphan into a handoff stays finn's call.
hooks/backlog-recap.nu
The brief the turn end entry points at – printed on demand rather than injected, so a wrong todos-done guess costs one line rather than a page. It runs backlog.nu top for the top 3 and the total, then backlog.nu check for the clocks, and tells the agent to put every item check names under "deferred and due an answer" to finn in that same reply, one line each, since check has already counted that showing whether or not it gets passed on. backlog-nudge.nu, the Stop hook this replaced, is gone as of M6.B, 2026-09-10; this file is unchanged by that migration, it is simply what the backlog turn end entry's do line calls now instead of a hook calling it directly.
commands/backlog.md
/backlog – capture, read, close, defer, revive, or run the clocks on a backlog through backlog.nu, never by editing a BACKLOG.md by hand. It works out which of the three scopes an item belongs in rather than asking, defaulting to --near on whatever file the item is about, never defers on finn's behalf (an item you think is doubtful is one to ask him about, not shelve), and closes out every finished task by offering the top 3 and the total, unless what is left is only the harness's own housekeeping, which does not count as work outstanding.
The Spine
compile-context.nu
The per-task compiler – stacks role, project rules, and global rules, folds in the routed lessons slice and any context.nuon manifest files, and prints one bundle to stdout for --append-system-prompt. The project rules and global rules sections wrap in <rules>, the lessons slice wraps in <lessons>; the role section and manifest files stay bare. Missing pieces skip silently, so an empty bundle just returns nothing.
read.nu
Surgical reads – symbol pulls the enclosing function or block (brace or indent bound), sig lists just the signatures, grep returns matches with context, and --dedup hands back a pointer for a slice already shown this session (forget clears the cache). Pure Nushell, so no missing binary can break it. The brace matcher strips strings and line comments, but char literals and block comments can still mis-bound a slice, it is a read aid, not a parser.
context-stats.nu
The hot-tier meter – prints each always-loaded file against a soft line cap and warns loud on a breach, so the paid-every-turn tier stays tiny. Advice only, it never edits anything.
The Generators
codebase-map.nu
The architecture primer – shells claude -p --dangerously-skip-permissions to walk the repo and write .claude/codebase-map.md. --path scopes it to one area, --out moves the output, --title sets the h1, --model overrides the model, --dry-run prints the assembled prompt without spending. On demand only, a full repo read costs, so it is never wired to a hook.
env-scan.nu
The machine fact sheet – probes a curated tool list (Nushell, node, npm, git, python, cmake, rustc, cargo, vcpkg, Claude, and msvc via vswhere) for exact version and resolved path, and writes a prose-free ENV.md. --out lands it elsewhere, --quiet writes without echoing the table. An absent tool skips its row, it never errors on a missing one.
script-registry.nu
The tool index, two outputs – gen scans .claude and writes SCRIPTS.md, selective on purpose: a script earns a row only by having two or more named subcommands or by opting in with a registry: <blurb> header line (registry: skip forces a multi-verb tool out), so the table carries only what a bare filename can't. light prints the second, much smaller hot-tier block to stdout instead, one line per script that opted in with its own inject: <when to reach for it> header, which is what inject/scripts.nuon's script-index entry runs at session start. A derived purpose reads past an agent that wasn't already looking; a hand-written trigger line is what actually routes, so the bar for earning a light row is much higher than the table row.
The Dispatcher
role-route.nu
The role ranker – scores the ROLE.md personas that fit a task by keyword overlap and names the best, but it suggests, it never adopts, adoption stays finn's pick via /role. A suggested role whose file is missing is still ranked, flagged exists false. The table's _router key carries the tokeniser setting rather than a second config file, hyphens: include keeps a hyphen as a word char so claude-code stays one token, exclude splits it so sprite-texture scores against both halves, and an absent key reads as include.
It has its own page, see the role router for the pool resolution order, the three separate roles directories, and the rest of the dispatcher's detail.
roles.nuon
The routing table – maps each role file stem to its keywords, project owned so it retunes to your persona library. A reserved _router key alongside the roles carries the table's own settings, the same underscore convention subprojects.nuon runs.
Manifests, Commands, and the Scout
manifest-template.md
The CONTEXT.md starter – a read-when index a fresh agent checks to find the one doc that answers a question instead of loading them all. Copy it to the project root and fill the rows; it names the codebase map as the architecture entry.
glossary-template.md
The GLOSSARY.md starter – the project's word for a thing plus what not to call it (Entity not GameObject), so an agent names things the codebase's way. Grown a row at a time by /term, append only.
commands/
The slash commands – /map, /env, /role, and /scripts drive the tools above, while /decision appends to DECISIONS.md and /term appends to GLOSSARY.md, both append-only logs generated as wrappers over capture.nu so they cannot drift from what the mode declares.
agents/researcher.md
The scout – a read-only subagent that runs on haiku, leans on read.nu for its digging, and closes every run with a four-part report: outcome, findings (each with a file:line ref), validation, and blockers. It follows the wiki first once the wiki part is installed and drops to code only for what the wiki doesn't cover, so exploring an area never fills the main window with files.
The Handoff
precompact-handoff.nu
The pre-compaction writer – a PreCompact hook that has sonnet read the session transcript and write .claude/HANDOFF-compact.md, running synchronously with a 240 second timeout so compaction genuinely waits for the brief rather than racing it. This is the narrow case the repo's own PreCompact rule carves out: the hook is discouraged everywhere else but earns its keep here because carrying a handoff across a compaction that is actually about to happen is exactly the thing nothing else can do post-hoc. A HARNESS_HOOKS_OFF guard on entry bails immediately if it is already 1, then sets it for its own claude -p call, so a harness hook further up the chain never re-fires the same chain through the child session it spawns. The transcript is flattened into one prose-plus-tool-call block, capped at a 120000 character budget (kept as a 10000 character head and a tail from the far end, with a [... middle of session trimmed for length ...] marker between them) so a long session's transcript never blows the prompt. It resolves the claude binary through which claude.exe claude claude.cmd, machine agnostic on purpose: an earlier version hardcoded an npm shim path to dodge a stale winget exe, that path stopped existing, and every run was silently falling through to the bare name it was trying to avoid. Its prompt template ships beside it as precompact-handoff-prompt.md so nothing is machine specific, sonnet is called with --no-session-persistence --exclude-dynamic-system-prompt-sections, and a git diff summary (git diff --stat plus git status --short, or working tree clean) appends under a ## repo state header before the file is written CRLF-normalised for the viewer.
inject-compact-handoff.nu
The post-compaction injector – a SessionStart hook scoped to the compact matcher, injects HANDOFF-compact.md wrapped in <handoff> with the === COMPACT HANDOFF === banner kept inside the tag (old telemetry matched the block by that opening before the wrap landed), then archives the file into archive/context/ dated so reruns never collide.
handoff.md
The /handoff command – writes .claude/HANDOFF-<topic>.md, never a bare HANDOFF.md, with frontmatter (kind, status, summary) the SessionStart lister reads and four sections: done, in flight, next, open questions. It checks for an existing handoff on the same topic first rather than opening a near duplicate, and refuses to write one when the session finished clean. HANDOFF-compact.md is reserved for the precompact hook and never a target. It is also the gate the handoff turn end entry quotes rather than restating, so there is one copy of the leftover-work rule and not two. Its last step absorbs the session backlog: backlog.nu absorb --topic <the same slug> renames .claude/backlogs/<session id>.md to that slug and prints one pointer line, which goes near the bottom of the handoff and nothing else, never a ## backlog section and never the items restated, since a list living in two files goes stale in one of them. The step was wired on 2026-09-10: absorb had been built and fixture-gated since 2026-09-04 and nothing had ever called it, this command had no mention of the backlog at all. ~/.claude/docs/authoring.md carries the same step for a TASK-<name>.md, which absorbs on identical terms because absorb only ever cares about the slug.
The Cleaner
cleaner.nu
The spent-doc detector – reads a handoff or task's own frontmatter status (done or consumed mean it's finished) and flags any still sitting in .claude/, plus any bare HANDOFF.md or TASK.md, which the naming rule forbids. It only ever reports; archiving is a deliberate act it never performs itself. --nuon returns the rows as data, --quiet exits 1 if it found anything, and --count prints a bare integer and nothing else, which is what the handoff-cleaner turn end entry reads it on. The part shipped a Stop gate of its own until the turn end injector landed; that hook is gone from the manifest and the detector is now one arbitrated client with signals: ["always"] and refire: "once", the exact behaviour the hook had, decided against the other clients instead of alone.
The Budget Gate
budget.nu
The PreToolUse meter – reads the session's token usage off the transcript and the subscription's own rate limits off a cache, and acts across four independently nullable meters rather than a separate mode flag: occupancy_soft/occupancy_limit off the last assistant turn's usage (input + cache_read + cache_creation, and it resets on a compaction), an optional cumulative_soft/cumulative_limit in billed input-token equivalents (hidden from harness config since 2026-08-11 but still read by the gate if hand-added, along with count_subagents to fold in what this session's subagents burned), and five_hour_soft/five_hour_limit plus weekly_soft/weekly_limit, the rolling 5 hour and weekly windows the subscription itself enforces, read as percentages rather than tokens because percent is the only unit the endpoint reports. rate-windows reads those two through rate-pct and rate-reset, and only calls out to rate-limits.nu when its cache at ~/.claude/harness-rate-limits.nuon is older than 5 minutes, so a tool call ordinarily costs a small file read and the endpoint itself is reached about once every five minutes across every session on the box. rate-in turns a reset timestamp into the shortest form that still says something, in 4d 22h, so a rate message never leaves the agent guessing whether the wait is hours or days. Past soft it nudges by default once per turn (nudge_repeat) and lets the call through; past hard it generates a handoff once per session by reusing precompact-handoff-prompt.md, blocks every tool but a write to a HANDOFF-*.md in handoff_dir, and tells the agent to echo the configured banner. A trip when writer (the handoff part) isn't installed reports that plainly rather than misreporting a generation failure. The trip marker is where the two kinds of meter genuinely differ: a token meter pins the marker with nothing in it, session-long, because neither occupancy nor spend comes back on a clock, while a trip caused only by the rate meters writes the window's own reset time into the marker, so the post-trip fast path stays a clock compare and the session comes back to life once that window rolls over. When both rate windows trip together the marker takes the earlier of the two resets (math min), the first moment the block could stop being true, and an older marker holding the literal tripped parses to null and reads as pinned, exactly the behaviour it already had. Any detection error fails open to exit 0, a broken meter must never brick a session.
budget.nuon
The gate's config – enabled occupancy_soft occupancy_limit five_hour_soft five_hour_limit weekly_soft weekly_limit nudge_repeat handoff_dir banner. Ships enabled: false with finn's own numbers already in place, occupancy_soft: 350000 and occupancy_limit: 600000, sized for a roughly 1M token window and dead on a 200k one where occupancy can never reach either; the four rate keys ship null, off until you set one. harness config types the two occupancy numbers in thousands while the file keeps the raw figure, and reads the four rate keys as bare percentages, 0 to 100, since that's the only unit the endpoint itself reports. handoff_dir is clamped, an absolute or ..-escaping path is refused back to .claude with a line on stderr, because the gate exempts whatever it resolves to and a folder outside the project would punch a hole in the block.
Lookup
lookup-first skill
The reach-for-a-lookup-instead-of-reading-it-whole trigger – routes to three scripts declared as its hard dependencies, read-front.nu (a folder of task/handoff/plan/note files, which one is this, off their frontmatter), read-section.nu (a file's headers, then one section out of it, a --grep answering is-this-logged-at-all without opening the file), and read-many.nu (a known set of source files in one call instead of one Read each). All three land at .claude/scripts/. Tolerant by construction, a missing or broken block returns a row rather than an error, and a script that's absent from a project just means say so and read the file normally rather than writing a replacement.
Hot and Cold
The whole module leans on one split, and keeping it straight is the point:
| tier | what lives there | what it costs |
|---|---|---|
| hot | CLAUDE.md, the injected role, the rules files | paid on every single turn, so it stays tiny, pointers not prose |
| cold | lessons, docs, cheatsheets, specs, the generated primers | nothing until something pulls it |
The bridge between the two is a pull rule, a one line read X before doing Y in CLAUDE.md that names a cold doc so it gets read exactly when it matters. The files part ships a set of these to paste into a project's CLAUDE.md: check CONTEXT.md before hunting for where something lives, DECISIONS.md before reopening a settled choice, ENV.md before leaning on a tool version, GLOSSARY.md before naming a new type, SCRIPTS.md before writing a new .nu helper. When a fact wants to live in the hot tier, ask whether a one line pull rule would do instead, it almost always would.
The XML Tag Convention
tag is the one field that spans both the injector and the compiler, and it is deliberately built in rather than a hook. Everything that injects a file's contents carries one, <context>, <style>, <design>, <role> from inject-project.nu, <scripts> from the script-index entry, <rules> and <lessons> from compile-context.nu, <handoff> from inject-compact-handoff.nu. Everything that only lists or references a file stays bare, the TASK*.md and HANDOFF*.md listings, and the role suggestion and manifest sections in a compiled bundle. In inject-project.nu, where a hook pair was the obvious alternative, the reasoning against it is concrete: pre and post fire per matched file and each half spawns a subprocess, so wrapping a multi-match entry that way would emit a tag pair per row and pay two subprocesses per match. A tag wraps the whole entry once, at the cost of nothing, giving an agent a hard boundary to follow and anything reading the transcript back a fixed signature to grep for, rather than a preamble it has to guess the edges of.
Connects to
- Arbitrates for wiki, plan-system, frameworks (mod-doc), telemetry, its own
cleaner, and, as of M6.B, its ownbacklog– each ships acountscript thenudgeStop hook asks for a number, and aprimescriptprime.nucalls on every edit where one is declared, so no module's ledger format leaks into the injector. - Routes through memory –
compile-context.nuasks the lessons store which domain a task belongs to and folds that slice into the bundle, androle-route.numirrors the store's own keyword router. - Depends on the generic script parts
read-front,read-section,read-many,strip-frontmatter, andnu-note– declared as hardneedsbyinjection-engineandlookuprather than copied in, so one shared copy of each lands at.claude/scripts/however many parts declare it. - Hard-
needsinside itself, three times over –nudgeneedsinjection-engineforloader.nu,modesandbacklogneedengineforcapture.nu, andfilesneedsenginebecause/decisionand/termare generated wrappers over it. - The
budgetgate cross-reads writer (handoff) when it trips – it reuseshandoff/precompact-handoff-prompt.mdto generate its own brief, and treats a missingwriterpart as an ordinary missing-part case rather than a failure. It also declares the genericrate-limitsscript as a hard dependency, so an install brings the cache reader its two rate meters need, and aneeds-partmigration row (2026-09-11) reaches any project that already installed the gate before those meters existed. - Wires forward to resume –
defaults.nuon'sinject-resumepointer resolvesresume.nuon, theresumemodule's own session-start entry, soresumereaches an install through the samekind: "nuon"seaminject-scriptsuses rather than by registering a hook of its own. See resume for what that entry actually injects. - Has its own page for the role dispatcher – role router covers the pool resolution order and the three roles directories in full.
- Placed by the installer – eleven parts under the shared
contextgroup, withinjection-engine(drawn asengine) andnudgeunderinjectors,engine/modes/backlogundercapture, andwriter/cleanerunderhandoff, so a project can take the session start injector without the turn end one, or the capture engine without the backlog router. - The condensed, end-user version of this page is the module's own
USAGE.md, atharness/modules/context/USAGE.md– that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module.injectors/USAGE.md,nudge/USAGE.md,backlog/USAGE.md, andcapture/USAGE.mdcover those four parts in the same thin form, andbudget/USAGE.mdcovers the budget gate's four meters in that same thin depth.