Skip to content

Archiver ​

Archiver is the automatic half of the archiving rule written into the global CLAUDE.md, and it now has three faces instead of one. The oldest and busiest is the stamp: a PreToolUse hook copies the pre-edit version of any file into <root>/archive/ before an Edit, Write, MultiEdit, or NotebookEdit lands, so the version about to be overwritten is kept without anyone remembering to keep it. Archive-by-default is the whole design bet, every file is stamped unless a deny glob names it as obvious junk, so nobody ever judges what is worth keeping, only what plainly is not. The other two faces arrived together on 2026-08-23: retire moves a file you are finished with, rather than one that changed, into a mirrored " retired" corner as one undated copy, and the cleanup sweep gives the archive an actual retention policy instead of growing forever, off by default so an unconfigured project stays exactly as append-only as it always was.

In Practice ​

Every stamp decision runs through one guard chain inside stamp, in archive.nu, so the hook, /archive, and careful's merge can never disagree about the same file. This assumes the archiver is enabled and the target already exists, a brand-new file has nothing yet to keep:

The hook stamps without being asked. Edit harness/PLAN.md and archive-write.nu fires on PreToolUse before the edit lands, no command, no tool call the agent even notices. This repo's own harness/archive/ holds the evidence: PLAN-2026-07-28_1616.md, PLAN-2026-08-18_0330.md, PLAN-2026-08-25_0240.md, and more, one stamp per session that touched the file rather than one per edit inside a session, because .claude/archiver/sessions/<session id>.nuon marks a path as done for the rest of that session. Because the source path starts with harness/, dest-parts roots it at harness/archive/ mirrored from the harness root instead of the repo-root archive/, keeping the self-contained module's own history with the module.

Force it past a denial. harness/installer/package-lock.json matches the deny glob **/package-lock.json, so the hook never touches it. /archive harness/installer/package-lock.json runs archive.nu stamp harness/installer/package-lock.json --force, and --force is the only thing that lifts the deny check, plus the once-per-session dedup alongside it. Content dedup is the one guard --force cannot lift, stamping the identical file a second time still gets skipped.

Ask why nothing landed. Before forcing it, /archive why harness/installer/package-lock.json runs the same guard chain under --dry, writes nothing, and names the exact glob that stopped it:

archiver, harness/installer/package-lock.json
  verdict  denied by **/package-lock.json
  path     harness/installer/package-lock.json
  held     0 stamp(s) already archived for this path

This is the whole point of why: the hook never blocks and never speaks, so from the outside a skipped stamp reads exactly like a taken one. Set HARNESS_ARCHIVE_LOG to anything non-empty and every decision the hook makes, taken or skipped, lands as one line in .claude/archiver/hook.log too, off by default so the hook still costs nothing to run.

Retire something you're finished with. /archive retire steal resolves steal against the project tree, exact path first, then basename, then stem, then a plain substring, and if exactly one thing matches it moves whole into the mirrored " retired" folder under whichever archive root that path already self-contains to. It prints retired <from> -> <to> on success, a reminder that the retired folder name starts with a space, or, if two things matched, the full list of candidates with an instruction to name the one meant, it never guesses between them. A second retire of the same source refuses outright with already retired, there is only ever one copy rather than overwriting.

Sweep it clean, eventually. Set cleanup.nuon's mode to copies, days, or distil through harness config --part archiver and a SessionStart tick sweeps the archive at most once every sweep.every_hours. This repo's own .claude/archiver/cleanup.nuon still sits at mode: "off", so nothing here has ever been swept, only stamped or retired, exactly the append-only behavior the module always had before the sweep existed. A swept stamp is not deleted, it moves to <archive_root>/.bin/ and only really goes after bin.keep_days, nu archive.nu unsweep <name> pulls one back out while it is still there.

Prune reports, never deletes. /archive prune walks every stamped file, groups it back to the source it came from, and flags three things without touching any of them: a source with more stamps than prune.keep_last (piling up, the oldest could be thinned), an orphan whose source file is genuinely gone, and a source marked retired because it was moved to the retired folder on purpose. Only the first two are worth a look, retired is a fact about a file finn already dealt with, not a problem, harness archive is the same report from the manager's own CLI.

