Repository navigation
v0.34.0
claudewheel rewritten in Go: one binary installed with go install or from the release archives, a workspace converted once with upgrade-workspace, segments preset with -s, patch-profiles with an explicit --profile or --all-profiles, and the probe runner run by probe run-service. The Python and npm packages are no longer published; PyPI and npm keep 0.33.0.
Context
The stricttools projects are moving to Go; the Python and npm releases stop at 0.33.0.
Breaking
- Claude Code is no longer memory-capped; a session's Bash commands share a 6G cap instead. Each launched session runs in its own slice: Claude Code in an uncapped scope, and every Bash command, with everything it starts, in a scope of its own inside the session's tools slice, capped together at
tool_memory_max(6G) andtool_memory_swap_max(1G) fromconfig.json. A runaway command is killed while the session goes on, and the command's output ends with a line naming what was killed and the cap. The commands reach the slice throughCLAUDE_CODE_SHELL_PREFIX, pointed at the newclaudewheel-tool-scopescript, which a launch deploys when it is missing; hooks, the status line, and MCP servers run outside the cap.session_memory_maxandsession_memory_swap_maxare removed fromconfig.jsonand not carried over. Probe reports, probe commands, andheavyattribute a Bash command's scope to its session. Sessions already running keep the scope they were launched with. - The command names itself
claudewheel. Help headers,--helpfooters, parse errors, and--versionnow printclaudewheelinstead ofc(claudewheel --versionprintsclaudewheel <version>), and the--jsonoutput'sappfield is"claudewheel". Scripts that matched the oldctext must match the new one. Theclauncher script at the repository root, which was meant to be symlinked as~/.local/bin/c, is gone; run the installedclaudewheelcommand instead. The README's install instruction now names the command that exists,claudewheel install <version>. claudewheel --dump-schemais replaced byclaudewheel help --json.--dump-schemais now refused with an error namingclaudewheel help --json, which prints the help document on stdout instead of writing a file. Also: an integer value accepts only plain decimal digits with an optional leading minus sign (+30and030are refused), and a flag that takes one value is refused when given twice.- claudewheel is now a single Go binary; the PyPI and npm packages are no longer published. Install it with
go install github.com/stricttools/claudewheel/cmd/claudewheel@v0or from the Linux archives on each GitHub Release (claudewheel runs only on Linux); PyPI and npm keep 0.33.0. To move from the Python: uninstall it (uv tool uninstall claudewheel,pipx uninstall claudewheel, ornpm uninstall -g claudewheel), runclaudewheel upgrade-workspace, thenclaudewheel deploy-hooks claudewheel-probe-runner.service --force-overwriteso the probe runner's service runs the Go binary. The deprecated namesnew-profile,delete-profile, andshow-profileare gone. - A workspace an older claudewheel wrote is converted once with the new
claudewheel upgrade-workspace. It removes the retired keys (_schema_version,scratchpad_snooze_until) and adds the keys the defaults declare, never changing a value; every other command refuses an unconverted workspace and names it, and--dry-runpreviews it. The workspace is always$HOME/.claudewheel(CLAUDEWHEEL_CONFIG_DIRis no longer read), read-only commands such asshowandhealthno longer create missing files,statsno longer deletes anything,reset-optionswrites the defaultoptions.jsoninstead of deleting it, andconfigopens$EDITORonly, refusing when it is unset. reconcile-permissionsis gone;patch-profilestakes a required--profile <name>or--all-profiles. Only--all-profilesalso reconcilesshared-settings.json.permission addandpermission removeedit theallowlist only and drop the category argument (every launch resetsdenyandaskto the canonical lists), and adding an allow rule that conflicts with a guardrail rule is refused.healthexits 1 when any check is not OK.launchpresets segments only with-s KEY=VALUE. The per-segment flags (--profile,--github,--model,--directory,--mcp,--permissions) are gone. A value a fixed-choice segment does not offer is refused, naming the values it offers; print mode with a required segment unset is an error instead of a warning; arguments after--go to the client; and Ctrl-C at the launch bar exits 130.migratetakes--session <uuid>(the full lowercase id) or--all-sessions, with no substring matching, and refuses before moving anything when any destination already exists, listing every collision.importrefuses a source holding a broken symlink it would read, listing every one, before copying anything.- The permissions segment no longer offers plan mode, and
-s permissions=planor a pinnedplanis refused: accepting a plan wipes the session's history. The segment offersbypass,default, andauto. - Every confirmation takes the same keys:
yaccepts,ndeclines, Escape skips, and Enter does nothing. The scratchpad cleanup asks once per stale directory, andnkeeps that directory and never offers it again (the seven-day snooze is gone). A launch with the miniclaude client hides the version segment and refusesmcp=strict, and a reconcile that fails during a launch stops the launch instead of being ignored.
Features
claudewheel deploy-hooksships theheavywrapper.heavyruns a memory-heavy command alone on the machine and under a memory cap: one machine-wide lock queues heavy commands from every session, and each runs in its own systemd scope with a 5G limit (--memchanges it) and no swap, so a runaway job is killed alone instead of the whole terminal session.deploy-hooks heavy(or--all) writes it to~/.claudewheel/scripts/heavyand makes~/.local/bin/heavya symlink to it; anything else already at that path is refused unless--force-overwriteis passed.heavyruns jobs side by side within a memory budget, replacing the one machine-wide lock. Every heavy command declares its cap (--mem, 5G unless given), and starts once that cap, plus what the running heavy commands have not yet used of theirs, fits in the machine's available memory less a 2G margin; at most 8 run at once. A job that needs less, such as a single test or a small build, starts sooner with a smaller cap (heavy --mem 2G -- <command>), and a cap larger than the machine's memory less the margin is a usage error. A command whoseheavywas killed keeps its cap reserved while it runs on, and the waiting message names thesystemctl --user stopcommand that ends it. When the command returns,heavystops whatever it left running. The command's arguments now reach it unchanged:systemd-runused to rewrite$VARand$$in them, soheavy -- bash -c 'echo $$'printed$.- Each session claudewheel launches runs in its own memory-capped systemd scope. A memory-heavy command that runs outside
heavyinside a session (a test suite insidebash -c, say) can now take down only its own session, not the whole terminal. The ceiling issession_memory_maxinconfig.json(4G unless set) withsession_memory_swap_maxof swap (1G unless set, or0); claudewheel prints both at every launch, and a malformed value fails the launch naming the key. When the scope reaches its ceiling, the largest process in it is killed and the session carries on.heavyjobs started from a session are limited only by their own caps.systemd-runmust be on the launchPATH. Sessions already running keep their old setup until they are relaunched. - Claude Code sessions are told when the OOM killer kills their commands, and probes watch other sessions. Every OOM kill of a command a session started (in its own session scope, or in a
heavyjob it launched) is reported to that session: the report wakes its main conversation even when it sits idle, and a session that ended gets it when it resumes. A Bash call that dies with status 137 during such a kill is labeled for the conversation that made it, the main one or a subagent, naming any other Bash call that was running at the kill.claudewheel probe create oom-kill --session <uuid>or--all-sessionswatches other sessions' kills until a required--deadline(or--count,--until-watched-ends,--until-file, orprobe stop);probe subscribeandprobe unsubscribeadd and remove sessions, and a subscription made by a subagent reaches that subagent.probe listshows every probe, every undelivered or expired report, and every kill no session took, and the sessions overview counts each session's undelivered reports. The kills are read from the user journal byclaudewheel-probe-runner.service, whichclaudewheel deploy-hooks --all(ordeploy-hooks claudewheel-probe-runner.service) installs, enables, and starts, andclaudewheel healthchecks;systemctl --user stop claudewheel-probe-runner.servicestops it.heavynames the session that started a job in the job's scope description. Profiles get the two new hooks at their next launch orclaudewheel patch-profiles; redeploy the hook scripts and the service withclaudewheel deploy-hooks --all --force-overwrite. claudewheel move-session <session> <directory>moves one Claude Code session to another project directory. It takes the session's full lowercase id and an existing directory, renames the session's transcript and folder into that directory's session store (in the sameprojectsdirectory the session was found in, so a session of thedefaultprofile stays in~/.claude/projects), appends therelocatedrecord Claude Code's own/cdwrites, rewrites the transcript's paths into its own store folder, keeps the transcript's access and modification times, and removes the old store dir when nothing else is left in it. It refuses, before changing anything, a session that is running or starting, one a background job or another session's symlink refers to, one no store holds or more than one store dir holds, and a target that is not a directory or whose store dir already holds the session;--dry-runpreviews every change. An interrupted move is finished by running the same command again. Each move is recorded as a newmovedevent in the session's lifecycle, and the sessions overview (S) shows a moved session's new directory and transcript at once. When--resumerefuses a session that belongs to another directory that still exists, the error now also names theclaudewheel move-sessioncommand that moves it to the current directory.claudewheel helpandclaudewheel version.claudewheel help <command>prints that command's help page,claudewheel help --jsonprints the whole CLI's help document, andclaudewheel versionprints the version line. Both used to be taken as arguments to the launcher.claudewheel probe run-serviceruns the probe runner, and the user servicedeploy-hooksinstalls starts it with the binary that deployed it.
Fixes
claudewheel mvno longer corrupts paths when the new name contains the old one. With profiles sharing one session store, a move such asfootofoobarrewrote the transcripts once per profile, leavingfoobarbarbarbarbehind, and the dry-run counts were multiplied the same way. Each real session store is now processed once.- Session data for projects whose path holds a space,
@,+, or any other non-alphanumeric character is found again. claudewheel now names a project's session directory exactly as Claude Code does, including the truncated, hash-suffixed name Claude Code uses for paths longer than 200 characters, somv,--resume,--cont, andimportlook in the directory that actually holds the sessions. claudewheel mvmoves session data left behind by deleted subprojects. A session directory under the moved path whose project no longer exists and has no registry key is now identified by the working directory its own sessions recorded, and relabeled under the new path, so a move no longer refuses and nothing stays recorded under the old path. Every such directory is checked against registry keys, existing directories, and recorded working directories together, and a directory whose evidence names more than one path, or none, stops the move before anything changes.claudewheel mvrefuses when a session file it must rewrite cannot be read. It used to log the file and carry on, leaving that transcript at the old path while reporting success. The move now stops before changing anything and lists every unreadable file.claudewheel mvno longer leaves half-merged session directories behind. When the old and new session directories both held a file of the same name, the move skipped it, printed a warning, and left the old directory in place. It now refuses before changing anything, naming both directories and the shared names, and any failure to remove the old directory after a merge stops the move with an error naming it.--resumereads a moved session's original directory correctly. It used to take the first working directory a transcript recorded, which can be a directory the session merely visited, and then offered to move the wrong project or told you to run from the wrong place. It now uses the working directory whose name matches the session's directory, and refuses with an error when the transcripts record none or several.claudewheel mvno longer rewrites the paths of sibling projects inside session transcripts. Moving~/Projects/fooused to change every~/Projects/foobarand~/Projects/foo-barmentioned in the moved sessions as well, falsifying them into paths that never existed. A path is now moved only where it ends: at a/, a quote, whitespace, punctuation, or the end of the text; and fields that hold one path, such as a session's working directory or a tool's file path, move only when they are the moved path or lie inside it.claudewheel importreads each session's original directory correctly and refuses broken transcript links. It used to take the first working directory a transcript recorded, which can be a directory the session merely visited, so sessions could be filed under the wrong project. It now uses the working directory whose name matches the session's directory, and refuses, naming the directory, when the transcripts record none or several. A session transcript in the source that is a symlink to a missing file used to be skipped with a warning; the import now refuses before writing anything and lists every such file.heavyno longer leaks its lock, explains memory kills, and waits visibly and boundedly. A process the command leaves running no longer keeps the machine-wide lock afterheavyexits, which used to make every laterheavywait forever. When the command is killed for going over its memory cap,heavysays so and suggests a rerun with twice the cap (heavy --mem 10G -- <command>). Every run prints its cap, and a line when-p=2is added toGOFLAGS; the command runs at a lower CPU weight (20, against the default 100) so interactive work stays responsive. While waiting for the lock,heavyprints the holder and the time waited every 30 seconds, names a holder only while that process is still alive, and gives up with exit status 75 after 60 minutes (--max-wait, such as90mor2h, sets another limit), saying how to find and stop the holder.--memwithout a value, or with a size that is not a whole number with aK,M,G, orTsuffix, is a usage error.claudewheel deploy-hooksnow replaces each script with a new file instead of rewriting it, so redeploying never disturbs aheavyor hook that is already running.- heavy no longer waits out --max-wait for a cap that cannot fit while no heavy command is running; it exits at once (status 75) and names the largest cap that fits now.
heavyno longer tells an agent to rerun a memory-killed command at twice the cap. When a command is killed at its--memcap,heavynames the peak before the kill and says not to rerun it with a bigger cap: a command that outgrows its cap is a defect to fix at the source. Only a cap that was a guess may be measured, once, at the largest cap that fits now, whichheavynames. Every run now ends with the peak memory use of the command's scope, so a cap can be set from a measurement. The cannot-fit refusal and the give-up message no longer offer a guessed smaller--memas the way around, and the give-up message names thesystemctl --user stopof a stuck job's scope instead of akillof itsheavy, which left the command running and holding its cap.- A session's lifecycle record always carries its Claude Code process ID. The SessionStart hook used to read the ID from Claude Code's session registry, which is sometimes not written yet when the hook runs, leaving it empty; it now takes the ID Claude Code gives its hooks. Redeploy the hook scripts to pick it up.
- saferm is named at its new home. When a profile deletion is refused for lack of saferm, the install command it prints is
go install github.com/stricttools/saferm@v0, and the checksum-verified download comes fromgithub.com/stricttools/saferm's releases. - Sessions moved with Claude Code's own
/cdare read in their new directory. claudewheel read a session's directory only from thecwdvalues its transcript recorded, so the store dir a session had been moved into by/cdrecorded no directory of its own:mvrefused with a store dir that "does not resolve to exactly one real path", and--resumeof such a session failed with "no session recorded a cwd that encodes to this dir's name". claudewheel now reads the transcript's lastrelocatedrecord first, as Claude Code does, andmvrewrites that record's directory like any other path field. --resumerefuses an id that is not lowercase. Claude Code session ids are lowercase UUIDs. A--resumevalue shaped like one but carrying uppercase letters used to be looked up as given and then reported as "not found in any project directory", even when the session existed; it is now refused at once with--resume <value> is not a session id: session ids are lowercase, and it is never searched as a session title or lowercased for you.permission list --all-profilesno longer crashes when a profile (such as the default~/.claude) has nosettings.json; that profile is listed with no rules.