Appearance
Project Router
Project router lets one physical .claude/ in a parent project serve many sub-projects at once. Every claude code session runs from the parent – which is what keeps them grouped together in the desktop app – but each session only wants the modules for the sub-project it's actually working on. So the router picks an active sub-project at SessionStart, advertises that sub-project's skills, workflows, and MCPs, and multiplexes its hooks, all off one shared install. You switch focus mid-session with /use, or let three auto-focus signals settle it for you.
It installs into the parent project's .claude/ like any normal part, and wires only that project's settings.json – no other project's sessions run any of it. The engine self-resolves the project it's running in, so once it's installed it costs nothing until a .claude/subprojects.nuon is authored – it just no-ops.
In Practice
A session opens and the router asks which sub-project. When the active sub-project isn't set yet, the SessionStart injector lists the sub-projects from the manifest and hands the choice to the model:
sub-project router, active sub-project not set. ask finn which to focus, via AskUserQuestion, one option per sub-project plus a base-only option:
engine the 2d engine core
editor the engine editor
on the pick, run /use <name> (or /use _base for base only)The model asks with AskUserQuestion, you pick, and it runs /use engine. A session that never picks just runs the _base tier, no error.
Once focused, the session is told what's in scope. The injector advertises the union of _base and the active sub-project, and names why the focus landed where it did:
sub-project router, active sub-project: engine (the 2d engine core)
you set this with /use
in scope this session:
skills natvis-writer
other modules are installed but out of scope, invoke one by hand with /name if you need itEvery routed skill ships disable-model-invocation, so nothing out of scope auto-fires – but you can still reach any of them by name.
Switching focus mid-session. /use editor re-points this session; the next hook fire reads the new focus with no restart. /use _base drops back to base-only, and forgets the sticky memory too, so the next session doesn't quietly re-open on what you just stepped out of. MCPs advertise only – they connected at launch and don't reconnect on a switch.
A path match settles a session without asking. With _router.auto including "path", the first tool call carrying a file_path under a sub-project's paths globs focuses that sub-project – editing something under engine/** locks the session onto engine before you ever touch /use. Because SessionStart already advertised the (previously unset) skills, the in-scope block is re-sent on the next prompt rather than instantly, one turn late by construction.
Installing a sub-project's parts. --subproject <name> on harness install copies the picked parts the normal way, then writes or merges a manifest entry that references them:
harness install --subproject engine --parts find-todos --yesdone, 4 items into ...\.claude
+ sub-project 'engine' in .claude/subprojects.nuon, 1 part, 1 skillAn example outcome. A part shared by two sub-projects installs once – the to-collision guarantee means the second --subproject install references the same files instead of duplicating them, and both manifest entries point at the one copy.
Scoping a Stop or PreCompact hook to one slice. A manifest entry can name hooks.Stop or hooks.PreCompact and have it actually fire, now that the dispatcher is wired for both events:
"engine": { "hooks": { "Stop": ["subprojects/engine/hooks/wrap-up.nu"] } }harness validate --target <dir> checks the event name against the dispatcher's own wired set before it lets that entry through.
The Session Key
The whole design hangs on one identity: which session is this. Both actors that touch the pointer can name it directly. A hook reads session_id off its payload, and the /use command – which runs as a model action with no payload – reads the same value from $CLAUDE_CODE_SESSION_ID, which Claude Code exports into the tool-call environment. So the pointer is keyed by session_id straight, one file per session under the parent's .claude/harness-active/.
Two sessions from the same parent keep independent pointers, so a /use in one never moves the other. The session id is unique and stable, so there's no pid-reuse hole to plug and nothing platform-specific. The design first leaned on a nearest-claude.exe pid walk to bridge the command path, but the env var made that dead code, and dropping it took the whole module off its Windows-only footing.
Auto-focus
Session start used to mean a picker every time. Auto-focus (opt-in via the manifest's reserved _router key) lets three signals settle a session instead, so the picker only fires when the answer is genuinely unknown. active.nu's focus subcommand is the one writer every signal goes through, so the precedence lives in one function rather than three matchers that have to agree with each other. No _router key at all means all three are off and the router behaves exactly as it did before – you pick once per session and nothing else ever writes the pointer.
| signal | fires on | locks | source in code |
|---|---|---|---|
/use <name> | you, any time | yes | active.nu main set, always --by "use" |
| phrase | a prompt containing an authored key-phrase | yes | dispatch.nu match-phrase, on UserPromptSubmit |
| path | the first touched file under a sub's paths | yes | dispatch.nu match-path, on PreToolUse |
| sticky | session start | no | active.nu main seed-hook, off last.nuon |
| unset | nothing matched | n/a | _base only, plus the turn-1 picker |
The ladder climbs once per session: the first real signal locks the pointer, and every source but use and sticky refuses to write over an already-locked one (focus just prints that the match was ignored). Sticky is the one exception on purpose – it seeds a remembered default, not a decision, so a path or phrase signal is still free to correct it, and that correction is itself the first real signal, so it locks in turn.
Path matching (match-path) reads tool_input.file_path (or notebook_path) off the payload, makes it project-relative, and scores every sub-project's paths globs against it. Only ** and * are supported, hand-built into a regex rather than leaning on Nushell's filesystem-walking glob, because the file in a payload may not exist yet – a Write creating a new file is the obvious case. The longest matching pattern wins ties on specificity (engine/render/** beats engine/**), and a genuine tie between two sub-projects changes nothing – the picker and /use are still there, and guessing wrong is worse than asking.
Phrase matching (match-phrase) is deliberately dumb: an authored phrases entry has to appear as an exact, case-insensitive substring of the prompt. Never stemmed, never split into words, never derived – a match means you wrote that phrase into that entry yourself. Two sub-projects both matching one prompt is reported and changes nothing, the same "don't guess" rule as a path tie.
Every pointer records set_by, and the injector's why-focused turns it into a one-line reason ("you set this with /use", "remembered, its what you last used in this project", "auto, off the first file this session touched", "auto, off a key-phrase in your prompt") printed right under the in-scope block. An auto-focus you can't see the reason for is a bug even when it picked right.
The Manifest
.claude/subprojects.nuon is the routing table, one entry per sub-project plus a reserved _base, and the reserved _router key for auto-focus settings. It's JSON inside a .nuon extension, so JSON.parse reads it fast.
json
{
"_router": { "sticky": true, "auto": ["path", "phrase"] },
"_base": { "desc": "active for every sub-project", "parts": ["memory"], "hooks": {}, "skills": [], "workflows": [], "mcps": [] },
"engine": {
"desc": "the 2d engine core",
"parts": ["cpp"],
"hooks": { "PreToolUse": ["subprojects/engine/hooks/guard.nu"] },
"skills": ["natvis-writer"],
"workflows": [],
"mcps": [],
"paths": ["engine/**", "src/core/**"],
"phrases": ["the engine core"]
}
}Each entry carries three kinds of field. parts is install-time provenance – what the installer placed, and what a dropped part gives its manifest claim up from too (harness subprojects heals a manifest that drifted before that held, naming which claims it removed). The hooks / skills / workflows / mcps lists are the runtime routing lists the engine reads hot, kept pre-expanded so the dispatcher never has to expand a part on every fire. paths and phrases feed auto-focus only, and a sub-project can carry no parts of its own at all – confirming the picker with nothing ticked writes an empty entry, and that slice then rides the project-global set plus _base, which is all it needs when what makes it a slice is its own paths, its own hooks, and its own name.
A hook entry is either a path string or a { matcher, script } record; the dispatcher checks payload.tool_name against the matcher before running it. The effective surface for a focused session is always _base union the active sub-project, resolved that way everywhere – the dispatcher runs _base's hooks before the sub-project's, and the injector lists both. An unset session resolves to _base only, which is why the base tier is also the sensible default floor.
harness install --subproject engine --parts cpp,natvis-writer writes this file, deriving the skills and workflows lists off the picks' to paths (MCPs, per-event hooks, paths, and phrases are left for hand-authoring). The file is authored, never shipped by a part copy, so an update never touches it – but the installer does declare the path itself, as a creates entry with mode prompt, so the module's own claim covers it for cleanup purposes even though nothing ever copies over it.
An event name in a hooks list has to be one the dispatcher is actually wired for. dispatch.nu takes the event as a free-form argument and will resolve hooks.<anything> out of the manifest against it, but it only ever runs on the events its own settings-fragment.json registers it against – a hooks.Stop or hooks.PreCompact entry means nothing if nothing ever calls dispatch.nu Stop. That fragment now wires nine events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SessionEnd, Stop, SubagentStop, PreCompact, and Notification. It used to wire only the first five, so a Stop or PreCompact entry in a manifest was silently dead – exactly the events that planning, limiter, wiki, context, and handoff hook, which made scoping any of them to one slice impossible. harness validate --target <dir> now reads the wired set straight off that shipped fragment and fails a manifest naming anything outside it, where it used to accept any event name silently.
An already-installed project needs harness --update to pick the four new events up. harness hooks will NOT tell you it is behind – it decides wired on the script path with no event in the compare, and dispatch.nu is one path under nine events, so all nine read as wired whichever ones settings actually holds.
Per-project, Not Global
An early version shipped as a global: "core" part, walled off from the normal picker like limiter. That was a mistake, and why it was a mistake is instructive. Limiter must be global – it counts every session on the machine against one registry, so a per-project copy would miss the sessions in other projects. The router shares nothing across projects: it only ever routes one parent's sub-projects, and a session's focus means nothing outside that parent. There is no shared store to justify going global.
So it installs like any normal part, into the parent's .claude/, and wires only that parent's settings.json. Nothing lands in ~/.claude, and no unrelated project's sessions run the dispatcher, carry the /use command, or fire the injector – a project that never installs it is untouched. The pointer store is the parent's own .claude/harness-active/, session-keyed, so concurrent sessions on the same parent don't collide and different parents isolate by their separate .claude/ dirs. A global install would have been namespace pollution – the command and hooks present in every session everywhere, no-op or not – which is exactly the tell that this belongs per-project.
Key Files
The engine lands under the parent's .claude/modules/project-router/, the /use command in .claude/commands/, and one settings fragment carries the wiring into the parent's settings.json. The subprojects.nuon manifest and any private sub-hooks are authored into the same parent, not shipped.
active.nu
The session helper – resolves the session key and reads or writes the active pointer. seed-hook seeds it off the payload at SessionStart (and seeds from last.nuon unlocked when _router.sticky is on, falling back blank if the remembered name has since left the manifest), clear-hook drops it at SessionEnd, focus is the one writer every signal calls, set is what /use calls (focus --by use), and get is the read. key prints the session id from $CLAUDE_CODE_SESSION_ID, state dumps the whole pointer as JSON, and sweep --days <n> reaps pointer files older than n days, skipping last.nuon by name so an idle week never forgets the sticky memory.
dispatch.nu
The multiplexer – wired once per event as nu --stdin dispatch.nu <Event>, now against all nine events its settings-fragment.json registers. It self-resolves the project, runs the auto-focus check (match-path on PreToolUse, match-phrase on UserPromptSubmit, only when the pointer isn't already locked), then resolves _base union the active sub-project for that event and runs each sub-hook in order, forwarding the payload. Matcher-gated, and an exit-2 from any gate short-circuits the whole dispatch into a block. It re-invokes inject-scope.nu on the next UserPromptSubmit after an auto-match, since the match itself lands after SessionStart already advertised the prior scope.
inject-scope.nu
The advertiser and picker – a SessionStart observer. For a focused session it prints the in-scope skills, workflows, and MCPs plus the why-focused reason for the pointer's set_by; for an unset one it injects the turn-1 picker prompt. Pure naming of already-installed modules, so it has no skill-discovery timing dependency.
use.md
The /use command – validates the name against the manifest, runs active.nu set, then re-advertises the new in-scope set. disable-model-invocation, so it fires structurally as a slash command on the desktop app. It's the top of the focus ladder: it always wins, always locks, and it's the only source that ever updates the sticky memory (/use none clears that memory too).
settings-fragment.json
The hook block – SessionStart wires the seed, the injector, and the dispatcher (seed first, so the pointer exists before the others read it); PreToolUse, PostToolUse, and UserPromptSubmit wire the dispatcher; SessionEnd wires the clear then the dispatcher; and Stop, SubagentStop, PreCompact, and Notification each wire the dispatcher alone. Paths ship relative and merge into the parent's settings.json, resolving against the project at runtime.
subprojects.nuon
The per-project manifest – authored into each parent project, one entry per sub-project plus _base and the reserved _router settings block. Written and merged by harness install --subproject, and hand-editable for the fields the derive can't own (MCPs, per-event hooks, paths, phrases). Declared to the installer as a creates entry rather than a copies dest, which matters for cleanup – see the gotcha below.
Known Limitations
harness doctor and harness hooks can't see router-dispatched hooks at all. Both build their intended set purely off shipped settings fragments and never read a project's subprojects.nuon, so a slice's own hooks.<Event> entries are invisible to either one – not reported as wired, not reported as unwired, just absent from the picture. harness validate --target <dir> is the one command that actually reads the manifest and checks its event names.
Removing project-router is unguarded. Nothing stops you uninstalling the module while subprojects.nuon and its claims stay on disk – the manifest survives with nothing left to dispatch it, and the sub-project install chooser still triggers off the manifest simply existing (hasManifest just checks the file is there), so the next harness install on that project can still open into the sub-project chooser for a router that's no longer wired.
Gotchas
harness clean used to flag subprojects.nuon as an orphan on every run. The module declares that path as a creates entry with mode prompt, but clean's claimed-paths set used to build off copies dests only and never read creates at all, so every project using --subproject was offered its own manifest for deletion on every single clean pass. Fixed by reading creates into the claimed set too – if you saw this before, it's why, and the manifest was never actually orphaned.
Connects to
- Installer – a normal
harness installinto the parent project.harness install --subproject <name>and the picker's r key author a project's manifest entry, deriving the runtime lists off the picks and leaning on theto-collision guarantee for install-once dedup.harness subprojectsbrowses the manifest and heals it when a claimed part has since been renamed or dropped.harness validate --target <dir>checks everyhooks.<Event>entry against the dispatcher's wired set. - Limiter – the global-core counterpart, and the contrast that put this one per-project: limiter counts every session on the machine off one registry so it must be global, exactly the cross-project sharing the router never has.
- Hooks – the dispatcher and its sub-hooks honour the pack's
HARNESS_HOOKS_OFFrecursion guard, and read their payloads the samenu --stdinway the pack's own hooks do. Planning, limiter, wiki, context, and handoff are the shipping parts that hookStoporPreCompact– the events the router only started dispatching this session, which is what makes scoping any of them to one sub-project possible now. - The condensed, end-user version of this page is the module's own
USAGE.md, atharness/modules/project-router/USAGE.md– that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module.