claudewheel 0.3.0__tar.gz

claudewheel-0.3.0/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "rlsbl prs"
+          }
+        ]
+      }
+    ]
+  }
+}

claudewheel-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+      - run: uv pip install --system -e . pytest
+      - run: python3 -m pytest tests/ -v
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: node -e "require('./package.json')"
+      - run: node bin/claudewheel.js --help || true

claudewheel-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

claudewheel-0.3.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+
+# Added by share-it-on
+node_modules/
+*.log
+.DS_Store
+coverage/
+dist/
+*.egg-info/
+.rlsbl/lock
+.credentials.json
+.*-cache.json
+.env
+.env.local
+
+# Added by rlsbl
+.rlsbl-notes-*.tmp
+*.local-only

claudewheel-0.3.0/.npmignore

@@ -0,0 +1,7 @@
+__pycache__/
+**/__pycache__/
+*.pyc
+**/*.pyc
+tests/
+todo/
+scripts/

claudewheel-0.3.0/.rlsbl/bases/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

claudewheel-0.3.0/.rlsbl/bases/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # engines.node: >= 18
+        node-version: [20, 22, 24]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test --if-present
+      - run: npm audit --audit-level=moderate || true

claudewheel-0.3.0/.rlsbl/bases/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

claudewheel-0.3.0/.rlsbl/bases/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+__pycache__/
+*.pyc
+*.log
+.DS_Store
+coverage/
+dist/
+*.egg-info/
+.rlsbl-notes-*.tmp
+.rlsbl/lock
+.credentials.json
+.*-cache.json
+.env
+.env.local
+*.local-only

claudewheel-0.3.0/.rlsbl/bases/CLAUDE.md

@@ -0,0 +1,20 @@
+# claudewheel
+
+## Release workflow
+
+This project uses [rlsbl](https://github.com/smm-h/rlsbl) for release orchestration.
+
+- Update CHANGELOG.md with a `## X.Y.Z` entry describing changes
+- Run `rlsbl release [patch|minor|major]` to bump version and create a GitHub Release
+- CI handles publishing automatically via the publish workflow
+- Never publish manually — always use `rlsbl release`
+- Requires NPM_TOKEN secret on GitHub (Settings > Secrets > Actions)
+- Use `rlsbl release --dry-run` to preview a release without making changes
+
+## Conventions
+
+- No tokens or secrets in command-line arguments (use env vars or config files)
+- All file writes to shared state should be atomic (write to tmp, then rename)
+- External calls (APIs, CLI tools) must have timeouts and graceful fallbacks
+- Use `npm link` (npm) or `uv pip install -e .` (Python) for local development
+- CI runs smoke tests on every push; manual testing for UI/UX changes

claudewheel-0.3.0/.rlsbl/config.json

@@ -0,0 +1,6 @@
+{
+  "targets": [
+    "npm",
+    "pypi"
+  ]
+}

claudewheel-0.3.0/.rlsbl/hashes.json

@@ -0,0 +1,9 @@
+{
+  ".github/workflows/ci.yml": "c8ea07acf2aa7a96c71f6e70f625807138549fd2b96cb5f15bd7d60785b4b86d",
+  ".github/workflows/publish.yml": "1216ed5948dec0ec26a2e1aea32c7eda914e76fca6aec3676e564630d49deb2a",
+  "scripts/check-prs.sh": "a438f046ac169256b859873e6f12b66bf629e12fa4bc1f766ed8484af983383c",
+  "scripts/pre-push-hook.sh": "68c436c3d16b88b289be8eb8af0d621d94a0249dd8287b2adca3b0bb85c9fa58",
+  ".rlsbl/hooks/pre-release.sh": "1b13062dda97df66792df382312263d704a6cc706d2dd3da921f4c470488276d",
+  ".rlsbl/hooks/post-release.sh": "b455f8511e0b2655509ecf5dcb0ab7da5bb7c961f47910ff8e00cab5bd51f833",
+  ".gitignore": "773ea3da02e79c42be002ec89b8b29cb7ad4001bf440b7fa78789210a8bbd7ef"
+}

claudewheel-0.3.0/.rlsbl/hooks/post-release.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Post-release hook. Runs after a successful release (non-fatal).
+# Environment: RLSBL_VERSION is set to the released version.
+# Customize this for your project (e.g., local install, deploy, notify).
+
+set -euo pipefail
+
+echo "Post-release: v$RLSBL_VERSION"

claudewheel-0.3.0/.rlsbl/hooks/pre-release.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Pre-release validation hook.
+# Runs before rlsbl creates a release. Exit non-zero to abort.
+# Detects project type and runs appropriate checks automatically.
+
+set -euo pipefail
+
+echo "Running pre-release checks..."
+
+if [ -f go.mod ]; then
+  echo "Detected Go project"
+  go vet ./...
+  go build ./...
+  go test ./... -race -short -count=1
+elif [ -f package.json ]; then
+  echo "Detected npm project"
+  npm test
+elif [ -f pyproject.toml ]; then
+  echo "Detected Python project"
+  if command -v uv &>/dev/null; then
+    uv run pytest
+  elif command -v pytest &>/dev/null; then
+    pytest
+  fi
+fi
+
+echo "Pre-release checks passed."

claudewheel-0.3.0/.rlsbl/version

@@ -0,0 +1 @@
+0.17.0

claudewheel-0.3.0/CHANGELOG.md

@@ -0,0 +1,166 @@
+# claudewheel Changelog
+
+## 0.3.0
+- Publish to PyPI: `pip install claudewheel` or `uv pip install claudewheel` now works alongside the existing npm distribution
+- Lower minimum Python version from 3.14 to 3.10 (the JS wrapper now reads requires-python from pyproject.toml instead of hardcoding)
+
+## 0.2.1
+- Fix: disallowedTools were never enforced -- the wizard wrote to a top-level `disallowedTools` key in settings.json that Claude Code silently ignores
+- Enforcement now uses `--disallowedTools` CLI flag in launch.py, which strips tools from the model's context entirely
+- Persist tool list under `settings.claudewheel.disallowedTools` (namespaced, not a Claude Code key)
+- Health check detects missing tools in claudewheel namespace and flags stale top-level key
+- patch-profiles migrates existing profiles: moves tools to new namespace, deletes inert key
+
+## 0.2.0
+- Enforce disallowedTools across all profiles: 19 Claude Code tools disabled via settings.json (plan mode, worktree, task tracking, cron, notebook, push notifications, remote triggers, LSP, skill auto-invoke)
+- Disable auto permission mode across all profiles (permissions.disableAutoMode)
+- Remove "auto" from permissions segment options
+- Wizard applies disallowedTools and disableAutoMode to new profiles automatically
+- Health check flags profiles missing disallowedTools or disableAutoMode
+- Add scripts/patch-profiles to retrofit existing profiles
+
+## 0.1.13
+- Schema-versioned config migrations: existing users' github segment automatically fixed to optional
+- Minimap character configurable via `overflow.minimap_char` theme key
+- Config migration runs on startup, adds missing keys and applies one-time value fixes
+
+## 0.1.12
+- Fix minimap: use small square (▪) instead of full block so focused segment's background highlight is visible
+
+## 0.1.11
+- Viewport scrolling for narrow terminals: bar scrolls horizontally with focused segment centered
+- Edge arrows (`<2`, `3>`) show off-screen segment count at viewport edges
+- Minimap: colored block indicators in top-right corner showing all segments at a glance
+- Configurable minimap visibility (`"minimap": "auto"` or `"always"` in config.json)
+- Overflow theme colors: `arrow_fg`, `minimap_fg`, `minimap_focused_bg` in the `overflow` theme section
+- Clip partially visible segments at viewport edges instead of rendering past margins
+- Clip fan-out options at screen edges when scrolling
+- Minimum width guard for degenerate terminals (< 9 columns)
+- Config migration: missing default keys are merged into existing config/segments/theme files on startup
+- Wide terminals see no visual change (viewport only activates when the bar overflows)
+
+## 0.1.10
+- Fix backspace in freeform segments trapping arrow keys (emptying the buffer now exits edit mode; LEFT/RIGHT work mid-edit)
+- Make GitHub segment optional (launching without a GH profile is legitimate)
+
+## 0.1.9
+- Add `--version` flag (prints app version)
+- Add `-s`/`--set KEY=VALUE` flag for setting any segment value (e.g. `-s version=2.1.119`)
+- `-s` is required for the `version` segment (its `--version` flag collides with the app version flag)
+- `-s` takes precedence over individual `--<segment>` flags; validates segment name and format
+
+## 0.1.8
+- Add `print_mode` toggle to segment definitions; segments declare whether they participate in `-p` mode
+- Exclude `github`, `mcp`, `permissions` segments from print mode by default (github is slow, mcp unreliable non-interactively, permissions can hang on interactive-only modes)
+- Fix health check blocking `input()` in print mode; warnings now go to stderr without blocking
+- Warn to stderr when print mode uses fallback defaults for missing required segments
+
+## 0.1.7
+- Add `-p`/`--print` flag for non-interactive print mode
+- Add `--` passthrough for raw Claude Code flags (e.g. `--output-format`, `--allowedTools`)
+- Add `scripts/redir-history.sh` for rewriting paths in history.jsonl files
+
+## 0.1.6
+- Default directory segment to current working directory
+- Raise `/tmp/claude` health check threshold from 500 MB to 2 GB
+
+## 0.1.5
+- Add `--redir OLD NEW` subcommand for redirecting session data after a project directory rename
+- Fix `--redir` to find `.claude.json` project keys under `data["projects"]` (not top-level)
+- Fix `--redir --dry-run` to report accurate JSONL file/line counts
+- Rename Python package from `claude_launcher` to `claudewheel`
+- Simplify README quick start, add `--redir` to CLI docs
+
+## 0.1.4
+- Rename all internal references from ClaudeLauncher to claudewheel (CLI output, User-Agent)
+- Add branding assets (logo, banner) and banner to README
+
+## 0.1.3
+- Fix freeform backspace bug: can now delete to empty string without resetting
+
+## 0.1.2
+- Exclude `__pycache__` bytecode from npm tarball (package size: 75kB -> 26kB)
+
+## 0.1.1
+- Remove hardcoded personal data from defaults (profile names, GitHub usernames)
+- Add runtime discovery for profile segment (`claude_config_scan` — scans `~/.claude-*` directories)
+- Add runtime discovery for github segment (`gh_auth` — parses `gh auth status`)
+- Expand directory scan parents to common project directories
+
+## 0.1.0
+- Initial npm release as `claudewheel`
+- Node.js bin wrapper with Python 3.14+ version check
+
+## Architecture
+
+- 16-module Python package (no external deps, stdlib only -- targets Python 3.14)
+- Bash shim `c` as entry point, sets `PYTHONPATH` and runs `python3 -m claude_launcher`
+- Tests via stdlib `unittest` (61+ tests, run in <10 ms)
+
+## TUI
+
+- Single-line segment bar at vertical-centre-left of the terminal
+- Vertical fan-out shows other options above/below the selected value
+- Per-segment focus background; per-option foreground colours from theme
+- Fuzzy search with character-position highlighting (matched chars in `search_match_fg`)
+- Search buffer turns red (`search_no_match_fg`) when zero matches
+- "+" sentinel option for creatable segments (profile, github, model) lets users add new values inline
+- Freeform editing on directory segment: backspace/typing on a selected value enters edit mode
+- Cycle math includes -1 (blank) as a ring position; symmetric blank reachability for both `wrap=True` and `wrap=False`
+
+## Discovery
+
+- `npm_and_local` for versions: fetches `npm view @anthropic-ai/claude-code versions --json` (cached 1 h in `state.json`), merges with locally installed binaries
+- `directory_scan`: lists subdirectories of configured parent dirs (`~/Projects`, `~/Work`)
+- `state_field`: merges state-tracked recent values
+- `directory_listing`: simple file listing (legacy, used by older configs)
+
+## Cross-segment dependencies
+
+- Options can declare `requires` constraints on other segments' values (e.g. `auto` permission previously required version >=2.1.110, since dropped)
+- `evaluate_requires(bar)` recomputes per-segment `unavailable` sets on every keypress
+- Renderer dims unavailable options with `unavailable_fg`
+
+## Install mechanism
+
+- Direct binary download from Anthropic's GCS bucket (the same mechanism Claude Code's own updater uses): `storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{ver}/{platform}/claude`
+- Fetches `manifest.json` first for SHA-256 checksum
+- Streams ~234 MB binary with progress reporting
+- Atomic write via `.downloading` -> rename
+- Replaces the original npm-based approach which failed on user-prefix installs
+
+## CLI
+
+- Dynamic `--<segment_key>` flags generated from segment definitions
+- TUI shown by default (pre-filled from `last_config` + arg overrides)
+- TUI skipped only when args alone cover every required segment
+- Passthrough flags `-c` / `--continue` and `-r` / `--resume [SESSION_ID]` for Claude Code's session restore
+- One-shot flags: `--versions`, `--config`, `--health`, `--install VERSION`, `--uninstall VERSION`, `--reset-options`, `--show`
+
+## Health checks
+
+- tmpfs quota (warns >80%)
+- `/tmp/claude-$UID/` size (warns >500 MB)
+- Ghost files check removed -- was misidentifying memfd regions as leaks
+
+## State persistence
+
+- `last_config` (segment selections from last launch)
+- `recent_dirs` (cap 20, dedup, recent-first)
+- `launch_count`
+- `npm_versions_cache` (1 h TTL)
+- Atomic writes via tmp-file rename
+
+## Hooks
+
+- `~/.claudelauncher/hooks/pre-launch*` scripts run before `exec`
+- Receive segment selections as `CL_*` env vars
+- Nonzero exit aborts launch
+
+## Notable upstream issue
+
+- Filed and closed [#54026](https://github.com/anthropics/claude-code/issues/54026) as duplicate of [#53180](https://github.com/anthropics/claude-code/issues/53180): Claude Code 2.1.120 `--resume` crashes due to `RW4` hook returning fewer keys than the destructure call expects. Workaround: use 2.1.116 or 2.1.119 until upstream ships a fix.
+
+## Open future work
+
+- Session-picker-as-segment (filed in `todo/session-segment.md`)

claudewheel-0.3.0/CLAUDE.md

@@ -0,0 +1,45 @@
+# claudewheel
+
+A TUI launcher for Claude Code: pick a profile, model, directory, MCP mode, and permissions from a horizontal segment bar, then launch.
+
+## Release workflow
+
+This project uses [rlsbl](https://github.com/smm-h/rlsbl) for release orchestration.
+
+- Update CHANGELOG.md with a `## X.Y.Z` entry describing changes
+- Run `rlsbl release [patch|minor|major]` to bump version and create a GitHub Release
+- CI handles `npm publish` automatically via OIDC Trusted Publishing (no tokens needed)
+- First publish must be done locally: `npm login && npm publish --access public`
+- After first publish, configure Trusted Publishing on npmjs.com (package settings)
+- Never run `npm publish` manually after Trusted Publishing is configured
+- Use `rlsbl release --dry-run` to preview a release without making changes
+
+## Architecture
+
+- `claudewheel/renderer.py` -- TUI rendering: segment bar, fan-out options, viewport scrolling, minimap, edge arrows
+- `claudewheel/app.py` -- TUI event loop, keyboard handling, SIGWINCH resize
+- `claudewheel/segment.py` -- Segment/SegmentBar dataclasses, option discovery
+- `claudewheel/config.py` -- ConfigManager: loads/saves JSON configs, key migration, schema-versioned value migrations
+- `claudewheel/defaults.py` -- All DEFAULT_* dicts (config, segments, options, state, themes)
+- `claudewheel/theme.py` -- ThemeColors dataclass, hex-to-ANSI parsing
+- `claudewheel/terminal.py` -- Raw terminal I/O, key reading, alt screen
+- `claudewheel/constants.py` -- Paths, ANSI escape sequences
+- `claudewheel/launch.py` -- Builds the exec command from selections
+- `claudewheel/cli.py` -- CLI argument parsing, one-shot commands
+
+## Config system
+
+- Config files live in `~/.claudelauncher/` (config.json, segments.json, options.json, state.json, themes/)
+- On startup, `_migrate()` adds missing keys from DEFAULT_* without overwriting user values
+- `_run_versioned_migrations()` applies one-time value fixes keyed by `_schema_version` in config.json
+- New migrations go in the `_MIGRATIONS` list in config.py with an incremented version number
+
+## Viewport scrolling
+
+When the segment bar overflows the terminal width, the renderer activates a scrolling viewport:
+- `_compute_bar_layout()` pre-computes logical column positions for all segments
+- `_compute_viewport()` centers the focused segment with ARROW_MARGIN (4 chars) reserved on each side
+- Segments outside the viewport are skipped; partially visible ones are clipped at the margins
+- Edge arrows show off-screen segment counts; minimap shows colored squares in the top-right
+- Config key `"minimap"` controls visibility: `"auto"` (only when scrolling) or `"always"`
+- Theme section `"overflow"` controls arrow/minimap colors and the minimap character

claudewheel-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smm-h
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claudewheel-0.3.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: claudewheel
+Version: 0.3.0
+Summary: TUI launcher for Claude Code
+Project-URL: Homepage, https://github.com/smm-h/claudewheel
+Project-URL: Repository, https://github.com/smm-h/claudewheel
+Author-email: smm-h <smmh72@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,config,launcher,rlsbl,tui
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10