An example outcome. The version about to be overwritten is never lost to a slip of memory, the hook takes it before every edit lands, and the one place you'd otherwise wonder whether it happened, /archive why answers directly instead of making you guess.

Standing Down for Careful ​

While a careful sandbox is armed the real tree is frozen and nothing on disk is actually changing yet, the edit landed in the run's staged copy, not the real file. careful-armed in archive.nu checks careful.nuon's enabled flag and an active, non-bypassed run before every stamp, and if one is armed the archiver stands down with the reason careful armed, stamping at merge. There is nothing to keep there.

The stamp still happens, just deferred. Careful's own sandbox.nu takes it at /careful merge, calling archive.nu stamp --at-merge --force for every staged file right before it copies the staged version back over the real one. --at-merge lifts the standdown guard, this is the deferred stamp the guard promised, and --force rides along too, so the merge-time stamp bypasses the deny list and the session dedup the same way a manual /archive does, only identical content still gets skipped. backups/ under .claude/careful/ and archive/ stay deliberately separate: backups/ is careful's own transactional undo, every file including denied junk, so a bad merge fully reverses, archive/ is the deny-filtered, deduped history trail. Folding one into the other would lose one of those two contracts.

Retire, the Other Half ​

A stamp answers "keep the version before this edit", many copies, the date is the whole name. retire answers a different question, "this file is finished with, get it out of the tree but do not lose it", one copy, no date, and the two never mix: stamp-rows and stamp-groups explicitly skip the retired folder so nothing that walks the archive to count, flag, or thin stamps can see inside it.

retire-dest reuses dest-parts, so a file under harness/ retires to harness/archive/" retired"/... the same way its stamps self-contain, and everything else retires under the configured archive_root at the project root. resolve-retire takes whatever finn typed and tries it in tiers, an exact path wins outright with no search at all, then a basename match, then a stem match, then a plain substring, never a regex, so a stray . or * in what was typed cannot silently widen the match. One hit is the answer; several is a question printed back, retire never picks for finn. The search itself skips .git, node_modules, build output dirs, and the archive and retired folders themselves, an archive is where retired things go, never a thing to retire.

retire does not read enabled, a retire is a hand-run move rather than part of the automatic stamping that switch governs, so it works even with the archiver asleep. It refuses a collision outright rather than overwriting, one copy is the single guarantee this feature makes, and a silent overwrite would turn that into a maybe. unretire works the mirror image, walking both retired trees (repo-root and harness-self-contained), matching the same way, and refusing if something is already sitting at the return path.

The retired folder name starts with a literal space, " retired", and that is deliberate, not a typo. It sorts above every mirrored directory (0x20 beats every letter) while rendering as near nothing. The cost: every path through it has to be quoted, a bare one pasted into a shell splits into two arguments, and any trim on a path segment silently eats the space and resolves one directory up instead of erroring. The constant is never to be "tidied."

The Cleanup Sweep ​

The archive used to grow forever, every stamp additive and nothing ever thinning it. The sweep gives it exactly one active mode at a time, off, copies, days, or distil, configured in cleanup.nuon, a file kept deliberately separate from archive.nuon: harness config rewrites its target whole on every save and would otherwise eat the hand-authored deny and context lists. off is the default, unrecognised text in mode also reads as off rather than guessing, so a typo in a hand-edited file sleeps the sweep instead of running the wrong rule over an archive.

  • copies keeps the newest copies.keep stamps of each source and sweeps the rest, clamped to at least 1, a rule can never wipe a source outright.
  • days sweeps any stamp older than days.keep_days.
  • distil keeps everything inside distil.daily_days untouched, then one stamp per anchor bucket (distil.anchors, weekday names like wed/sat) for distil.biweekly_weeks, then one stamp per calendar week for distil.weekly_weeks, then nothing survives past that. biweekly means twice a week here, not fortnightly, the buckets are anchored to two weekdays, not to a two-week span.

Age for every mode is read off stamp-date, the date encoded in the stamp's own filename, never file mtime, because a copy, move, or git restore rewrites mtime but never the name. The tick lives in archive-sweep.nu, a SessionStart hook that reads a sweep.nuon { last: <iso> } clock and runs at most once per sweep.every_hours; a long session that never restarts simply skips a day's sweep, harmlessly, and nu archive.nu clean is the manual escape hatch if the tick never fires.

