Appearance
Install Scopes
A harness part is just files sitting in the repo until something places them, and there is more than one place a part can land. Project is the default and covers almost everything, but a handful of modules only make sense once per machine, and a handful more are development tooling for the harness repo itself rather than anything a project should ever see. Picking the wrong scope for a module is not a style choice – a per-project copy of a module that wants one shared home breaks silently, because the wrong copy still runs, it just runs alone. This page is the map: the four ways a part reaches a machine, and the rule for telling which one a given module wants.
The Four Scopes
Project, the default. harness install copies a part's files into the current project's .claude/, one PARTS record becomes one row in ~/.claude/harness-installs.nuon keyed to that project. Two flags protect what the project has done with its copy across an update: a keep sub-path on a dir copy is stashed over the wipe and restored, the project's version winning – memory's lessons, safety's backups. An own file is seeded once and never overwritten again – hooks' protected.nuon. Everything else, harness install --update wipes and recopies clean. This is where almost every part lives, and it is the only scope most modules ever need.
Global, ~/.claude instead of a project's .claude/. Reached through harness globals or --global on a normal install – three spellings (--global, a cwd inside ~/.claude/, a --target on the home dir) all resolve through the one scopeFor function in src/runtime/scope.ts, so they can never disagree. A part declares where it belongs with global?: "core" | "optional" on its Part record:
global: "core"means the part only makes sense in~/.claude, full stop.projectParts()insrc/parts.tsfilters everycorepart out of the project picker, out of--parts all, and out of the project--listentirely – naming one there points you atharness globalsinstead of doing it.globalTierParts(tier)is the other half, what a tier's parts actually are.global: "optional"means the part works fine per project but has an optional global piece alongside it.
Two parts are core today, for two different reasons:
- limiter caps concurrent claude code sessions off one shared registry. A per-project copy would count only that project's own sessions, so the cap it exists to enforce would silently mean nothing – there is exactly one limiter, or the whole idea breaks.
- skill-smith is core-global for the opposite reason – not because the count needs to be shared, but because claude code resolves a project skill over a user one of the same name. A project copy would shadow the global one, so a fix to the global skill would never reach that project, and its banked corpus –
references/built/, the few-shot examples a build reads before drafting – would only ever feed builds in its own project and never accumulate across any of them.
Local Module
Harness-only development tooling, the third class beside a part and a banked module. A local module is a tool the harness runs on itself – vendor and modify (the skills that fetch and tweak the extern bank), the plugin-extractor and plugin-verifier agents they fan, strip-repo.nu, and scripts/context-window.nu. Per harness/CLAUDE.md amendment 33, a harness-only dev tool is a local module: it never gets a PARTS record, never installs into a project, and never browses as bankable.
It is declared in two places that say the same thing on purpose – the LOCAL array in installer/src/local.ts (the machine copy) and the table in harness/LOCAL.md (the readable one). harness local is the only view that can see them, and it is gated on the harness repo: the dashboard drops the row outright anywhere else and the command refuses, because a local module is machinery for developing this repo, not something to offer an unrelated project. Its install target is the harness repo root, not the cwd, so running it from a subdir like installer/ still lands in the one .claude/ that gets read.
Its store is ~/.claude/harness-local.nuon, deliberately its own file rather than a row in the shared registry. A local: row in the shared registry would resolve to no PARTS record and so read as an orphaned part in every view that walks the registry – installs, projects, stats, doctor, notices – so the isolation is by construction, one separate file, instead of a filter bolted onto seven views.
harness local # the browser, gated on the harness repo
harness local --install modify # non-interactive install
harness local --remove modify # non-interactive removeProfile
Not a scope on its own, but the fourth way a part lands – a named selection installed in one keypress instead of re-ticking the same rows into every new project. Press s in the install picker to save what is ticked, then harness profile to browse and install one straight into a new project. A profile stores the exact dests it was saved with, so an accordion subset round-trips exactly – save two of hooks' twenty files and that is what it installs – while a part taken whole is stamped whole, so it adopts files the part gains later rather than freezing today's file list.
Profiles carry provenance: a ProfilePart rides the same auto flag the registry does, so a part that came along as a resolved dependency in the project it was saved from installs auto again from the profile, rather than laundering into an explicit pick that a later remove would never offer back. They live in ~/.claude/harness-profiles.nuon, global and per machine, so a profile can seed a project that has nothing in it yet.
harness profile save cpp --parts cpp,natvis-writer,nushell --desc "the cpp lot"
harness profile mystack # install it straight into this projectThe Decision Rule
The payload of this page, in one line: if a module only makes sense once per machine, it is a core-global. If it is machinery for developing the harness itself, it is a local module. Otherwise, it is a part.
That first case splits again by why it only makes sense once. Ask whether a per-project copy would break a shared count (limiter's session cap) or split a corpus that only compounds when it is one (skill-smith's banked builds) – either answer means global: "core", not a project part with a note asking people to be careful.
Shadowing, a Real Failure Mode
A local copy of a core-global part does not just sit there unused – it actively wins. Claude code resolves a project skill over a user one of the same name, so a stale project copy of a global-only module answers every request in that project forever, and a fix landed on the global copy never arrives there.
This happened for real. Skill-smith went core-global on 2026-07-30, but nine project copies were already out there from before the tier changed, each one silently pinning its project to whatever version it was installed at. The picker already refused to hand out new project copies of a core-global part, but nothing reached back for the ones already placed – which is exactly the gap a coreGlobalNotices detector in src/models/notices.ts was added to close. It walks a project's registry row, and for every installed part now flagged global: "core" it raises a notice naming the shadow and offering to remove the local copy (or, if nothing is installed globally yet, telling you to run harness globals first so the project does not lose the module entirely rather than just losing the shadow). The nine stale skill-smith copies were swept on 2026-07-31 once the detector caught them.
Connects to
- Everything routes through the Installer –
harness install,harness globals, andharness localare three faces of the samerunInstall/runRemoveengine and the samehashPartcontent digest, so staleness reads the same way regardless of which store a part is tracked in. - Skill-smith is the worked core-global example – global-only since 2026-07-30, with the shadowing story and the swept project copies documented on its own page.
- Extern is where the local modules
vendorandmodifylive and work, fetching and tweaking the bank they never themselves get shipped as part of.