claudewheel v0.15.1 /Changelog
Edit
On this page

#Changelog

#0.15.1

Thread safety fix for background discovery and wizard UX overhaul

Context

The background discovery thread shared a mutable state dict with the main thread, creating a race condition on npm_versions_cache writes. Fixed by passing a deep copy and copying results back on the main thread after completion.

The profile creation wizard was overhauled: 6 checkbox fields are now hidden behind a collapsible Advanced toggle (defaulting to sensible values), Enter from the Name field submits immediately, errors persist until the user takes a meaningful action, context-sensitive keyboard hints appear at the bottom, Shift-Tab navigates backward, and the text input has visible brackets. The Cancel button was removed (ESC suffices).

#Features

  • Wizard UX overhaul. Collapsible Advanced toggle hides 6 checkboxes by default, Enter from Name field submits, persistent error display, context-sensitive keyboard hints, Shift-Tab backward navigation, improved visual clarity (bracketed text input, bold radio selections).

#Fixes

  • Fix. Background discovery thread no longer shares mutable state dict with the main thread; uses a deep copy to prevent race conditions on npm version cache writes.

#0.15.0

Option provenance architecture: SegmentState separates discovered, pinned, and default options with staleness policies, value-based selection, deferred discovery apply, and a provenance overlay

Context

A pre-registry build (0.1.0) accidentally shipped with the maintainer's personal data hardcoded in DEFAULT_OPTIONS (GitHub handles, profile names). This seeded into users' ~/.claudewheel/options.json on first run. Even after the fix (making defaults empty + adding discovery), stale data persisted because gh_auth appended (never replaced) and claude_config_scan fell back to stale values when discovery returned empty.

This release introduces SegmentState -- a new data model that cleanly separates discovered (runtime), pinned (user-added), and default (shipped) option collections. Discovery always replaces the discovered collection; pinned values are never touched by discovery. A staleness policy (IMMEDIATE for credentials, VERIFY for filesystem objects) controls what happens when previously-discovered values disappear. The entire discovery system was refactored from a monolithic match/case dispatch into a typed registry of individual functions returning DiscoveryResult dataclasses.

Selection tracking switched from index-based (fragile when options change) to value-based. The "+" creation sentinel moved from a real option to a virtual UI element via display_options. Slow discovery results are now deferred for the focused segment and applied on defocus, preventing option list disruption during interaction. A provenance overlay (toggle with ?) shows where each option came from.

#Features

  • Staleness policy. Discovery registry entries now carry verify callbacks; set_discovered uses them to retain values that still exist on disk when a re-scan omits them.
  • Directory discovery. Recent dirs are now validated (must exist on disk) and stale entries are pruned from state. Static values no longer mixed into discovery results.
  • Virtual '+' button. The '+' creation sentinel is now a virtual UI element, no longer stored in segment state collections. Freeform values are promoted from ephemeral to pinned on launch.
  • Deferred discovery apply. Slow discovery results for the focused segment are now buffered and applied on defocus, preventing option list disruption while the user is interacting. A pending indicator (*) appears in the segment label when results are waiting.
  • Provenance overlay. Press ? to toggle a source overlay on fan-out options: * discovered, ^ pinned, . default, ~ ephemeral. The status bar shows a legend while active.
  • Docs. Added installation instructions (pipx/uv) and deprecation notice for the old Node/npm package.

#0.14.0

Add import command for importing session data from external Claude Code directories

Context

The new claudewheel import command enables importing Claude Code session data from external directories (e.g., Windows backups onto a Linux machine). It handles cross-OS path rewriting (Windows backslashes to Unix forward slashes), collision detection for sessions that already exist in the store, optional session re-identification (reid), and a dry-run mode for previewing what would be imported.

#Features

  • New command. claudewheel import imports Claude Code session data from external directories (e.g., Windows backups) into the shared store, with cross-OS path rewriting, collision detection, reid support, and dry-run mode.

#0.13.1

Instant TUI startup via async discovery, KeyboardInterrupt fix, SEO improvements

#Features

  • Improvement. TUI launches instantly. Slow discovery calls (GitHub auth, npm versions) now run in a background thread instead of blocking startup.

#Fixes

  • Fix. Ctrl-C during npm version fetch no longer produces a traceback.

#0.13.0

Proactive directory rename detection via inode tracking

