Skip to content

v0.34.0

Choose a tag to compare

@smm-h smm-h released this 08 Oct 18:19
· 18 commits to main since this release

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) and tool_memory_swap_max (1G) from config.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 through CLAUDE_CODE_SHELL_PREFIX, pointed at the new claudewheel-tool-scope script, which a launch deploys when it is missing; hooks, the status line, and MCP servers run outside the cap. session_memory_max and session_memory_swap_max are removed from config.json and not carried over. Probe reports, probe commands, and heavy attribute 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, --help footers, parse errors, and --version now print claudewheel instead of c (claudewheel --version prints claudewheel <version>), and the --json output's app field is "claudewheel". Scripts that matched the old c text must match the new one. The c launcher script at the repository root, which was meant to be symlinked as ~/.local/bin/c, is gone; run the installed claudewheel command instead. The README's install instruction now names the command that exists, claudewheel install <version>.
  • claudewheel --dump-schema is replaced by claudewheel help --json. --dump-schema is now refused with an error naming claudewheel 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 (+30 and 030 are 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@v0 or 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, or npm uninstall -g claudewheel), run claudewheel upgrade-workspace, then claudewheel deploy-hooks claudewheel-probe-runner.service --force-overwrite so the probe runner's service runs the Go binary. The deprecated names new-profile, delete-profile, and show-profile are 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-run previews it. The workspace is always $HOME/.claudewheel (CLAUDEWHEEL_CONFIG_DIR is no longer read), read-only commands such as show and health no longer create missing files, stats no longer deletes anything, reset-options writes the default options.json instead of deleting it, and config opens $EDITOR only, refusing when it is unset.
  • reconcile-permissions is gone; patch-profiles takes a required --profile <name> or --all-profiles. Only --all-profiles also reconciles shared-settings.json. permission add and permission remove edit the allow list only and drop the category argument (every launch resets deny and ask to the canonical lists), and adding an allow rule that conflicts with a guardrail rule is refused. health exits 1 when any check is not OK.
  • launch presets 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.
  • migrate takes --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. import refuses 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=plan or a pinned plan is refused: accepting a plan wipes the session's history. The segment offers bypass, default, and auto.
  • Every confirmation takes the same keys: y accepts, n declines, Escape skips, and Enter does nothing. The scratchpad cleanup asks once per stale directory, and n keeps that directory and never offers it again (the seven-day snooze is gone). A launch with the miniclaude client hides the version segment and refuses mcp=strict, and a reconcile that fails during a launch stops the launch instead of being ignored.

Features

  • claudewheel deploy-hooks ships the heavy wrapper. heavy runs 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 (--mem changes 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/heavy and makes ~/.local/bin/heavy a symlink to it; anything else already at that path is refused unless --force-overwrite is passed.
  • heavy runs 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 whose heavy was killed keeps its cap reserved while it runs on, and the waiting message names the systemctl --user stop command that ends it. When the command returns, heavy stops whatever it left running. The command's arguments now reach it unchanged: systemd-run used to rewrite $VAR and $$ in them, so heavy -- bash -c 'echo $$' printed $.
  • Each session claudewheel launches runs in its own memory-capped systemd scope. A memory-heavy command that runs outside heavy inside a session (a test suite inside bash -c, say) can now take down only its own session, not the whole terminal. The ceiling is session_memory_max in config.json (4G unless set) with session_memory_swap_max of swap (1G unless set, or 0); 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. heavy jobs started from a session are limited only by their own caps. systemd-run must be on the launch PATH. 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 heavy job 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-sessions watches other sessions' kills until a required --deadline (or --count, --until-watched-ends, --until-file, or probe stop); probe subscribe and probe unsubscribe add and remove sessions, and a subscription made by a subagent reaches that subagent. probe list shows 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 by claudewheel-probe-runner.service, which claudewheel deploy-hooks --all (or deploy-hooks claudewheel-probe-runner.service) installs, enables, and starts, and claudewheel health checks; systemctl --user stop claudewheel-probe-runner.service stops it. heavy names the session that started a job in the job's scope description. Profiles get the two new hooks at their next launch or claudewheel patch-profiles; redeploy the hook scripts and the service with claudewheel 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 same projects directory the session was found in, so a session of the default profile stays in ~/.claude/projects), appends the relocated record Claude Code's own /cd writes, 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-run previews every change. An interrupted move is finished by running the same command again. Each move is recorded as a new moved event in the session's lifecycle, and the sessions overview (S) shows a moved session's new directory and transcript at once. When --resume refuses a session that belongs to another directory that still exists, the error now also names the claudewheel move-session command that moves it to the current directory.
  • claudewheel help and claudewheel version. claudewheel help <command> prints that command's help page, claudewheel help --json prints the whole CLI's help document, and claudewheel version prints the version line. Both used to be taken as arguments to the launcher.
  • claudewheel probe run-service runs the probe runner, and the user service deploy-hooks installs starts it with the binary that deployed it.

Fixes

  • claudewheel mv no longer corrupts paths when the new name contains the old one. With profiles sharing one session store, a move such as foo to foobar rewrote the transcripts once per profile, leaving foobarbarbarbar behind, 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, so mv, --resume, --cont, and import look in the directory that actually holds the sessions.
  • claudewheel mv moves 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 mv refuses 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 mv no 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.
  • --resume reads 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 mv no longer rewrites the paths of sibling projects inside session transcripts. Moving ~/Projects/foo used to change every ~/Projects/foobar and ~/Projects/foo-bar mentioned 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 import reads 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.
  • heavy no 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 after heavy exits, which used to make every later heavy wait forever. When the command is killed for going over its memory cap, heavy says so and suggests a rerun with twice the cap (heavy --mem 10G -- <command>). Every run prints its cap, and a line when -p=2 is added to GOFLAGS; the command runs at a lower CPU weight (20, against the default 100) so interactive work stays responsive. While waiting for the lock, heavy prints 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 as 90m or 2h, sets another limit), saying how to find and stop the holder. --mem without a value, or with a size that is not a whole number with a K, M, G, or T suffix, is a usage error. claudewheel deploy-hooks now replaces each script with a new file instead of rewriting it, so redeploying never disturbs a heavy or 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.
  • heavy no longer tells an agent to rerun a memory-killed command at twice the cap. When a command is killed at its --mem cap, heavy names 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, which heavy names. 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 --mem as the way around, and the give-up message names the systemctl --user stop of a stuck job's scope instead of a kill of its heavy, 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 from github.com/stricttools/saferm's releases.
  • Sessions moved with Claude Code's own /cd are read in their new directory. claudewheel read a session's directory only from the cwd values its transcript recorded, so the store dir a session had been moved into by /cd recorded no directory of its own: mv refused with a store dir that "does not resolve to exactly one real path", and --resume of such a session failed with "no session recorded a cwd that encodes to this dir's name". claudewheel now reads the transcript's last relocated record first, as Claude Code does, and mv rewrites that record's directory like any other path field.
  • --resume refuses an id that is not lowercase. Claude Code session ids are lowercase UUIDs. A --resume value 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-profiles no longer crashes when a profile (such as the default ~/.claude) has no settings.json; that profile is listed with no rules.