Nothing is unlinked on the spot. A swept stamp moves to <archive_root>/.bin/, with one line appended to .bin/swept.jsonl before the move, not after, so a crash between the two leaves a recoverable file rather than a lost one. That bin only really empties once an entry's own recorded sweep date is older than bin.keep_days, the single real delete in the whole module, and it is always exactly a month (or whatever bin.keep_days is set to) behind the decision that caused it. nu archive.nu unsweep <name> pulls one binned stamp back out while it still exists, taking a partial name the same way retire does.

Key Files ​

archive.nu ​

The engine – the whole API: stamp, why, status, prune, retire, unretire, sweep, and unsweep, plus the private helpers every caller shares. Every stamp decision, the hook, /archive, careful's merge, runs through the same stamp function, so there is exactly one guard chain to reason about. dest-parts is what makes harness self-contained, and both retire-dest and archive-roots reuse it so stamps and retired copies land under the same tree. stamp-groups is the pruner's raw material, and it is also where the module decides a gone source is retired rather than orphaned, by checking whether a retired copy exists before ever calling it lost. free-dest walks a letter suffix when two different stamps would land in the same minute, the clock only carries minute precision.

archive-write.nu ​

The stamp hook – PreToolUse on Edit|Write|MultiEdit|NotebookEdit, forced onto that event rather than PostToolUse because the pre-edit content is the entire point, a moment later it would already be gone. It pulls tool_input.file_path (or notebook_path for NotebookEdit) and the session id out of the hook JSON, hands both to stamp, and throws the verdict away. It never blocks and fails open, any error at all degrades to exit 0, a broken archiver must never brick a write. It reads stdin natively with nu --stdin rather than shelling out to cat, so it works without git bash on the bare Windows PATH.

archive-sweep.nu ​

The cleanup tick – SessionStart, not PreToolUse, because the stamp hook is the hot path on every single edit and a walk of the whole archive has no business slowing that down. It reads sweep.nuon's last timestamp, does nothing at all if the last sweep was inside sweep.every_hours, and is quiet even when it runs, printing a line only when something actually moved, so an unused feature leaves no trace and a used one doesn't train you to stop reading its output. It checks cleanup.mode before ever touching the clock file, so a project that never configured a sweep never even writes one.

Config ​

archive.nuon ​

The denylist – project owned, seeded once, never reset by an --update, so it stays tunable for the life of the project.

KeyMeaning
enabledThe master switch. false sleeps the archiver entirely, the hook, /archive, and careful's merge stamp all read this
archive_rootProject relative dir the stamps mirror under, archive by default
denyGlobs never archived, project relative or ~ / drive rooted to reach outside the project. Archive by default and only these stop it
contextGlobs that land flat in <archive_root>/context/ with just their dated name instead of mirroring their path, the global CLAUDE.md's context-file exception, ROLE.md, PROJECT.md, STYLE.md, TASK*.md, HANDOFF*.md
prune.keep_lastHow many stamps of one source before prune flags it as piling up. Read as the threshold whenever the sweep's mode is anything other than copies (off, days, or distil), since only copies mode has its own copies.keep number for prune to describe instead

cleanup.nuon ​

The sweep's own config – owned by harness config --part archiver, which rewrites this record whole on every save, so nothing hand-authored can live here, that stays in archive.nuon.

KeyMeaning
modeoff / copies / days / distil, exactly one runs, an unrecognised value reads as off
copies.keepCopies mode only, how many newest stamps per source survive, clamped to at least 1
days.keep_daysDays mode only, sweep anything older than this many days
distil.daily_days, distil.biweekly_weeks, distil.weekly_weeks, distil.anchorsDistil mode only, the three tiers and the anchor weekdays, biweekly means twice a week
bin.keep_daysHow long a swept stamp sits in .bin/ before it is actually deleted, the module's one real delete
sweep.every_hoursThe SessionStart tick, at most one sweep per this many hours

config.json ​

The settings form – eight fields feeding harness config --part archiver, one per cleanup.nuon key, each with its own description and unit (days, weeks, hours). This is the only sanctioned way to change cleanup.nuon, hand-editing it works too but a form save overwrites whatever was there.

Command and Wiring ​

archive.md ​

