Appearance
Installer
The delivery layer. Every other module in the kit is just files sitting in the harness repo until this puts them somewhere they run – one TypeScript + Ink CLI, harness, that installs chosen parts into a project's .claude, or globally into ~/.claude, browses every project they landed in, manages them per project, and audits whether they are current and wired. It replaced the split harness-install / harness-installs bins (2026-07-10), and before them a Nushell picker that could not redraw cleanly on Windows Terminal – Ink owns the redraw now, so nothing stacks. Since I18 (2026-08-13) a part is no longer one literal record in src/parts.ts – a module declares its own install shape in a module.json beside its files, modules/modules.json rosters which modules exist and in what order, and src/manifest.ts reads the two into the shape everything else works with. A single content digest (hashPart) is still the one source of truth for staleness, so what the picker offers, what the registry records, and what a health pass checks can never drift apart. A project can also split itself into sub-projects, .claude/subprojects.nuon, so a monorepo installs a different slice of parts into each part of itself without losing the picture of what belongs to the project as a whole.
In Practice
The install path is a pipeline from the harness source to a target's registry row, and the target is the first thing decided – a project, or ~/.claude when the run is global:
Install parts into a project, or update what's already there. From inside the project:
harness installEnter ticks the row under the cursor, tab or ctrl+enter confirms, esc cancels with nothing installed. Run it in a project that already has parts and the picker opens as a reconcile instead: every installed part starts ticked, green if current or yellow if an update is available, and del marks an installed row for removal (it turns red [-], enter puts it back). Confirm and one pass lands the adds, the refreshes, and the removals together – project-owned paths survive all three. Every decided path still asks to proceed unless --yes, and a piped run with no tty to confirm prints ! no tty to confirm, pass --yes and exits non-zero rather than guessing. A successful run recaps as done, <n> items into <target>\.claude.
Give one part of a monorepo its own slice. A project carrying .claude/subprojects.nuon splits harness install into a chooser first – pick an existing entry, or + new sub-project to name one:
harness install
harness install --subproject engine --parts cpp,natvis-writer --yesThe picker that follows draws that one slice's world only, its own ticked parts, not everything the project carries. Confirming with nothing ticked is a real answer here, not a bail – the entry is written empty so the slice rides the project-global set and the always-on _base tier, keeping its own name, paths glob, and hooks. harness subprojects browses every entry without touching the picker, arrow keys read a row's sheet and enter drops straight into a scoped install for it.
Save a selection once, reuse it on the next project. Tick what you want in the picker and press s to save it as a profile, or build one headless:
harness profile save cpp --parts cpp,natvis-writer,nushell --desc "the cpp lot"harness profile then lists it – enter installs it straight into whatever project you're stood in, e reopens it in the picker pre-ticked so you can add or drop a couple first. A profile records the exact dests it was saved with, so a two-file subset of an accordion part round-trips as that same subset on every install.
Go global for a part that only makes sense in ~/.claude. Some modules are core-global – they belong in one shared home, not scattered across projects:
harness globals --install limiterharness globals lists every core-global module with its state and an update-all row; harness install --global --parts <part> --yes installs an ordinary part globally the same way. A globally-installed part then reads as one locked, blue row everywhere else in the manager, never a tick, never a del.
Catch what the dashboard is already trying to tell you. Bare harness carries a one-line banner under the menu whenever something wants attention:
! skill-smith shadows the global copy . n to reviewPressing n (or running harness notices directly) opens the notice, spells out why, and offers an action per letter – here, x removes the stale local copy since the global one is already installed.
An example outcome. You install context into a fresh project, and context --> memory is a soft wants edge – harness deps context shows it as suggested, not pulled automatically. Install context alone and later add memory, and harness doctor reports both current; leave memory out and the lessons injector installs and runs fine, it just finds nothing to inject.
The Subcommands
| Command | What it does |
|---|---|
harness install | Pick parts in the Ink picker and copy them into a project, or reconcile an existing install (add, update, and remove in one confirm). |
harness profile | Browse named part-selections; install one straight into the current project or reopen it in the picker to adjust first. |
harness roles | Browse and adopt personas: compose a base role with subskills, pick one already composed, or manage this project's own roles and the router keywords that rank them. |
harness installs | Drill into one project's installed parts and update or remove them one at a time; remove asks first and names what survives. |
harness projects | Browse every project the harness has landed parts in, and refresh any row in place. |
harness modules | The catalogue – every module the manager knows about across every class, expandable into a full sheet (source, files, deps, presence, activity). |
harness subprojects | Browse a project's .claude/subprojects.nuon, what each slice claims, which parts two slices share, and its hooks / paths / phrases; enter drops into a scoped install for the row under the cursor. |
harness extern | Browse the module bank: download or update-check an entry, and see whether it's installed in this project. |
harness local | The harness's own dev tools (vendor, modify, ...), installable only into the harness repo itself. |
harness globals | Install and manage the global-only modules that live in ~/.claude rather than any one project. |
harness deps | Read-only view of the module dependency graph, and what installing a set of parts would pull in. |
harness scripts | Scan a project's .claude for its .nu tools and show each one's purpose, subcommands, and usage; --gen writes SCRIPTS.md. |
harness hooks | Cross-reference shipped hook fragments against live settings, and wire the unwired ones in place (--merge). |
harness doctor | One health pass over a project: staleness, wiring, the nushell runtime, SCRIPTS.md, pending migrations, and retired permission rules; --fix resolves what it can. |
harness diff | Preview what an update would change per file for a project's installed parts, before running it. |
harness clean | Sweep a project's .claude for files no installed part claims – retired residue, empty dirs, and genuinely unclaimed files – and remove or keep each; a two-tier ignore list spares what the scan can't judge. |
harness migrate | Apply the def changes an already-installed project is behind on: a part renamed or split, gained a hard requirement, or had a dest move or drop since it was installed. |
harness stats | A roll-up over the install registry: presence, footprint, and version drift, or --history over the ledger. |
harness archive | Walk a project's archive: the default view is the prune report (piling-up sources, orphans, and retired ones); --why <path> asks why one file would or wouldn't be stamped; --retire / --unretire move a file into and out of the retired corner; and --clean sweeps old stamps into the bin. |
harness config | Open the settings form a part ships into the project – whatever fields its config record declares; a value left on default is never written. |
harness settings | Toggle what each view does when it finishes (stay on it, or return to the menu), how an empty project is handled, and dashboard-wide toggles like sticky cursor. |
harness notices | The heads up the dashboard banner points at: a retired part, a project copy shadowing a core-global, a pending migration, or updates available. |
harness runtime | Report which nushell interpreter this box resolves – PATH or the bundled copy – and smoke-test it. |
harness validate | Lint the loaded module manifests against the source and the dependency graph; harness repo maintenance, not a project check. |
harness uninstall | Take this project apart at four tiers – its parts, what they created at runtime, .claude/ itself, then the global stores that name it; --harness instead clears the harness's own traces outside its folder (the global state files and the npm-link shim), --all widening either scope to its maximum. Dry runs by default, prints the whole plan before it asks anything. |
Bare harness in a terminal opens a dashboard of the project- and manager-facing views; notices, runtime, validate, and uninstall are CLI-only and never appear as a menu row – the first three answer questions rather than doing anything, and uninstall is deliberately a step removed from the everyday flow, a keypress away from the home screen being the wrong distance for something that can take an archive/.
The Part Model
A part is data, but it is no longer one literal record in a PARTS array. Since I18 (2026-08-13) a module declares its own install shape in a module.json beside its files, modules/modules.json rosters which modules exist and in what order (a module nothing rosters is invisible, a rostered module with no manifest is a hard failure), and src/manifest.ts reads the two into the Part shape everything downstream reads. src/parts.ts itself is now just the types and the helpers – PARTS is exported as a Proxy over a backing array that loads off the manifests the first time anything touches it, so the 40-odd files that still import it as one flat array see exactly that. from in a manifest is module-relative (. means the module's own dir whole, ../ escapes for the few pulling from scripts/ or frameworks/), and to is relative to the target .claude/, exactly as before the split.
Each record maps a source path in the harness repo to a destination under the target .claude. A part is one of two shapes: a flat part carries a copies list and installs whole, one tickable row in the picker – chalk, memory, context, and the stack packs are flat. An accordion part carries a bundle of named groups and files the picker drills into – only hooks and orchestration are trees today, so a twenty-file bundle can go in whole or a few leaves at a time.
Two flags protect project data across an update. A keep path on a directory copy is a sub-path the project owns – memory's lessons, skill-smith's references/built – stashed over the wipe and put back, the project's version winning. An own file is a whole file the project owns – hooks' protected.nuon – seeded once, then never overwritten. Each recorded part also carries auto, its provenance: true means it landed as a resolved dependency, absent means it was picked directly, which is what lets a remove tell "this only came along" apart from "this was wanted."
The picker's top level row order is a separate list from the parts themselves, ROOT_ORDER in src/models/menu.ts (finn's own list, landed with I18). A group name or an ungrouped part's name that isn't in that list sorts dead last, after every named bucket and after external itself, so a module added without touching the list still appears, it just draws at the bottom until someone places it deliberately. sessions is the newest bucket (2026-09-10), holding just the one part, resume – the group name had to differ from the part it holds because harness validate fails a group that shares its name with a part (the picker keys a branch on its name, so a group and a part sharing one would collide in the same id space), so a module wanting its own top-level bucket sometimes needs a bucket name distinct from the part inside it.
Moving a part between groups costs nothing beyond the two files that declare it. group is display only – it folds parts under a picker branch, but the registry keys everything on the part's own name and stores no group at all, so a part changing groups needs no migration row and doesn't touch an already-installed project, only where it draws in the tree changes. commands landed as its own top-level group on 2026-08-30, right after skills in ROOT_ORDER, with its own blurb in GROUP_DESCS ("plain slash commands, one job each n invoked by name, no description doing routing work"), and briefing and sheet moved out of skills and into it as its two members. skills holds six parts now that they're gone – three loose single-job skills from modules/skills/module.json (find-todos, media-grab, prompt-engineer) and three banked c++ skills skill-smith writes into (cpp-lua-bind, profiler-zones, natvis-writer).
Every part also carries a weight ("light" | "med" | "heavy"), one coarse bucket folding what it injects into every session and turn together with what it spends on model calls when it runs – hooks is heavy ("injects at every session start n gates every tool call"), orchestration is heavy ("every workflow here fans agents, that is the point of it"), chalk and skill-smith sit at med, and limiter is light ("counts sessions off a registry, nothing model side"). It's a hand-assigned judgement call today (phase 1), read through one function, weightOf(part), which falls back to DEFAULT_WEIGHT ("light") when a part declares nothing – that single point of read is what lets a later telemetry-derived phase 2 swap in without any render path changing. The badge shows in the harness modules catalogue today; the install picker badge the same task asks for isn't built yet.
A part's manifest can also declare a config flag rather than its settings inline – harness config's form is read off a separate config.json beside the module's module.json, lazily, the first time anything actually opens it, so the cost of parsing a module's whole settings shape (orchestration alone runs to 70 field records) never lands on a cold command that never touches that view. A generic harness script gets the same treatment from the other roster, modules/scripts.json beside modules.json: one entry per script becomes its own flat part, script:<name>, under the scripts group, so a script reaches a project by being picked in its own right rather than by riding along as a copy leaf on whichever module happened to be volunteered to carry it.
Install Scopes
A part doesn't only ever land in a project's .claude. scopeFor in src/runtime/scope.ts is the one function every view resolves its target through, and it agrees on three destinations: project (the default), global (~/.claude itself, reached by --global, a cwd already inside ~/.claude/, or a --target on the home dir), and local module (harness-only dev tooling, seen and installed only through harness local, gated on the harness repo, and tracked in its own harness-local.nuon rather than the shared registry). A part also declares where it belongs with global?: "core" | "optional" on its record – a core part like limiter or skill-smith is filtered out of the project picker entirely, out of --parts all, and out of the project --list, and a project already holding one of their old copies from before the tier changed gets caught by the notices detector below rather than staying silently shadowed. The full map of what belongs where and why lives on its own page, Install Scopes.
An open edge: a built-in remove never unwires its hooks, so removing a global module leaves dangling settings entries that doctor flags but nothing pulls automatically.
Sub-Projects
A project carrying .claude/subprojects.nuon is split into slices, and the picker asks which slice before it draws. src/models/subprojects.ts owns the manifest – read, write, and derive; src/widgets/sub-pick.tsx is the chooser that settles the scope before harness install's tree is built; src/views/subprojects-view.tsx is harness subprojects, the read-only browser.
Two reserved keys never read as a sub-project (isReserved, anything starting with _): _base, the always-on tier every slice gets merged with, and _project, the parent project's own set – what was installed at project scope rather than claimed by a slice. The two are exclusive: claiming a part into a slice drops it from _project, and installing one at project scope drops it from every slice, so "who owns this" always has exactly one answer, and no reader has to work it out by subtraction (finn tried three passes of inferring it that way before landing on recording it directly, 2026-08-11).
Picking a sub-project in the picker draws that slice's world only – what reads as installed is the entry's own parts, not everything the parent carries. A part the slice doesn't claim but that is genuinely active there anyway (carried project-global, or the always-on _base tier) draws blue, and the two blues mean different things: a _base part is locked ([x], there's nothing to do with it, every slice gets it whatever the screen says), a loose project-global part stays tickable, because ticking it is the only way a slice ever claims it – the manifest is written straight off the picks (setSubEntry). Unticking a claimed part is claim-gated: nothing else claims it and it really uninstalls, another entry (or _base) still claims it and it only leaves this entry, files kept – the confirm splits the two under separate headings so a red [-] can never mean a file delete and a manifest edit without saying which. Confirming a scoped reconcile with nothing ticked is a real, deliberate answer – it writes the entry with no parts of its own, so a slice can ride the project-global set and the _base tier and still carry its own name, its own paths glob, and its own hooks, rather than the flow bailing with "nothing picked" the way it used to (tests/installer/drive-sub-empty.mjs drives this end to end over a faked tty, including proving a re-opened empty slice writes nothing on an esc).
forgetParts is the removal give-up: every removal in the manager (the installs view, a reconcile's drops, removeRecordedPart, the extern teardown) funnels through recordRemove in stores/registry.ts, which calls it, so a part that leaves the project also leaves every manifest entry that claimed it. Before this landed, a removed part sat in the manifest forever and the browser went on reporting it as not installed in this project – an unresolved reference, the stale list finn hit. healManifest is the one-time catch-up for a manifest that drifted before forgetParts existed: a claim the registry still holds under a new name re-keys (a rename), a claim the registry doesn't hold under any name at all drops (gone). It's the one place a read view is allowed to write, deliberately narrow (only ever parts), and it reports what it changed rather than silently rewriting a file finn hand-edits (tests/installer/sub-forget.mjs covers both functions directly against a temp manifest).
--subproject <name> on harness install names the slice up front and skips the chooser; headless (with --parts) it installs the normal way then merges the picks into that entry, add only, since there was no picker in it to have meant anything by what it left out. harness subprojects lists every entry plus _base, arrows and space expand a row into its sheet – its desc, why it's focused right now (off the router's own pointer), its parts and which other slice shares them (the dedup guarantee made visible, a manifest references a part by id and never copies it), what it advertises, its hooks with a red MISSING on any script not on disk, and its auto-focus paths / phrases – and enter drops straight into a scoped install for the row under the cursor, so browse-install-browse is one loop rather than three separate commands. Editing the desc, hooks, mcps, paths, or phrases by hand in subprojects.nuon is still how those change, a form over a file finn hand-edits anyway would be a second way to write the same thing and a second way to get it wrong.
Notices
What the dashboard raises about a project without digging through projects or installs for it. The banner and the check both run once per dashboard open, not per keypress, so the file hashing an update check does never runs on the arrow keys. Five detectors ship, run in order by collectNotices in src/models/notices.ts:
- A part the harness has since retired – a registry row with no def left. It names what replaced it off
src/retired.tsand offers replace with the successor (only when it still ships as a current part), remove, or ignore. Ignore here is terminal, since retirement doesn't change back. - A part that has since gone core-global – it belongs in
~/.claudeonly, and this project still holds a copy from before the tier changed. The picker already refuses to hand out a new one, but nothing reached back for copies placed before the change; a local copy shadows the global one silently, so the project stays pinned to whatever version it was installed at. Remove leads only when the global copy is actually installed to take over; otherwise ignore leads, since removing the only copy would leave the project with nothing. - One or more parts that are out of date – the source moved since they were installed. The primary action updates them all in place (project-owned paths survive); ignore is pinned to the version you dismissed, so a real further change surfaces again rather than staying silenced forever.
- One or more pending migrations – the def changed in a way this project's copy hasn't caught up with. This is the one detector that carries a real fix rather than only naming a problem:
mruns every pending migration,zignores. The ignore id is pinned to the pending set, so it holds only until what's owed changes – a new requirement landing after a dismissal is new information and surfaces again. See the Migrations section below for the full mechanics. - An orphan pileup –
harness clean's own scan, run again here once unclaimed paths cross a threshold, so a project that never openscleanstill hears about it. It's the one detector that walks the filesystem rather than only reading the registry, and its ignore (y) is pinned to the count, so more leftovers appearing surfaces it again.
Esc never acts here – it used to run the ignore action, which meant backing out of a look at a notice quietly dismissed it, so an ignore now has to be asked for by its own letter like every other action. Dismissals live in ~/.claude/harness-notices.nuon (HARNESS_NOTICES overrides), keyed per project.
Migrations
The harness ships a definition and a project holds a copy of it, so every change to the def opens a gap between what the harness says a module is and what's actually sitting in someone's .claude/. src/retired.ts was the only thing that had ever spoken to that gap, and it can only name a successor – it migrates nothing. src/migrations.ts is the general answer: one row per change that needs something done to the copies already out there.
The case that proved renames alone were too narrow: a module gains a hard needs on a part that didn't exist when it was installed. Adding the dependency to a module's manifest fixes nothing for the projects already holding that module – an install only resolves deps for the parts it's installing that run, so every existing copy is quietly short a requirement and nothing would ever say so.
Six kinds cover it today, split into two classes on a safety rule rather than a taxonomy
| Kind | What it says | Class |
|---|---|---|
rename | The part is the same part under a new name. | Auto – re-keys on read |
part-split | An option grew into a part of its own; the dests it shipped under now belong to a different row. | Auto – re-keys on read |
needs-part | This part now requires that one; install it here. | Pending |
dest-move | This dest moved; move the file with it. | Pending |
drop-dest | This dest stopped shipping; take the stale file. | Pending |
custom | The one-off none of the above can say; it decides and acts for itself. | Pending |
part-split (I19.7) is the newer auto kind. When a generic script stopped being a copy leaf riding whichever part was volunteered to carry it and became an installable part of its own (script:<name>), nothing on disk moved, only the row claiming the file changed. splitDests derives exactly which dests moved by diffing the old part's and the new part's own allCopies rather than listing paths by hand, so the row can never drift from the manifests it describes, and a promoted row is stamped auto: true regardless of the source row's own provenance – the file was never picked for its own sake, it came in with whatever module called it, so a later remove offers the script part back once the last thing needing it goes.
Two custom rows outlived their own justification, and the settled answer is that they stay. nudge-retired-stop-hooks and budget-dead-gate-hook both open by explaining that no declarative kind can say what they say, because the stale thing is an entry in settings.json rather than a file any part ships. stripOrphanHooks in engines/merge.ts made that untrue on 2026-09-08: it cuts any hook registration whose script is not on disk, generically, wherever a remover runs. Finn's call on 2026-09-10 was to leave both rows in place rather than retire them. They are applied history, both are applies guarded so they cost a clean project nothing and self-skip, and pulling them would leave a project that never migrated depending on somebody thinking to run doctor --fix on it. What actually changed is narrower: no new row of that shape gets written, because the orphan strip is the answer now. A comment at the head of the MIGRATIONS array says so, so the question does not get raised a third time.
A hand-written list is exactly the kind of thing this table exists to replace, and it caught itself out once. The context-toolchain-reparent custom row that folds .claude/context/ skips whatever belongs at the parent and reparents the rest into context/tools/ – and "what belongs at the parent" used to be a literal array, ["tools", "budget", "handoff", "injectors"], the four dests that existed the day the row was written. Two days later the clock claimed context/clock/, which was never on that list, so the row read a freshly installed clock as leftover pre-fold toolchain and offered to move it into tools/, silently breaking its two hooks – every project installing the clock owed a migration that would eat the part it had just installed. The fix is contextKids(), which derives the set from the dests the parts actually declare under .claude/context/ rather than naming them by hand, lazy and memoised since PARTS is a proxy that loads every manifest on first touch and this file sits on the read path in every view. tests/installer/gate-context-fold.mjs grew a check for exactly this: it plants .claude/context/clock/ on an already-folded project and asserts the row stays quiet, proved by reverting the fix and watching that check fail.
Auto is a pure record rewrite with no disk touched, applied on registry read (applyRecordMigrations inside loadRegistry in src/stores/registry.ts), in memory, every view included – so a project untouched for a month reads correctly the first time it's opened, and nothing has to run in the right order. The version hash and whole flag ride across untouched on a rename, and a row already recorded under the new name gets the old one's dests unioned onto it rather than a second row appearing.
Pending is everything that writes, moves, or deletes. It never rides the read path – a read happens in every view, and a view that silently changes a project on disk isn't something you could reason about. It's detected on read (cheap, pendingFor), surfaced (a dashboard notice plus the harness migrate view), and applied only when asked.
A dest-move moves the file rather than reseeding it from source, which is the whole own / keep story: a project-owned config at the old path is the project's copy, so carrying it across preserves what was tuned into it, where a reseed would hand back the shipped default and call it a migration.
harness migrate is the view, and its posture is the opposite of harness clean – every row opens marked to apply, and you untick what you don't want, because a pending migration is the def saying you're behind rather than a judgement call. Anything moved or removed is copied into .claude/.bak/<run>/ first, one migration failing never sinks the rest, and each one that lands writes a migrate ledger event naming its id. A needs-part install is stamped auto, so it's offered back on a remove like any other resolved dependency.
harness migrate # the list, tick what to apply
harness migrate --list # what is pending, touching nothing
harness migrate --yes # apply everything pending, headlessharness migrate dropped off the dashboard menu 2026-08-15 (finn's call), though the command itself is unchanged and still opens the per-migration picker. harness doctor now carries a migrations section reading the same pendingHere the notice detector reads, and applies them in place off its own f / a prompt through the same runMigrate – a pending migration was always a health-pass finding, and a dashboard row of its own meant doctor could find one and then send you elsewhere to act on it.
G-mig-1 is the guardrail: every row must point at things that exist – a part name that resolves in the loaded manifests, and for a dest-move, a to the part actually ships. harness validate fails on a broken row, and both the read path and the applier skip a broken row per row, so one bad entry never stops the good ones. It's gated by tests/installer/gate-migrations.ts, 41 gates including a real end-to-end needs-part install.
src/retired.ts lost its context -> files row to this table – a retirement says a part stopped existing, a migration says it is the other one under a new name, and those are different enough facts that they now live in separate tables.
Retired Permission Rules
A permission rule can leave a shipped settings-fragment.json the same way a part can leave the def, but the settings merge is add only (mergePerms unions a fragment's rules in and never removes), so narrowing or replacing a rule only stops new installs from getting the old rule – every project that already holds it keeps it silently and forever. src/retired-rules.ts is the twin of retired.ts for this case: a table rather than a diff against the shipped fragment, deliberately, because a diff would flag every rule finn wrote himself by hand in a project's own settings. harness doctor reads it in a permission rules section, warning when the rule's replacements are already present (dead weight, just delete it) and failing when they aren't (deleting it alone would drop coverage it once provided). settings.local.json is read too but reported apart, since the merge never wrote to it, so a hit there is hand-authored. It's report only – --fix doesn't touch it – and harness validate fails a rule that's marked retired but still shipped (G-rule-1).
Profiles and the State Files
A profile is a named selection of parts – { name, dests, whole? } – saved from the picker with s or built headless with harness profile save. Storing the exact dests a save was made with is what lets an accordion subset round-trip exactly; a part taken whole is stamped whole, so it adopts files that part gains later rather than freezing today's file list. Profiles live in their own file, separate from every other config, global and per-machine so one can seed a project that has nothing in it yet.
The manager keeps its state outside any repo, in ~/.claude, each file resolved through its own path function so a HARNESS_* override always wins:
| File | Holds | Override |
|---|---|---|
harness-installs.nuon | the install registry, keyed by target, each part's dests and content digest | HARNESS_REG |
harness-ledger.jsonl | one append-only line per install / update / remove / migrate, what stats --history reads | HARNESS_LEDGER |
harness-profiles.nuon | named part-selections | HARNESS_PROFILES |
harness-settings.nuon | the dashboard's stay-or-menu policy, empty-project mode, picker fold state, install mode, per-row menu visibility, and sticky cursor | HARNESS_SETTINGS (HARNESS_CONFIG still works) |
harness-notices.nuon | per-project dismissed notice ids | HARNESS_NOTICES |
harness-local.nuon | local module installs, harness repo only, never the shared registry | HARNESS_LOCAL |
harness-store.nuon | the store pointer (2026-08-30) – harness local stamps it, merged rather than overwritten, when it installs a module that declares a stamp. Holds { "<key>": "<absolute dir>" }, one entry per relocated store, and telemetry is the only key today, naming where the telemetry stores actually live now that they've moved into store/telemetry/ in the harness. It's a config naming the data's address rather than the data itself, which is why it stays here while what it points at doesn't, and a missing or hand-broken pointer just reads as absent rather than throwing, so every reader falls back to ~/.claude | HARNESS_STORE |
Every file is written as JSON inside a .nuon extension, which Nushell's from nuon reads fine either way. harness uninstall --harness clears the first five – the registry, ledger, settings, profiles, and notices – plus the npm-link global shim, best effort; --all additionally walks the registry and removes every recorded per-project install through the same removeRecordedPart engine everything else uses, so keep and own paths survive there too. A bare harness uninstall, with no --harness, is a different command in practice, a project-scoped teardown rather than a global sweep – see Uninstall, the Teardown at Two Scopes below. harness-local.nuon is deliberately not swept – it's the harness's own dev-repo state, not a friend-share trace. harness-store.nuon is left alone too, on purpose: removing the telemetry module doesn't unstamp where it pointed, so whatever else still resolves through it keeps finding the same store.
The registry digest is the whole staleness story: src/runtime/version.ts's hashPart walks every shipped file sorted, builds a manifest of path:sha256 lines, and takes the first twelve characters of the manifest's own hash. Compare the stored digest to a fresh one and a part reads current, stale, or new – the same math install, installs, projects, diff, doctor, and notices all read, so none of them can ever disagree about what needs an update.
Uninstall, the Teardown at Two Scopes
harness uninstall is one command at two scopes, and the default is the safer one (2026-08-30, finn's call). Bare, it takes this project apart. --harness instead takes the harness itself apart – the npm-link global shim and the ~/.claude/harness-* state files, which is what the bare command used to do before the default flipped. harness purge briefly existed as the project half's own standalone command, for three days, before it was folded back into uninstall; a reference to a separate purge command anywhere is stale. purge survives only as the internal word for the project scope – src/models/purge.ts builds its plan, src/engines/purge-run.ts runs it, and the ledger records the run as a purge action – but there is no harness purge to type. It's CLI-only and off the dashboard menu, the same call notices and validate got: a keypress away from the home screen is the wrong distance for something that can take an archive/. It dry-runs unless --yes or --all says go, and it prints the whole plan before it asks anything.
The project scope, bare
Everything the harness put into one project comes out in four tiers, in this order, and the order is the safety:
- The parts – every part the registry records here, through the shared
removeRecordedPart, sokeepandownand the extern teardown behave exactly as an ordinary single-part remove does, and the ledger gets its normal per-partremovelines. First, so the bookkeeping is right even if a later tier is refused. - The extras – the paths those parts create at runtime, off the
createsfield in their manifest (below), plus the manager's own project-side files (the clean log, the two clean/scripts ignore lists,.claude/.bak), which are built in rather than declared and are derived off the store modules that own each path so they can't drift. .claude/itself – always offered, always a prompt, always defaulting to keep.- The global stores that name this project by path.
Two modes, and they're declared by the module, not picked by the user: auto is derived state a fresh install rebuilds, so it goes with the run and is never asked about; prompt is something the project would genuinely miss, so it asks keep or remove and defaults to keep. The run flags only say what an unattended run does with the prompt tier – --yes keeps every one of them, --all takes every one of them, .claude/ included.
harness uninstall # dry run against the cwd, prints the plan
harness uninstall --target <dir> # another project
harness uninstall --yes # run it, every PROMPT item is KEPT
harness uninstall --all # run it, every PROMPT item is REMOVED (incl .claude/)The harness scope, --harness
What the harness leaves outside its own folder – the folder itself is delete-to-remove, the bundled nu rides inside it, this is the rest: the five ~/.claude/harness-* state files and the npm-link global shim, best effort. --all additionally walks the registry and removes every recorded per-project install through the same removeRecordedPart engine, so project-owned keep / own paths survive there too – but it stays tier one only, the shipped files and nothing else. A project's archive/ is that project's own data, not the harness's, so a whole-box teardown has no business sweeping it; the four-tier bare command, run per project, is what takes a project fully apart.
harness uninstall --harness # dry run, says what it would clear
harness uninstall --harness --yes # clear the global state and the shim
harness uninstall --harness --all --yes # also remove every recorded per-project installcreates, what a part leaves behind
A part declares the paths it writes at runtime that no to (a copy's own destination) ever named. The distinction that matters is what gets recorded: a copy records a source and a dest, so the installer writes it, the registry stores it in dests, hashPart covers it, and every remove already knows about it. A creates entry records a dest with no source – nothing in the harness ever writes it, it appears in no registry row and no hash, and (for the archiver's archive/) not even under .claude/. An own copy isn't a creates either – it has a source and is recorded, just spared on an update. Nothing but harness uninstall reads the field; an install or an update never touch it.
json
"creates": [
{
"path": "{}/wiki",
"mode": "prompt",
"desc": "the generated docs site, hours of subagent writing plus its node_modules, regenerable but not cheaply",
"pathFrom": { "file": ".claude/wiki/wiki.nuon", "key": "parent" }
}
]path is target-relative and forward-slashed, the same shape as a copy's to, and {} is where a pathFrom value lands in it. mode is auto or prompt, the same split as the tiers above. desc is required – it's what the prompt tells you you're about to lose, and a prompt with nothing to say is a rubber stamp. pathFrom is optional, for a root the project can move: it reads one key: value pair out of a project config file with a tolerant line regex, not a nuon parse, and substitutes it into path. The archiver's archive_root is the path; the wiki's parent is the dir holding the site, so it declares {}/wiki. Twelve declarations across eight parts carry the field today – adherence, project-router, skill-smith, sieve, memory, careful, wiki, and archiver. src/manifest.ts checks a creates entry at load, so a malformed one is a manifest error rather than something a teardown discovers with a delete already in its hand, and harness validate carries a creates section that re-runs the teardown's own refusals against each declaration and warns when a pathFrom names a file the part doesn't actually ship.
The safety posture
There's deliberately no .bak copy the way harness clean makes one – a teardown moves things measured in gigabytes, so a copy is a second copy of the problem, not a safety. What stands in for it:
- Every path is declared – off a manifest, off a store module, or the literal
.claude– nothing walks a disk and calls what it finds a candidate, the exact shape that cost a whole test project's.claude/on 2026-08-11. - The containment gate runs twice – at plan time in
src/models/purge.ts, and again at the moment of the unlink insrc/engines/purge-run.ts– because every safetyharness cleanhad before that incident lived in its scan, in the thing that turned out to be wrong. .claudeis spelled once, from a constant, so tier 3 can only ever mean<target>/.claude.- The home dir is refused outright – that's the global install, and
harness uninstall --harnessis its command.
One honest gap: ~/.claude/harness-usage.jsonl keys its project field on a folder basename rather than a path, so two projects sharing a folder name are indistinguishable in it. A teardown counts those rows and reports them, but never touches them.
Roles, the Persona Catalogue
harness roles is harness modules for personas – a role is a whole ROLE.md a session adopts for the work in front of it, and the harness carries a collection of them so a project can take one rather than have the persona written out again. It opens on a chooser rather than dropping straight into a list, three halves now: composer (the base personas, pick one and bolt subskills onto it), library (roles already composed, pick one to adopt), and installed (this project's own roles and what the role router ranks them by).
The chooser is a loop, and esc is two levels here rather than one – esc off a list lands back on the chooser, and esc on the chooser is what leaves the view. Crossing between halves used to be a tab swap in place; that was cut (2026-08-08) once the chooser stopped being a one-time gate the moment esc came back to it, and because the swap was the thing pushing the hint line past a 100 column frame. The chooser also remembers its cursor across that loop, gated on the sticky cursor toggle in harness settings (on by default) – backing out of a list lands you back on the row you came through rather than at the top, and leaving the view forgets by construction, since the memory is one variable in the loop and nothing is stored.
Installed is the newest half (2026-08-08). It lists the project's own roles – .claude/roles/ when a pool exists, or the lone .claude/ROLE.md stood up as a single row when it doesn't, so the screen works whether the router is on or off. A separate router screen briefly existed here and was merged away as a bug fix: it listed the routing table's own rows, which ship keyed to finn's global library, so every project was shown roles it had never had. The merge is the fix – the rows are always the project's own, and the table only ever supplies keywords to them.
| Key | What it does |
|---|---|
a (or c) | Add a role – jumps straight to the composer, writing into the project's own pool, since the rows on this list are the project's own and the thing you build off is a harness base. |
e | Edit the words that rank the role under the cursor. One prefilled field does add and remove at once; a role the routing table doesn't know about gets a row added, which is the only way a project role outside the shipped table becomes rankable at all. |
t | Flip the tokeniser (hyphens include/exclude), writing immediately. |
-> | Expand the sheet, which carries a routing row the other two halves don't. |
The router itself is derived, never stored – it's on whenever .claude/roles/ holds at least one role, exactly how role-route.nu decides it. Adding a second role is what turns it on, and that carries the project's existing ROLE.md into the pool as a copy, not a move, because inject-project.nu injects .claude/ROLE.md at session start and nothing there reads the pool: the pool is what you pick from, ROLE.md is what you picked.
The composer opens on enter (or c) over a base role: a base plus one or more subskills bolted on, and nothing is written until its last screen, so esc at any stage leaves the project untouched. It's three stages now – pick subskills (enter ticks, tab or ctrl+enter confirms), name the result (a text field prefilled with an auto name, take it or type over it), then the library (y also banks it there, n installs to the project only – either way it installs to the project). A fourth keep stage (2026-08-08) only fires when the compose would actually destroy something: writing over a .claude/ROLE.md that no pool copy is already holding asks first, and y copies the old role into the pool before the write lands. The guard, roleAtRisk, is a content compare rather than an existence check, so a project whose pool already holds a byte-identical copy is never asked. The scriptable twin refuses rather than guessing – --compose exits 1 naming --keep (save the old role first) or --replace (lose it on purpose).
harness roles the catalogue
harness roles --role physics-dev the sheet for one, printed
harness roles --install <name> adopt one into the target, non-interactive
harness roles --compose physics-dev --with sfml3,embedded-systems the compose flow, non-interactive
harness roles --compose physics-dev --with sfml3 --keep save the role being replaced first
harness roles --compose physics-dev --with sfml3 --replace lose it on purposeKey Files
The Entry
harness.tsx
The one entry – parses argv, opens the dashboard when run bare in a tty, and otherwise dispatches to one of the twenty view runners in its COMMANDS map. takeGlobalFlag strips --global off the line before dispatch so a bare harness --global still reads as bare.
dashboard.tsx
The home menu – the pick list bare harness opens, one row per view. needsProject marks a row that reads a project's own .claude and greys or hides it against an empty one (harness settings picks the mode); harnessOnly drops local from the list outright outside the harness repo. Reads bannerFor once per open for the notices banner line.
The Part Model
manifest.ts
The parts loader – loadParts is the one place the part set is decided: readRoster walks modules/modules.json in order, loadModule reads each module's own module.json and resolves its copies, bundle, and creates paths from module-relative into the shape the rest of the manager reads, and loadScripts then appends the modules/scripts.json roster as its own flat parts, one per generic script, so a script reaches a project by being picked on its own rather than by riding along on whichever module happened to carry it. A part's config field is a getter, not a parsed value – attachConfig only opens the module's config.json the first time something actually reads it, so a cold command never pays for a form it never shows. A manifest problem is always fatal and always names the file (ManifestError): a module rostered with no manifest, or a manifest that isn't valid json, stops the load rather than silently dropping the module. readModuleIndex is the parallel read harness modules uses to keep a module's parts grouped under its own name rather than flattened away.
parts.ts
The types and the helpers, not the definitions any more – Copy / Node / Part / Pick, allCopies to flatten a flat or accordion part, and the Weight / GlobalTier fields plus weightOf, the one reader for usage cost. PARTS is a Proxy over a backing array that loads off src/manifest.ts the first time anything touches it (I18, 2026-08-13), rather than a literal array – adding a part is a record in a module's own module.json now, not a line in this file. It also carries Created / CreateMode / PathFrom and Part.creates, the types the teardown reads.
menu.ts
The PARTS-to-picker bridge – buildRoots turns the loaded part list into the tree of MenuNodes the picker and the profile browser both draw, folding grouped parts under one branch, rolling a branch's status and weight up from its children, and hosting a module's own parts under its row via under. ROOT_ORDER is the one list that decides the picker's top-level row order; a bucket not named in it sorts after every bucket that is – sessions (holding resume) sits between project-router and archiver in the list today. GROUP_DESCS carries the blurb each group branch shows, commands (added 2026-08-30 alongside the group itself) among them.
scope.ts
The one scope resolver – scopeFor(target?, globalFlag?) is what every view comes through to decide project versus global, so the three ways of asking for a global session can never disagree with each other.
deps.ts
The dependency engine – resolveDeps (the transitive, cycle-safe closure), dependants (the reverse edge, what still needs a part before it's removed), orphanedAutos (what an --autoremove would clear), and checkDepGraph (what validate renders).
migrations.ts
The migration table – one row per change that needs something done to a project's already-installed copy: rename, part-split, needs-part, dest-move, drop-dest, custom. Pure – renamedTo follows a rename chain to its end for the read path, splitDests derives which dests a part-split actually moved (diffed off the two parts' own allCopies rather than listed by hand), pendingFor derives what a project still owes, and migrationOk / brokenMigrations back the G-mig-1 lint. contextKids() is the same derive-don't-list rule applied to the context-toolchain-reparent custom row, lazily reading the set of dests the parts actually ship under .claude/context/ rather than a hand-maintained list, which is what stopped a later part (the clock) from being read as pre-fold leftovers and reparented into the wrong place. It writes nothing itself; the writer is migrate-run.ts below.
purge.ts
The project-teardown plan – src/models/purge.ts, pure. buildPurgePlan walks the four tiers, resolving each part's creates entries (including a pathFrom read against the project's own config) and the built-in project-side extras, sizes what it finds, and runs the first pass of the containment gate. Same pure-model / destructive-engine split clean runs on, so the gate is readable apart from the thing it gates. src/views/uninstall.ts is the one caller.
The Engines
installer.ts
The copy engine – resolveSource finds the harness repo, buildPlan flattens picks to absolute src-to-dst copies, runInstall does the stash-wipe-copy-restore so project-owned paths survive an update, and runRemove clears a part's shipped files while leaving own files and keep sub-paths.
install-run.ts
Where every install goes through – executeInstall runs the recap, the prompt, the copy, the clash check, and the registry and ledger record in one fixed order, so nothing can happen out of sequence between an interactive run and a headless one.
reconcile.ts
The picker's three-in-one pass – executeReconcile is the install-plus-refresh-plus-remove confirm the plain interactive picker drives, built off the same pre-tick and stale-status truth the checkmark colours read from.
refresh.ts
Every viewer's refresh – runRefresh is what --update-all, installs, projects, doctor --fix, and the notices update action all call, so an extern pick refreshed from any of them re-runs its token rewrite and merges rather than getting a plain copy.
registry.ts
The install ledger – reads and writes the global registry, keyed by target with earlier parts unioned back in. recordInstall / recordRemove update a row, globalParts / isGlobalRow read what's installed globally, and picksFromEntry / recordedPicks reconstruct exactly what to refresh, subset-aware. loadRegistry applies any pending rename and part-split migrations in memory on the way out (applyRecordMigrations), so a renamed or promoted part reads correctly under its current name the first time anything opens the registry after the change lands. recordRemove also calls forgetParts in models/subprojects.ts, so a part leaving the project gives up its claim in every sub-project manifest entry too.
version.ts
The digest and the staleness math – hashPart is the per-part content digest the registry stamps; copyStatus / partStatus / rollupStatus turn a stored or freshly computed digest into the current / stale / new colours every view paints, and footprint is the files-and-bytes weight stats and modules both read so the two numbers can never disagree.
migrate-run.ts
The one writer for migrations – runMigrate applies a picked set of pending rows: backs up anything about to move or be removed into .claude/.bak/<run>/ first, works through each kind, rewrites the registry row, and appends a migrate ledger event. pendingHere is the one derivation the view, the headless --yes path, and the notices detector all call, so a row can never read due in one place and not-due in another.
purge-run.ts
The one removal path for a teardown – src/engines/purge-run.ts's runPurge re-runs the containment gate at the moment of the unlink (the plan-time pass in models/purge.ts is the first, not the only, safety), works through the four tiers in the plan's own order, and reports what it actually took so src/views/uninstall.ts can recap it.
The Views
install.tsx
The picker command – builds the parts into the picker's tree, colours each node on an update, opens the sub-project chooser first when a project carries .claude/subprojects.nuon, and runs the flow through executeReconcile when it's a plain interactive session against an already-installed project. In sub-project scope, confirming with nothing ticked writes the entry empty (a real answer, not a bail) rather than falling through to the ordinary "nothing picked" exit.
profiles.ts
The profile store – alongside profile-pick.ts (the dests-to-leaf-ids bridge that lets a subset round-trip) and profile-cmd.tsx, the view harness profile runs.
installs.tsx
The per-project manager – drill into one project and update or remove a part at a time; remove asks first and spells out what survives.
projects.tsx
The global browser – every project the harness landed parts in and how each one stands, enter refreshes a row in place.
hooks.tsx
The wiring viewer – reads the intended hooks from every shipped settings-fragment.json, checks each against live settings.json, and closes the gap in place with --merge, through the same applyMerge engine doctor --fix uses.
scripts.tsx
The tools viewer – scans a project's .claude for its .nu tools through nu-scan.ts, a port of context/script-registry.nu's own header parser, so this view and the generated SCRIPTS.md never disagree.
doctor.ts
The health pass – one static report rolling staleness, wiring, and the runtime resolution into a pass/fail, plus a migrations section (off the same pendingHere the notice detector reads, applied through runMigrate) and a permission rules section (off src/retired-rules.ts), alongside diff.ts (a per-file preview of what an update would change) and archive.ts (a skin over the archiver's whole engine, not just the pruner). --fix walks each fixable finding and resolves it.
archive.ts
harness archive – the manager's skin over a project's own archive.nu, every verb here shells that tested nushell engine rather than reimplementing it, so the two can never drift. The default view frames the pruner's own report (piling up, orphaned, retired), --why runs the real guard chain under a dry run and names whichever guard stopped a stamp (or says none did, the loud "would stamp" verdict), --retire / --unretire resolve a partial name through the engine and never guess between two matches (several hits come back as a list and the run stops), and --clean is the one verb here that can remove anything, so it always renders the dry plan first and a real run waits on a confirm.
settings.ts
The dashboard's own behavior – the per-view stay-or-menu policy (VIEWS), the empty-project mode, the picker's remembered fold state, the install mode, per-row menu visibility, and the sticky cursor toggle a looping chooser reads, all in harness-settings.nuon; settings-view.tsx is the toggle screen. Named config.ts until the 2026-08-04 rename split it from the per-part settings below, one letter apart and neither name saying whose settings it meant.
config.ts
A part's own settings – harness config lists the installed parts that declare a config record, then opens a form over that part's declared fields; the form is module-agnostic, so a second part with settings adds a def entry rather than a line of this file. config-view.tsx is the form; a value left on default is never written, so the file on disk only ever names where a project departs from the shipped defaults.
migrate-view.tsx
The harness migrate view – a flat list, not an accordion, since there's nothing to expand: a row is a kind, a one-line description, and (under the cursor) the reason it was added. Every row opens marked to apply; space skips it, a flips the whole set at once, and tab or enter runs runMigrate on whatever is still ticked.
ignores-view.tsx
The ignore list, browsed – one screen over both tiers for whichever store it's handed, harness clean --ignores or harness scripts --ignores are the same screen with a different name. A flat table of path, scope, and a COVERS count run against a fresh disk walk, so an entry matching nothing today reads stale rather than looking load-bearing. del del drops an entry, armed the same way harness local arms a destructive key.
Sub-Projects
subprojects.ts
The sub-project manifest – .claude/subprojects.nuon read / write / derive, sliceClaimedParts (every part some slice claims, the one rule installs, projects, and the install picker's parent scope all read so they can't drift), claimants (the claim-gate a scoped removal reads), and the two unwrites, forgetParts (a removal gives its claim up, called from recordRemove) and healManifest (the one-time catch-up for a manifest that drifted before forgetParts existed). It does not read stores/registry.ts, the recorded part names come in as an argument.
sub-pick.tsx
The sub-project chooser – lists the parent project itself, every manifest entry, and a + new sub-project row that prompts for a name. Opens in front of harness install's tree whenever a project carries a manifest, and settles the scope before that tree is built, which is what lets the tree draw one slice's world.
subprojects-view.tsx
harness subprojects – the read-only browser over the manifest, _base included, arrows and space expand a row into its sheet, enter drops straight into a scoped install for the row under the cursor rather than opening a second command.
Roles
roles.ts
The persona model – discoverRoles parses the base collection, roleRows states them against a target, rolePart synthesizes the one copy, discoverLibrary reads the composed roles/library/ subfolder, projectRoles decides whether a project reads its own pool or the lone ROLE.md, and roleAtRisk is the content-compare guard the composer's keep stage reads. Model-agnostic like modules.ts, so the screen and the --json dump read one truth.
roles-view.tsx
The view – the chooser loop over composer, library, and installed, and the composer's own stages (subskills, name, library, keep). Mounts the composer in place of the list rather than beside it, returning early on composing !== null rather than toggling ink's isActive, since toggling raw mode off then back on does not survive contact with Windows Terminal.
router.ts
The routing table, read and written – readTable / writeTable parse and re-emit .claude/context/roles.nuon as the native nuon it already is, comment block and row order kept verbatim rather than rewritten as json. The reserved _router key carries the tokeniser setting, written only when it departs from the default, so an old role-route.nu – whose scoring runs a where over every value – never sees a shape that errors it.
The Catalogue and the Bank
modules.ts
The catalogue model – collectModules merges the four sources (built-in parts, core-globals, the discovered extern bank, and local dev tools) into one class-tagged list, sheetFor gathers one module's full sheet, and refreshStale is the one action the view (modules-view.tsx) exposes: refresh every out-of-date install of a module across every live project and the globals row at once.
globals.tsx
The global-only view – one row per core-global module with an update-all row on top; tab confirms into the same reconcile summary install uses.
local.ts
The local modules – the LOCAL array is the one declaration of the harness's own dev tooling, read by the bank browse (to reserve the name), validate (to fail a part reaching into a local path), and local-view.tsx / local-store.ts (the view and its separate install store).
extern.ts
The bank discovery – discoverExtern walks extern/{plugins,skills,commands,agents,hooks,mcps}/ and synthesizes each entry into an ext:<name> part the picker and registry already understand; the bank itself, its manifests, and the download / update-check / modify story are documented on the Extern page.
Global State
notices.ts
The notice model – the per-project dismissal store and the five detectors behind collectNotices; notices-view.tsx renders and drives them, bannerFor feeds the dashboard line.
runtime.ts
The interpreter resolver – resolveNu is the one place anything in the manager gets a nushell interpreter from, PATH first, the bundled bin/nu/bin/nu.exe second, smoke-tested with --version so a binary that can't run on this box fails here rather than inside a hook later.
stats.ts
The registry roll-up – install counts, footprint, and version drift off the live registry; --history reads harness-ledger.jsonl instead, for churn over time the current-state registry can't answer.
uninstall.ts
The one teardown command, dispatched to two scopes – bare it runs the project scope, handing off to buildPurgePlan and runPurge (models/purge.ts / engines/purge-run.ts above); --harness runs the harness scope in place, clearing the five global state files plus the npm-link shim, with --all additionally walking the registry to remove every recorded per-project install through removeRecordedPart. src/views/purge.ts doesn't exist any more – this file absorbed it when the two commands merged (2026-08-30), and harness purge stopped being something you can type.
validate.ts
The parts-def lint – checks every part's from exists, no two copies collide on a to, keep / own fit their copy kind, the dependency graph (checkDepGraph in deps.ts) has no dangling target, self-reference, or cycle, and (I20) that every creates declaration points at something real, re-running the teardown's own refusals against it.
ignore-list.ts
The two-tier ignore store – one list per view name (clean, scripts today), a project file at <target>/.claude/harness-<view>-ignore.nuon and a global one at ~/.claude/harness-<view>-ignore.nuon (HARNESS_CLEAN_IGNORE / HARNESS_SCRIPTS_IGNORE override), both read and neither winning – an entry in either spares the path, the same shape the rules system runs. A path is written the way the owning view spells it: target-relative, forward-slashed, opening .claude/. A directory entry covers its whole subtree, and a * makes an entry a glob (* stops at a slash, ** crosses them). JSON under a # comment header; every read failure comes back empty rather than throwing.
Shared TUI
picker.tsx
The install flow – one Ink app owning both the pick and confirm phases, a tree with tickable leaves and cascading branches, so stepping back redraws in place and nothing stacks.
confirm.tsx
The proceed prompt – enter or y goes, esc or n bails, with an optional step back to the selection.
select.tsx
A single select list – up/down move, enter picks, esc bails; the shared list the interactive views reuse, and what the roles chooser loops on. runSelect takes an optional descs array to print the focused row's blurb dim under the list, a note for a looping caller to report on the pass that just ended, and opts.at / opts.title to reopen the cursor somewhere other than row 0 under a real bright-bold header.
ui.ts
The plain-ansi helpers – the colour wrappers (no-ops when piped), freshScreen, and GLOBAL_BLUE, the one colour every view uses to mark a locked global row.
ignore-scope.tsx
The shared "which tier" prompt – asks project or global whenever i or shift-i bank a path, shared by both harness clean and harness scripts so the question reads the same way in both. It's a whole screen rather than an overlay, deliberately: the view it interrupts already owns a live useInput handler, and two active handlers would both catch the same keypress.
Connects to
- The delivery mechanism for every module – chalk, skill-smith, orchestration, memory, hooks, context, careful, find-todos, wiki, brain, and the nushell / cpp / ahk / ue5 / ts stack packs each declare a
module.jsonthe manager loads as a part. - Places and preserves Skill-smith's global-only home – a
global: "core"part installed only throughharness globals, with akeep: ["references/built"]so an update to the shipped skill never wipes its banked corpus. - The full picture of where a part can land is Install Scopes – project versus global versus local module, the core-global rule, and the shadowing failure the notices system now catches.
- Delegates browsing and downloading the module bank to Extern –
harness externis this manager's window onto it,discoverExternfolds every entry into a part the picker, registry, and hashers already understand. - Records where an install went for project-router, installed into the same parent project –
.claude/subprojects.nuonis what that part routes off at runtime, andharness install --subproject/harness subprojectsare the only things that write and read it from this side. - Audits hooks specially – parts ship hook scripts but the settings that fire them are merged by hand, so
harness hooksreads each shippedsettings-fragment.jsonand flags the ones sitting on disk wired to nothing. - Shares a read with context –
harness scriptsparses.nutool headers through a port of context'sscript-registry.nu, so its view and the generatedSCRIPTS.mdagree, andharness doctorrolls the whole picture into one pass. - Shells the project's own
archive.nufor every verb – the prune report,--why,--retire/--unretire, and--clean– rather than reimplementing any of it on the TypeScript side, so the two can never drift. - Diverges from Role Router on purpose –
harness rolescomposes and browsesharness/roles/through its own resolver, while the router ranks.claude/roles/(or the global fallback) for/roleandcompile-context.nu; see that page for why the three roles directories aren't meant to agree. - Writes the store pointer
harness localstamps for the telemetry module –~/.claude/harness-store.nuonnames wherestore/telemetry/lives so every tracker's ownstore-dirdef and this manager'sstores/telemetry-dir.tsresolve the same directory. - Reads a project's archiver config (
.claude/archiver/archive.nuon'sarchive_root) and wiki config (.claude/wiki/wiki.nuon'sparent) through acreatesentry'spathFromwhenharness uninstallsizes and prompts about their runtime output, the two live cases for a relocatablecreatesroot. - Placed Resume's
resumepart in its own top-level bucket,sessions, inROOT_ORDER(2026-09-10) rather than folding it intocontextorother– the bucket and the part it holds needed different names to clearharness validate's group-name gate.