Appearance
Repo Scripts
Most modules carry their own scripts – memory has lessons.nu, context has compile-context.nu, hooks has its gates. harness/scripts/ is the other drawer: tools that answer a question no single module owns, and that boundary is deliberately the whole point of the folder existing. A module's own scripts stay with that module; only the module-agnostic ones land here. The folder now holds eighteen scripts split three ways – some are installable parts a project picks for itself, some are local modules the harness runs on itself and never ships, and a couple only ever run against this repo, with nothing left uncategorized. The path itself is not settled either, finn may move the folder to harness/modules/scripts/ later, so treat harness/scripts/ as where these live today, not a permanent address.
In Practice
Price a paste before it goes anywhere. tokens.nu answers whether a doc or a folder is worth putting in front of a model, before you send it:
nu harness/scripts/tokens.nu notes.mdestimate: 690 tokens (2,428 chars, 3.52 per token)
window: 0.35% of 200,000
weighted: 690 input-equivalent (role input, x1.0)
session: <0.01% of a 5h block
week: <0.01% of a weekIt splits the text into word / number / punctuation / whitespace pieces and prices each class the way a bpe tends to merge them, since claude's real vocab is not public and the count_tokens endpoint wants an api key finn does not use. --role output or --role cache-write reweights the same count for a different kind of spend, and nu tokens.nu docs/ .nu -r adds a whole folder up with a per file breakdown, biggest first.
Read the window before deciding whether to push on. context-window.nu answers a different question cheaply: not what a paste would cost, but how full the running session already is.
nu harness/scripts/context-window.nucontext: 183,753 tokensIt sums input_tokens + cache_creation_input_tokens + cache_read_input_tokens off the newest non-sidechain assistant turn in the session's own transcript, so the reading is current rather than a turn behind. It reports no percentage on purpose, nothing on disk says whether a given session is a 200k or a 1m context, so any denominator would be a guess.
Learn what six task files are about without opening any of them. read-front.nu reads the yaml frontmatter off a set of markdown files and hands it back as a table:
nu read-front.nu .claude --kind handoffMeasured 2026-08-07 against 135 files across harness/plan/, .claude/, and harness/notes/, the whole scan ran in 63ms in process. It is deliberately fault tolerant, a file with no block, broken yaml, or an unclosed fence still comes back as a row rather than an error, because these files are hand written prose nobody validates.
Pull a section by name, or list what's there without opening the file. read-section.nu answers "which part of it" the way read-front.nu answers "which file", and a miss is cheap and useful rather than a blind error:
nu read-section.nu BUGS.md "does not exist anywhere"no section matching "does not exist anywhere" in BUGS.md. it has these,
1 harness/BUGS.md
2 open
3 outside-project.nu silently ignores a relative-path lease
...splice-section.nu is the twin, it puts a section back the same way, anchored on the same header parse imported straight out of read-section.nu. It was write-section.nu until 2026-09-04, renamed because splice is the verb that means remove and insert both, the sense Array.splice gives it, where write only ever held on the read-vs-write axis. It bypasses Edit to do it, so it stamps its own archive copy before writing and refuses rather than writing blind when it can't:
nu splice-section.nu append NOTES.md "open" "- a line"REFUSED, no archiver in this project, nothing was backed up
nothing was written. pass --write-anyway to write with no backup, or --no-archive to skip it on purposeDrop text at an exact line, but only if the file still says what you think it says. insert-lines.nu is the position half where splice-section.nu is the content half, anchoring on --top, --bottom, --line <n>, or --after-line <n> instead of a header, so it works on any text file:
nu insert-lines.nu DOC.md "INSERTED" --line 8 --expect "not there"REFUSED, line 8 does not hold "not there", it holds,
intro prose
nothing was written. the file has moved since you read it, find the spot again--expect turns a line-number guess into a checked one for the cost of a few words.
Sweep every reference to a file that just moved. swap-refs.nu finds every shape a filepath can wear across the whole project – forward slash, backslash, absolute, a leading ./ – and swaps them all in one pass, which is the reconcile step nothing else does once git has moved a file:
nu swap-refs.nu harness/old/ harness/fresh/ --drydirs.md, 1 line
1:14 a folder ref harness/fresh/thing.nu and harness/fresh/ and harness/freshThe trailing slash on both paths puts it in directory mode, so every file that used to sit under harness/old/ gets caught in the same pass, whatever shape the reference took inside it. --dry shows the same list and writes nothing; drop it and the swap lands for real, one archive stamp per touched file first.
Check what a /wiki run is about to fan a writer over, before it burns the usage doing it. wiki-pending.nu fronts harness wiki's changelog view as a real nushell table:
wiki-pending --list | where at > (date now) - 1hrAn example outcome. A project with nothing banked gives an empty table, not an error, so it is safe to pipe into without a guard.
Installable Scripts
Thirteen of the eighteen are rostered in modules/scripts.json under the scripts group (I19), so a project picks one on its own as script:<name> rather than it being smuggled in as a copy leaf on whichever module happened to need it. A module that calls one declares it as a hard dependency, "scripts": ["read-front"] on the part, so one copy lands however many modules declare it and it is offered back only once the last thing needing it goes. A script can declare the same edge onto another script: splice-section.nu declares "scripts": ["read-section"], and insert-lines.nu, n-to-and.nu, and swap-refs.nu all declare "scripts": ["splice-section", "read-section"], since each imports its write path or its header parse rather than copying it, and a missing import fails at parse time. The chain runs insert-lines -> splice-section -> read-section (the same chain for n-to-and and swap-refs), so picking script:insert-lines alone on the install page pulls both of the others in without a separate pick. Context's backlog part is the first module to actually declare one, "scripts": ["insert-lines"], for the same archive-stamped write a closed item wants before it lands at the top of DONE.md. n-to-and.nu and swap-refs.nu still ship rostered and reachable with nothing in modules/ declaring them as of this writing. The dest is never the manifest's to pick: anything directly under scripts/ lands at .claude/scripts/<basename> regardless of what asked for it, derived off the source path in installer/src/models/shared.ts (canonicalDest / scriptDest) rather than a table, and loaded into real parts by installer/src/manifest.ts's loadScripts, so a project holds exactly one copy of each script.
read-front.nu
Which file. Reads the yaml frontmatter off a folder of markdown files and returns one row per file, kind (task / handoff / plan / note, off the filename so a file that forgot its block still classifies), summary, status, updated, tags, and an extra bag for whatever field nobody expected. --tags "a,b" ranks by hit count, --kind and --status filter, --deep walks subdirs, --bare prints paths only for piping. It is read only and reads live off disk every call, never an index.
read-section.nu
Which part of it. Pulls one named header out of a markdown file, or lists every header with its line and size so an agent can decide whether pulling is even worth it against reading the whole file. A miss lists what headers do exist rather than erroring blind, --grep searches title and body for the "is this logged at all" case, and --flat drops the nested children under a match. It tracks fenced code blocks so a # inside a shell snippet is never read as a header, and frontmatter is skipped the same way read-front.nu skips it. It exports main, so a caller working over several files can use it and stay in process. It is reads only; splice-section.nu is the write side and imports this file's parse rather than carrying a second copy of it.
read-many.nu
Several files, one call. Reads a known set of source files in a single call instead of one Read per file, tuned for a survey pass rather than a walk, it takes exactly the paths handed to it and never globs on its own. Measured against real usage records, a Read costs about 90 output tokens of envelope per tool_use block, so ten files as ten Read calls run about 1,120 tokens against roughly 243 through here, a 4.6x saving that grows with the file count. Anything over the 8,000 token per file cap is refused rather than clipped by default (--clip opts into truncation), and --out writes a markdown dump read-section.nu can later slice by filename.
splice-section.nu
Changes one named section in place, without reading the rest of the file. Four ops against a header anchor, remove, replace, append, and insert, anchored with --under, --after, --before, --table-top, or --table-bottom. Renamed from write-section.nu on 2026-09-04 (a row in installer/src/migrations.ts carries the migration) because the old name only held on the read-vs-write axis and read as putting something in; splice is the verb that means remove and insert both, the same sense Array.splice gives it, and it now sits in the settled-verb list frameworks/DICTIONARY.md keeps for naming a script. It imports its parse straight out of read-section.nu through use rather than by copy, so the two can never disagree about where a section ends, and CRLF endings are read off the file and rejoined unchanged rather than being flattened by nushell's own line splitting. Because it writes directly it bypasses the Edit tool and, with it, the PreToolUse archiver stamp, so it stamps its own dated copy into archive/ before writing and refuses to write when it can't, --no-archive and --write-anyway are the two deliberate escapes. It is idempotent by default, a payload already sitting in the file as a contiguous run of lines is refused with the line it is already at, --force overrides for a genuinely repeated row.
insert-lines.nu
The position half, where splice-section.nu is the content half. Anchors on --top, --bottom, --line <n>, or --after-line <n> rather than a header, so it works on any text file, not just markdown with headers, a .cpp, a .json, or a log all qualify. --top lands under any yaml frontmatter and its blank line rather than above it, so it can never break a file's own header block. --expect <s> turns a line-number anchor into a checked one, refusing the write unless the anchored line still holds the text the caller expects, since a line number is only ever valid against the file as the caller last saw it. It shares splice-section.nu's archive stamp by import, one backup path rather than a second copy of it. Context's backlog part is the first module to depend on it, "scripts": ["insert-lines"], for the archive-stamped write a closed item wants before it lands at the top of DONE.md, since backlog.nu rewrites that file's whole body off a parse rather than splicing a named section.
n-to-and.nu
Turns the bare n abbreviation back into and, the pass that brings an old file over now that finn-style dropped n from the dialect (2026-09-10). It was written first for the narrower job, a doc leaving the house for somewhere formal, and that job still holds, there is just far more of it now. A sweep over a whole file rather than a targeted edit, it matches an n with whitespace or a line end on both sides, skips fenced code blocks and inline code spans by default (--in-code turns both skips off), and prints every line it changes rather than just a count, because a shape like keep_last n reads as a number placeholder rather than a conjunction and nothing can tell the two apart by shape alone. It shares splice-section.nu's archive stamp the same way insert-lines.nu does.
swap-refs.nu
Finds every reference to a filepath across the whole project and swaps it for the new one, the reconcile pass for a file that moved or got renamed. Git knows a file moved; nothing else does, so this is the sweep that finds the markdown link, the use import, the hook command in a settings file, and the path in a comment that still point at the old spot. One path wears several literal forms – harness/scripts/old.nu, its backslash and absolute equivalents, a leading ./ – and all of them get swept and put back in the same shape they were found in, gated on both sides by a path boundary so old.nu never matches inside old.nuon. A trailing separator (or a new path that already exists on disk as a directory) switches it to directory mode, sweeping every file under a moved folder in one pass. --text, --word, and --regex drop the path handling for a plain literal, a symbol rename, or a captured pattern, and a quoted list of [old new] pairs runs a whole batch in one walk of the tree rather than one per pair, without letting an a -> b and a b -> c pair chain into a -> c. It writes by default, imports splice-section.nu's archive stamp the same way insert-lines.nu and n-to-and.nu do, and reports what matched separately from what actually got written so a fully refused run can never read as a successful one. It is the engine behind the reconcile local module's moved-path and renamed-file passes, which batch it per section with the harness's own records (plan/, retired/, wiki/, TESTS.md, BUGS-fixed.md) skipped, a set the tool's own default skip list does not cover.
strip-frontmatter.nu
Takes a frontmatter block off. The write-side twin of read-front.nu: only a --- on the very first line opens a block, and the file comes back byte for byte untouched otherwise. It installs with the hooks part under injectors > strip, and the injector that calls it resolves the script at call time off its own directory rather than via use, so a missing copy just means the header rides along into context instead of taking the whole injector down.
skill-front.nu
Edits a skill's own frontmatter, not just reads it. Toggles disable-model-invocation, narrows allowed-tools, or fixes a description that routes badly, as a picker (arrows, / to search) or as flat subcommands, get / set / unset / toggle / list. It edits lines rather than round-tripping through a parsed yaml tree, since that would reflow the whole block and eat the comments, and a SKILL.md is prose a person reads. Checks on a value (an unknown field, a bad model name, a non kebab-case skill name) are warnings that still write, never refusals, catching a typo that would otherwise sit in the file doing nothing.
nu-note.nu
Tells the agent which nushell to run. A SessionStart hook (an observer) that prints nothing on a box where nu resolves off PATH, and one line naming the bundled interpreter path when it does not, off $env.HARNESS_NU stamped in by the harness settings merge. It is a stray script by design, roughly a dozen modules ship .nu scripts and every one of their docs says nu <script>, so the note serves the harness as a whole rather than any one of them, and it is deliberately not a declared dependency of anything, a module takes it or it does not.
now.nu
Tells an agent what the time is, and what work day that time belongs to. A session's injected date goes stale the moment the session runs past midnight, so this answers --iso, --epoch, --day, --since <iso>, or --json on demand. When the clock part is installed it reads boundary, weekday, and offset out of .claude/context/clock/clock.nuon, so the answer is in the same terms as the injected stamp and the two can never disagree; with no clock installed it still works, falling back to a midnight boundary and the clock's own default stamp shape rather than erroring, because this is a generic script and not the clock module's private tool.
tokens.nu
Prices text before it gets sent. Estimates how many tokens a paste, a file, or a whole folder is worth, and what that spends against the 200k context window and against a 5 hour / weekly usage budget, all measured off finn's own transcripts rather than a published limit (Max plans are stated in hours per week, never tokens). calibrate --days 30 set the baked session and week budgets from 41,124 turns across 213 sessions on 2026-08-10, and tool <name> fits the fixed-plus-per-char cost of a single tool call, Bash, Read, or Edit, off exact output_tokens in a transcript rather than an estimate. --role reweights a count into input-equivalents using the same weighting the harness already uses for subagent spend, so a figure from here and a figure from harness-agents.jsonl are comparable. to pipe into it, import it rather than running it, a script run as nu tokens.nu never sees the pipeline.
rate-limits.nu
How much of the plan is left, the account-level twin of context-window.nu. Where that one reads how full the running session's context is, this one reads how full the Claude subscription's rate limits are, the rolling 5 hour window and the weekly one, as percentages: 5h: 82% (resets in 2h 25m), weekly: 22% (resets in 5d 20h). The numbers come off GET https://api.anthropic.com/api/oauth/usage, the same undocumented endpoint the /usage command reads, authed with the OAuth token Claude Code keeps in ~/.claude/.credentials.json – community-found rather than published, so it could move without warning. --full returns both windows as a record instead of the one line, --json hands back the raw response, and --over <pct> answers whether either window has passed a percent, prints which one is fuller, and exits 1 when it has, so it gates a script as well as it reads. The endpoint rate limits itself – a burst earns a 429 that clears in about ninety seconds, but a call made during the ban restarts it – so every answer is cached for 5 minutes in ~/.claude/harness-rate-limits.nuon (--fresh skips it), and a failed call falls back to whatever is cached however old, saying the age rather than dying.
Local Modules
Three more are local modules, declared in installer/src/local.ts and listed in harness/LOCAL.md, the third class beside a part and a banked module. harness local is the only view that can see them, and it only works inside the harness repo. All three read as in place: there is nothing to copy, they are called by their harness path, so a project copy would only drift out of true. Whether that changes, giving each a real destination so an installed project is self-contained, is an open decision weighed against the risk of two copies falling out of sync, not settled either way. See Install Scopes for what a local module's install boundary actually means.
context-window.nu
The one-number read. Finds the running session's transcript off $env.CLAUDE_CODE_SESSION_ID (or an explicit --session), never by newest mtime since concurrent sessions in one project dir would pick the wrong file, and sums the newest assistant turn's input, cache-write, and cache-read tokens. --full returns the breakdown as a record, tokens, fresh, cache_written, cache_read, model, as_of, session, instead of the one line.
context-view.mjs / context-view.cmd
What actually filled it. A zero-dependency node tui, deliberately not nushell since it cannot redraw a cursor list cleanly on Windows Terminal, that reads a session's injection log and lists every block that entered context without you or the model writing it: hook stdout, nested CLAUDE.md pulls, the skill listing, the agent listing, mcp instruction blocks, deferred tool names. A fat block like the skill listing opens as an accordion so you can price one skill instead of the whole lump, and d drops a row to model what removing it would save without touching anything on disk. A [dupe] tag on a hook block means the exact same hook output showed up twice, meaning the same script is wired into both the global and the project settings files, since claude code merges hook config rather than overriding it. --list and --export are the headless paths, they skip the tui entirely since it refuses to draw into a pipe. context-view.cmd is the double-click launcher, it resolves the project two directories up from its own location rather than off the shell's working directory, so a double click always opens the right project's sessions, and dragging a different project's folder onto it opens that project instead.
wiki-pending.nu
The nushell front onto harness wiki. A router, not an implementation, the parse and the accordion view live in the installer, this file only calls it and types up what comes back. wiki-pending (registered globally via use .../wiki-pending.nu in config.nu) opens the tui for the cwd project, --list returns the changelog .claude/wiki/pending.nuon banks (one row per source file written since the site was last generated) as a real nushell table with at and modified as datetimes and size as a filesize, so it pipes and sorts rather than needing to be scraped as text. It fronted a standalone node viewer plus a double-click .cmd until 2026-08-15, when the viewer moved into the installer and picked up the shared accordion widget the other list views use; the standalone now sits in harness/retired/wiki-pending/.
Harness-Only Dev Tools
Two scripts belong to neither roster, they only ever run against this repo, so they are neither installable parts nor declared local modules.
manifest-gate.nu
Catches a broken module manifest the moment it is saved. A PostToolUse hook on Edit|Write|MultiEdit, live since 2026-08-13, that fires only on a module.json, a config.json, or the modules/modules.json roster, every other write costs one basename compare. It shells harness validate --manifests rather than holding a second hand-written copy of the checks, and calls the built cli through node directly since the npm .cmd shim errors when nushell spawns it. Exit 2 blocks the write and prints the fail lines on stderr so claude code feeds them straight back to the model.
framework-skill.nu
Turns a framework doc into its module skill. For each framework doc under frameworks/ it writes modules/frameworks/<slug>/SKILL.md, a router pointing into the doc, never a copy of it. A skill that already exists is skipped, it is an add tool, a shipped framework skill is hand maintained from the moment it lands, the one exception is GENERAL which is rewritten on every run because it names no project and nothing local to lose. --check exits non-zero when a framework has no skill at all, for a hook or a ci step, and --parts prints the record to paste into modules/frameworks/module.json by hand rather than editing the shared manifest itself, which would be a merge conflict waiting to happen in a repo running concurrent sessions.
One Doc, Loaded Once
Each script gets exactly one doc at scripts/docs/<script name>.md, and the convention is to load only the doc for the script you actually need, never the whole folder. An index you have to read in full to find one line is a context tax, and harness/CLAUDE.md's rule for the folder says so directly.
The folder also keeps its own open questions where they can be found rather than acted on by surprise: docs/todo.md weighs whether each doc should split into a short usage half and a longer detail half. Its own assessment argues against splitting yet, since nu context-window.nu --help already prints the usage for free off the def main signature, and the half actually worth keeping, the constraints (don't divide by 200k, don't find the transcript by mtime), would land in the file most agents skip. Nothing in it is settled, it says as much, and it is not acted on without finn.
Why Script It At All
The folder exists because of a harder rule than "these are handy": frameworks/GENERAL.md says anything a module can settle deterministically should be settled by a script rather than by the model reasoning it out in context, because a script's cost is its output, fixed and known, where the model's is reasoning plus the tool result anyway plus a real chance of being wrong, and that gap widens as the context fills. Counting tokens off a jsonl transcript, or parsing a folder of yaml frontmatter, is exactly that kind of work, so it is code's job.
The bar is still net savings over a realistic number of uses, not the saving on a single use, since advertising a script costs tokens in a context file every session it is mentioned whether that session ever calls it or not, and a tool call has a floor of its own: the decision to call it, the call, and the result.
Connects to
- Depended on by Context –
inject-project.nushellsread-front.nuto render the TASK and HANDOFF summary rows,read-many.nu's per-file token cap is priced bytokens.nu's own estimator, thebacklogpart depends oninsert-lines.nudirectly for the archive-stamped write that lands a closed item at the top ofDONE.md, and thebudgetpart depends onrate-limits.nudirectly, shelling it to refresh its cache and reading that cache to drive two rate-limit meters alongside its existing occupancy and cumulative ones. - Shares its occupancy math with Hooks –
modules/context/budget/budget.nusums the same input, cache-write, and cache-read tokens as a PreToolUse gate;context-window.nuis the version that works without a hook handing it the transcript path, andrate-limits.nuis its account-level twin, how much of the plan is left rather than how full the session is.strip-frontmatter.nuandnu-note.nualso ship as leaves of the hooks injectors part. - Makes an agent reach for
read-front.nu,read-section.nu, andread-many.nuin the first place – the lookup-first skill, which also notes its own tested doubt about whetherEditreally refuses an unread file on the current claude code build, a claimsplice-section.nu,insert-lines.nu,n-to-and.nu, andswap-refs.nustill lean on to explain why they exist. - Browsed and installed through the Installer – the
scriptsgroup in the install page for the thirteen rostered parts,harness localfor the three local modules with its own store separate from the shared registry.write-section->splice-sectionis arenamerow in the installer's own migration table, so an already-installed project re-keys on read rather than needing a reinstall. - Fronts the same changelog the Wiki module's Stop hook banks –
wiki-pending.nureads.claude/wiki/pending.nuonbefore a/wikirun fans a writer over it. - Runs the reconcile local module's own sweeps –
swap-refs.nuis the engine behind its moved-path and renamed-file passes, called directly by harness path rather than as an installed dependency, since reconcile only ever runs inside this repo. - Polices the budget the harness's own
frameworks/CONTEXTS.mdsets for the instruction window, the reasoncontext-window.nuandtokens.nuboth exist.