The /archive command – installed to .claude/commands/archive.md. A bare /archive runs status. A path runs stamp <path> --force. prune, why <path>, retire <X>, and unretire <X> each route to their matching verb. The doc carries hard rules for the agent driving it: never retire anything unprompted, several matches is a question for finn and never a guess, and an "already retired" refusal is not something to work around by deleting or renaming the existing copy. A second rule landed on 2026-09-10 to close the gap the first one left open, which was that it said stop and ask without ever saying how to ask. Something that only implies a retire, a consumed handoff whose own text says archive it once done, a plan just closed, a doc that has plainly finished, is still not finn naming a file, so the never-unprompted rule holds; but it now goes to him as an AskUserQuestion prompt rather than a line of prose. The reasoning is the same one that shapes every reply in this repo: finn skims, so a question sitting under a summary reads as sent when it was never seen, and the retire ask that prompted this rule cost a full round trip and a Stop-hook nudge before he reached it.

settings-fragment.json ​

The wiring – one PreToolUse entry matching Edit|Write|MultiEdit|NotebookEdit running nu --stdin ".claude/archiver/archive-write.nu", and one SessionStart entry running nu ".claude/archiver/archive-sweep.nu". harness settings --merge finds and wires both into a project's settings.json.

The Blind Spot ​

The hook only ever sees Edit, Write, MultiEdit, and NotebookEdit. A rm or a mv issued through Bash never touches those tools, so it never reaches archive-write.nu, and a file deleted or moved that way leaves no stamp behind at all: the deny list and the content dedup never even get a turn to run. This is the same shape gap every PreToolUse hook keyed to a tool matcher carries, not a bug unique to archiver: a hook can only see what Claude Code routes to the tools it matches, and Bash sits outside that net by construction.

It is a half guarded blind spot, not an unguarded one, and the two halves split on permission mode. This repo's own .claude/settings.json carries a permissions.ask list naming the destructive bash verbs, Bash(rm -r*), Bash(git reset --hard *), Bash(git push --force *), Bash(dd *), twenty-three bash rules in total, plus two PowerShell rules for Remove-Item and Clear-Content. In Claude Code's default auto permission mode those rules do fire and put a prompt in front of the destructive command before it runs, so a Bash-issued rm -rf gets a human in the loop even though the archiver itself never sees it. Measured 2026-08-26: a Bash(rm -r*) ask rule asked as expected under auto. Only rm was ever tested against this claim – the other twenty-two bash rules and both PowerShell rules are assumed to behave the same way, not measured.

Two gaps sit underneath that guard, and neither the archiver nor the permission system covers them. Under bypassPermissions mode a permissions.ask rule does not fire at all: the same 2026-08-26 measurement showed rm -rf just running, no prompt and nothing stamped. And a destructive command wrapped inside an interpreter, nu -c "rm -rf ...", node -e "...", never matches a Bash(rm ...) glob to begin with, in any permission mode, because the rule matches the literal Bash command string and the interpreter call is a different string entirely. So the honest framing is guarded in auto, unguarded in bypassPermissions, and never stamped either way: the archiver's own coverage stops at the four edit tools regardless of which permission mode is asking on its behalf.

Connects to ​

  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/archiver/USAGE.md – that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module.
  • Careful – careful-armed stands the hook down while a sandbox run is active, and careful's own merge takes the deferred stamp with stamp --at-merge --force, keeping backups/ (the transactional undo) and archive/ (the filtered history) as two separate contracts.
  • Registers its own PreToolUse and SessionStart entries alongside the hooks pack, sharing the same HARNESS_HOOKS_OFF recursion guard so a harness-spawned Claude instance never re-fires either one.
  • Placed by the installer with harness install --parts archiver, weight light, keeping archive.nuon, cleanup.nuon, sessions/, and sweep.nuon across an --update. harness archive is the manager's own CLI skin over the same archive.nu verbs /archive drives, shelling prune, why, retire, unretire, and clean rather than reimplementing any of them, so the two can never diverge. --clean always runs the dry plan first and waits on a confirm before a real sweep, --yes skips the confirm and --dry stops after the plan.
  • harness config --part archiver is the only sanctioned way to change cleanup.nuon, reading its eight fields from config.json.
  • Replaces the hand-run half of the archiving rule in the global CLAUDE.md, an agent no longer has to remember to copy a file into archive/ before changing it, the hook does it whether anyone remembers or not.