#Features

  • New feature. Proactive directory rename detection via inode tracking. On every launch, claudewheel records the project directory's inode. The health check detects when a recorded path was renamed and suggests claudewheel mv --post-hoc to fix it.

#0.12.0

Fable 5 model support, model auto-sync, full orphan scan for --cont

#Features

  • New feature. Model list now auto-syncs from defaults on startup. New models added to claudewheel are automatically available without resetting options.
  • New feature. Added Fable 5 (claude-fable-5 and claude-fable-5[1m]) to the default model list.
  • Improvement. --cont now scans all orphaned session directories, not just same-parent. Cross-parent directory renames are now detected.

#0.11.0

mv now renames directories by default, --post-hoc for session-only migration

#Breaking

  • Breaking. mv now renames the directory on disk by default, then migrates sessions. Use --post-hoc for session-only migration (the old behavior).

#0.10.1

CI workflow improvements: idempotent publish steps for npm and PyPI

Context

Scaffold update added skip-if-already-published checks to both npm and PyPI publish workflows, making CI re-runs safe. Also added separate CI check workflows.

#Fixes

  • Fix. CI publish workflows are now idempotent -- re-running a partially failed publish no longer fails on already-published packages.

#0.10.0

New permission command group for managing profile permission rules

#Features

  • New command group. permission add, permission remove, and permission list subcommands for managing profile permission rules from the CLI.

#0.9.1

--cont interception, mv merge fix, cleaner dry-run UX

#Features

  • New feature. --cont now detects directory renames the same way --resume does, scanning for orphaned sessions in sibling directories.
  • Improvement. Resume/cont interception shows the claudewheel mv command when the old path still exists, and uses a concise human-readable dry-run summary instead of per-file log spam.

#Fixes

  • Bug fix. mv now merges sessions into an existing target directory instead of silently skipping the move.

#0.9.0

Rename redir to mv, add resume interception for directory renames, fix path encoding bug

Context

The redir command is renamed to mv for better discoverability. When --resume can't find a session under the current directory, claudewheel now searches the shared store, detects that the project directory was renamed, and offers to move all sessions to the new path. The path encoding function is also fixed to replace dots (not just slashes) with hyphens, matching Claude Code's internal encoding -- this fixes mv operations on dotfile paths.

#Breaking

  • Breaking. Renamed redir command to mv.

#Features

  • New feature. Resume interception: when --resume can't find a session under the current directory, claudewheel searches the shared store, detects directory renames, and offers to move sessions to the new path.

#Fixes

  • Bug fix. Path encoding now replaces both / and . with -, matching Claude Code's internal encoding. Previously, dotfile paths (e.g. ~/.claude-common) would encode incorrectly.

#0.8.0

Rename gc command to stats

Context

The gc command only reports shared-store statistics now (sentinel cleanup and origins compaction were removed in v0.7.0). Renamed to reflect its actual purpose.

#Breaking

  • Renamed. gc command renamed to stats to reflect its actual purpose (reporting shared-store statistics).

#0.7.0

Remove profile attribution system, add --picker flag, unify shared settings

Context

The profile attribution system (hook-stamp-origin, xattr stamping, sentinels, origins log) had unfixable race conditions and 30% of session files could never be attributed. Removed entirely rather than patching. Also adds --picker for argless session resume and unifies shared settings with drift detection.

#Breaking

  • Breaking. Removed the profile attribution system (hook-stamp-origin, xattr stamping, sentinel files, origins log). The system had unfixable race conditions and 30% of files could never be attributed.

#Features

  • New flag. --picker opens the Claude session resume picker without requiring a session ID argument.
  • Unified shared settings. Replaced per-profile profile-defaults.json with a single shared-settings.json and drift detection.
  • deploy-hooks --force. Added --force flag to overwrite existing hook scripts.

#Fixes

  • Health check. Removed xattr-coverage and hook-integrity checks; streamlined hooks-wired to only verify hook-timestamp.

#0.6.1

Consolidate shared data and eliminate ~/.claude-shared/ and ~/.claude-common/

Context

Shared session data (projects, session-env, file-history, tasks, todos, paste-cache) moved from ~/.claude-shared/ to ~/.claudewheel/shared/. Skills, utility scripts, and profile origins moved from ~/.claude-common/ into ~/.claudewheel/. COMMON_DIR constant eliminated. Sentinel files moved to dedicated ~/.claudewheel/shared/sentinels/ subdirectory. Dead code (_strip_xattrs, _clean_origins_file) removed. Origins file dual-location bug fixed.

