Appearance
Limiter
Limiter caps how many claude code sessions run at once, counted off one shared registry, so straying by proliferation – opening a fourth session for a tangent instead of finishing the first three – gets blocked at the container level instead of fought in the moment. It ships in two layers: an enforcement layer, four hooks that register every live session and gate the ones over the cap, and an integrity layer, a two-instance watchdog pair that keeps that enforcement wiring from being edited or removed on impulse. It's deliberately not unbeatable – the goal is friction that outlasts the impulse, not a lock nobody admin-side can pick.
It ships as a part but isn't currently installed anywhere on this machine; harness globals --list reports it not installed. Everything below describes what it does once it lands.
In Practice
A fourth session trips the cap. With global_cap at 3 and three sessions already live, starting a fourth still registers fine – SessionStart can't block anything – but limiter-eval catches the new session over the cap and prints a loud nudge naming what it's competing with:
session-limiter, this session breaks: global cap – over the global cap of 3, slots held by proj-a, proj-b, proj-c. the other live sessions are:
- project proj-a, started ~12m ago
- project proj-b, started ~4m ago
- project proj-c, started ~1m ago
the prompt gate will hold your turns until you stop breaking every rule. defer this work or close another session.The nudge alone changes nothing. The first prompt in that session hits limiter-prompt-gate.nu instead, which runs the same limiter-eval, finds the same violation, and exits 2:
session-limiter, blocked. this session breaks: global cap – over the global cap of 3, slots held by proj-a, proj-b, proj-c. its turns are held until it stops breaking every rule, close a session holding a slot or adjust limiter.nuon, then resubmit.Claude Code erases the prompt and shows that reason in its place, and every turn in the fourth session stays inert until a slot frees – the oldest three sessions keep theirs the whole time, only the newest arrival over the cap is ever gated.
Checking whether the tamper guard is actually up.
nu ~/.claude/limiter/pair.nu statuspair A: alive
pair B: alive
maintenance: noneAn example outcome. Close one of the other three sessions, or let it hit SessionEnd, and the next prompt in the fourth session goes through clean – reg-read prunes the closed session's record the moment anything reads the registry again.
Counting Sessions
Each live session is one JSON file, ~/.claude/limiter/live/<session_id>.json, never a single shared append file. Two sessions starting at once write different files, so nothing needs a lock, and nothing collides with the CRLF external-lock gremlin this repo already fights elsewhere. The live count is never stored, it's derived: every read walks the live/ directory, drops any record whose owning process is gone or older than a six-hour stale backstop, and deletes the file behind it, so a hard-killed session with no SessionEnd self-heals the moment anything reads the registry next.
The pid a record is keyed on isn't the hook process, it's the outermost claude.exe ancestor walked up from it, past whatever shell wrapper sits in between, and the walk deliberately stops at the nearest one. Climb one hop further on the desktop app and you'd reach the app's own top-level claude.exe, the process every session shares and that outlives them all – key on that instead and every session gets the same pid, none would ever free a slot, and the limiter would read as permanently over cap. The assumption baked in is the native claude.exe install; an npm/node launcher would name the session process node.exe instead and session-owner would need revisiting.
limiter-eval in registry.nu is the one place every rule is judged, shared by the SessionStart nudge and the UserPromptSubmit gate so the two can never disagree: a global cap ordered by start time (the oldest sessions up to the cap hold their slots, only a later arrival over the cap is gated), an opt-in per-project cap a project turns on with its own .claude/limiter.nuon, and an off-by-default one-project mode that blocks a new project's sessions while another project still has any live. Every rule fails open – a missing or unreadable limiter.nuon is itself a soft off switch, and any hook error falls straight through to allow, because a lockout of your own repo is a worse outcome than an uncapped one.
Global, Not Project
Limiter is one of only two parts in parts.ts marked global: "core", and its reason is the plainest one there is: it counts against a single shared registry, ~/.claude/limiter/live/. Install a copy into a project's own .claude/ and it would count only that project's own sessions against its own registry – the cap would still print, the hooks would still fire, and it would silently never trip, because a fourth, fifth, and sixth session opened in other projects would all be sitting in registries this copy can never see. A project install here isn't a lesser install, it's a broken one that only looks like it's working.
That's why the core tier is walled off from the normal picker rather than just discouraged. projectParts() filters every global: "core" part out before a project's harness install ever builds its menu, --parts all inherits the same filter, and a project's own --list never names it either. harness globals is the one door in – it lists the core tier against the global registry at ~/.claude/harness-installs.nuon and installs straight into ~/.claude/, never a project.
An update through that door is still careful about what it overwrites. The part's keep list spares every runtime path a fresh copy would otherwise wipe:
live/– the session registry the cap is counted off; wiping it would silently under-count whatever is actually running.limiter.nuon– the caps you've set.maintenance.nuonandmaintenance-pass.hash– the maintenance door's open/closed state and its password hash.bypass.log– the bypass / tamper log.pair.stop,pair-A.pid,pair-B.pid– the watchdog pair's own liveness markers.
Skill-smith is the second module marked global: "core", but for an entirely different reason – not a shared registry, a shadow. Claude Code resolves a project skill over a user skill of the same name, so a stale project copy of skill-smith would silently pin that project to a frozen version forever, with no way for a fix to the global one to ever reach it. See Skill-smith.
Maintenance Mode
Editing the limiter's own files while the watchdog pair is up would just get reverted on the next integrity tick, so there's a deliberate off-ramp: maintenance mode suspends the whole limiter, caps and watchdog both, for a window. Two doors open the same window, and both log every use to ~/.claude/limiter/bypass.log, which SessionStart reads back and prints at the top of the next session – a near-free confrontation lever, not a strong one, but cheap enough to ship anyway.
The watchdog pair stands down for the whole Open state, marked by dropping pair.stop, and comes back up the instant the window re-arms.
The password door is set once and reused:
nu ~/.claude/limiter/maintenance.nu set-password
nu ~/.claude/limiter/maintenance.nu start --minutes 30 --inactivity 5 --reason "edit hooks"maintenance open, up to 30m, re-arms after 5m quiet, reason: edit hooksThe window closes at whichever comes first: the absolute --minutes backstop, so a reboot mid-window still re-arms it, or --inactivity minutes with no session activity, and every message sent while it's open counts as activity and holds the door.
The gatekeeper door needs no password, just a stated reason:
nu ~/.claude/limiter/maintenance.nu request --reason "fix a null deref in the prompt gate"A fresh, insulated claude -p call on opus judges it, given the rubric, the request, and the requester's recent gatekeeper verdicts – never the asking session's own conversation, so the blocked session can't coach its own judge. Deny is the default: it approves a concrete, present, necessary edit to the limiter itself and denies a tangent, a quick tweak that can wait, or any request dressed up as maintenance that's really trying to raise the session cap. It's un-naggable by design – a repeat request with nothing new gets denied harder, not worn down – and any failure of the judge itself, no claude cli on PATH or one that isn't logged in, denies too. That's the same posture as the rest of maintenance: a broken maintenance file always reads as not suspended, so the limiter defaults to armed.
The Watchdog Pair
The integrity layer is two watchdog.ahk instances, roles A and B, each polling for the other every 500ms and relaunching it the instant it's gone. Killing one alone just loses the respawn race; killing both takes a genuine simultaneous hit inside the same 500ms window, the deliberate gap in the design. pair.nu is the manual controller (start, stop, status), but day to day nothing starts the pair by hand: SessionStart and every UserPromptSubmit call pair-ensure, a no-op once the pair is already up (one pid-file read against the process snapshot the hook already took) and a no-op while a maintenance window holds the pair.stop marker. The pair polls for the claude desktop app itself every 10 seconds and, once it's been gone past an idle limit (10 minutes by default) stamped to a clock shared on disk between both halves, retires together – shared on disk on purpose, since per-instance timers would let whichever half hadn't timed out yet keep reviving the one that had, and the pair would never die.
On a slower five-second cadence, deliberately slower than the liveness poll because this one touches files an editor may hold open, each half also checks that the limiter's own scripts still match what it loaded into memory when it started: watchdog.ahk itself, registry.nu, limiter.nuon, maintenance.nu, pair.nu, rewire.nu, and the four limiter-*.nu hooks. The canon lives only in memory, never on disk – a known-good hash sitting in a file would just be one more file to tamper with – so gutting every limiter file on disk at once still restores every one of them from what either half already holds. Files are read and rewritten as raw bytes so a restore is byte-exact, and a write goes through a temp file and a rename, so a file an editor is mid-save on is never left half-written, just retried on the next tick.
settings.json is the one exception, guarded as a block rather than a byte-exact snapshot, because it's shared with every other hook you run – restoring the whole file would revert edits that are none of the limiter's business. Each watchdog only checks that its four hook files are still named somewhere in it, and when one isn't, it shells out to rewire.nu, which parses the json and appends back only the missing entries, leaving everything else exactly as found.
Key Files
The four hooks land loose in ~/.claude/hooks/, each pulling in ../limiter/registry.nu as a relative sibling import, so hooks/ and limiter/ have to stay next to each other exactly as they do under ~/.claude/. The lib, config, and runtime state live in ~/.claude/limiter/, and one settings fragment carries the wiring.
Hooks
limiter-sessionstart.nu
The register and soft nudge – a SessionStart hook. Adds this session to the live registry, brings the watchdog pair up if it's down, prints the recent bypass-log summary, and prints a loud over-cap nudge if this session already breaks a rule. Never blocks – SessionStart can't.
limiter-prompt-gate.nu
The hard block – a UserPromptSubmit hook. Bumps this session's heartbeat, runs the same limiter-eval the SessionStart nudge used, and exits 2 when this session is the newest one over a rule – the closest a hook can get to ending the chat, since no hook actually can, so it just holds every turn until a slot frees.
limiter-stop.nu
The heartbeat – a Stop hook. Bumps last_seen on this session's own record so a long but idle session stays fresh against the stale backstop, and lets ongoing turn activity extend an open maintenance window.
limiter-sessionend.nu
Best-effort cleanup – a SessionEnd hook. Removes this session's record on a clean exit. SessionEnd is unreliable – a killed terminal, a crash, or sleep all skip it – so the real source of truth is the live-pid prune in reg-read, not this hook.
The Library
registry.nu
The shared library – every hook loads it with use ../limiter/registry.nu *. Holds the live-session registry (reg-add / reg-read / reg-touch / reg-remove), the process-owner walk (session-owner), the shared rule evaluator (limiter-eval), the maintenance state machine, the gatekeeper judge, and the settings.json restore logic the watchdog shells out to.
limiter.nuon
The global config – global_cap, project_cap, one_project_mode, and the two watchdog cadences, liveness_ms and integrity_ms. Missing or broken means no cap is enforced at all; deleting it is itself a soft off switch.
Maintenance and Integrity
maintenance.nu
The maintenance CLI – set-password, start, request, and status, the two doors and the status readout, run by hand: nu ~/.claude/limiter/maintenance.nu <subcommand>.
pair.nu
The pair controller – start, stop, and status for the watchdog pair. Rarely touched day to day, since the hooks already bring the pair up and down themselves through pair-ensure.
rewire.nu
The settings.json restorer – parses settings.json and merges back only the limiter's own missing hook entries, leaving everything else untouched. The watchdog shells out to it because AutoHotkey can't parse json.
watchdog.ahk
The tamper guard itself – one half of the mutual-respawn pair, launched as role A or B. Loads the guarded files into memory at start, restores them byte-exact off the slow integrity cadence, and retires once the claude desktop app has been gone past its idle limit.
Wiring
settings-fragment.json
The hook block to merge – the four entries appended by hand into ~/.claude/settings.json, never a project install (this part touches no project). Paths ship relative and match the part's dests exactly, which is what lets harness hooks see them as installed; harness install --global absolutises them against the home dir on the way in, since a relative path left in a global settings.json would otherwise resolve against whatever project you happened to be sitting in.
Connects to
- Installer – installed only through
harness globals, the one entry point for anything markedglobal: "core"; a project's ownharness install, including--parts all, filters it out before the picker is even built. - Skill-smith – the only other
global: "core"part, walled off for shadowing rather than a shared registry: a stale project copy of a skill would silently outrank the global one of the same name. - Hooks – shares the pack's recursion guard; every limiter hook checks
HARNESS_HOOKS_OFFfirst so a childclaude -pcall, the gatekeeper judge included, never registers as a session of its own. Its four hooks land loose beside the pack's rather than inside its ownobservers//gates/split.