#Breaking

  • Shared data consolidated. Session data, skills, and scripts moved from ~/.claude-shared/ and ~/.claude-common/ into ~/.claudewheel/. Both old directories eliminated.

#Fixes

  • Fix. Profile origins log now correctly read from ~/.claudewheel/ instead of stale ~/.claude-common/ path.

#0.6.0

Profile centralization, hook management, worktree isolation, docs website

Context

Profiles moved from ~/.claude-/ to ~/.claudewheel/profiles// (breaking). New deploy-hooks command auto-creates hook scripts from built-in templates. Settings drift detection compares profiles against canonical shared-settings.json. PreToolUse hook blocks Agent tool worktree isolation to prevent multi-session conflicts. Cron tools (CronCreate, CronDelete, CronList, ScheduleWakeup) unblocked. Documentation website at claudewheel.smmh.dev with auto-generated API/CLI reference and branding.

#Breaking

  • Profile directories moved. Profiles now live at ~/.claudewheel/profiles// instead of ~/.claude-/. A startup warning appears if old-style directories are detected.

#Features

  • New command. deploy-hooks auto-creates hook scripts at ~/.claudewheel/scripts/ from built-in templates.
  • Settings drift detection. Health check compares profiles against a canonical shared-settings.json and reports differences.
  • Worktree isolation guard. PreToolUse hook blocks the Agent tool from using worktree isolation, preventing multi-session conflicts.
  • Cron tools enabled. CronCreate, CronDelete, CronList, and ScheduleWakeup removed from disallowed tools.
  • Documentation website. Live docs site at claudewheel.smmh.dev with auto-generated API reference, CLI reference, and branding.

#0.5.0

Strictcli compatibility fix and config-directory rename to ~/.claudewheel/.

Context

The config directory has been renamed from ~/.claudelauncher/ to ~/.claudewheel/ to match the project name (the rename of the project itself happened a while ago, but the config-dir path was never updated). Existing users must mv ~/.claudelauncher ~/.claudewheel before upgrading or claudewheel will scaffold a fresh empty config directory on next launch.

Strictcli v0.16.0 added a guardrail requiring unique=True or unique=False on every repeatable=True flag. claudewheel's -s/--set flag did not pass it and crashed at startup with ValueError: Flag "set": repeatable requires explicit unique. This release adds unique=False and, more importantly, surfaces the underlying intent the guardrail is meant to enforce: _handle_launch now rejects any duplicate segment override regardless of source. Previously, passing the same key twice (e.g. --profile work -s profile=personal, or -s profile=work -s profile=personal) silently dropped the earlier value. The new diagnostic names the conflicting key, both values, and both sources.

#Breaking

  • Config directory renamed from ~/.claudelauncher/ to ~/.claudewheel/. Run mv ~/.claudelauncher ~/.claudewheel before upgrading or claudewheel will scaffold a fresh empty dir on next launch.

#Fixes

  • Fix startup crash from strictcli guardrail; -s now errors on duplicate segment keys (including conflicts between an individual segment flag and -s) instead of silently dropping the earlier value.

#0.4.5

#Fixes

  • Fix. resolve_profile() now runs option discovery before reading metadata, fixing programmatic profile resolution from external callers.

#0.4.4

  • No user-facing changes.

#0.4.3

#Fixes

  • Fix. Profiles set up before claudewheel (without .credentials.json) were invisible to health checks and the TUI profile picker. They are now discovered via tokens.json.
  • Fix. Compatibility with strictcli 0.5.0 (MutexGroup is now always required; session flags moved to a Tag with manual mutual-exclusion check).

#0.4.2

  • No user-facing changes.

#0.4.1

#Fixes

  • CI fix. Resolved dependency resolution failure by removing local path override for strictcli.

#0.4.0

#Breaking

  • Python 3.11 required. Bumped minimum Python version from 3.10 to 3.11 for strictcli compatibility.

#Features

  • New API. resolve_profile(name) returns environment variables (CLAUDE_CONFIG_DIR, CLAUDE_CODE_OAUTH_TOKEN) for a given profile, enabling programmatic consumers like claudestream.
  • CLI rewrite. Migrated from argparse to strictcli with typed subcommands, mutex groups, and structured flags.

#Fixes

  • Print mode hygiene. Print mode (-p) now skips health checks and state writes, preventing TUI default pollution and stderr noise for programmatic callers.