claudewheel 0.25.0

TUI launcher for Claude Code with profile, GitHub account, version, model, directory, MCP, and permission switching.

Installation

Install from PyPI:

pipx install claudewheel

Or with uv:

uv tool install claudewheel

Requires Python 3.11+.

Upgrading from the Node package

Early versions of claudewheel were distributed as an npm package (npm install -g claudewheel). The Node wrapper is deprecated -- it only exists as a thin shim that calls python3 -m claudewheel. Install the Python package directly instead:

npm uninstall -g claudewheel    # remove the old Node wrapper
pipx install claudewheel        # install the Python package

If you have the old Node binary at /opt/homebrew/bin/claudewheel or a similar npm global path, removing the npm package will clean it up.

Quick start

claudewheel         # launch the TUI
claudewheel --help  # show all flags

The first run creates ~/.claudewheel/ populated with defaults (config, segments, options, themes).

The segment bar

The TUI is a single horizontal "segment bar" rendered at the vertical centre of the terminal. Each segment is a labelled cell whose value can be cycled, searched, or freely edited. Above and below the focused segment, a vertical "fan-out" shows the other available options dimmed in the segment's accent colour. Pressing Enter on any segment launches Claude Code with the current selections.

Keys:

• Left / Right -- move focus between segments (also exits freeform edit mode)
• Up / Down -- cycle the focused segment's value (blank state --- is part of the ring)
• Type characters -- start fuzzy search (on searchable segments) or freeform edit (on freeform segments)
• Tab -- accept the current fuzzy match and advance to the next segment
• Backspace -- delete a search/edit character (on a non-empty selected value, starts edit mode)
• Esc -- cancel the in-progress search or edit
• S (uppercase) -- open the sessions overview for the selected profile (see below)
• Enter -- launch
• q or Ctrl-C -- quit without launching

Search shows the matched characters in the search-match colour. The search buffer turns red when no option matches.

An uppercase S typed with nothing in the search buffer no longer seeds a fuzzy search -- it opens the sessions overview. Lowercase s still searches, and once a search is in progress S is an ordinary character again.

The sessions overview

Press uppercase S from anywhere on the bar to list every Claude Code session registered under the selected profile -- name, working directory, uptime, resident memory, and the session you are sitting in marked. The focused row expands to show its pid, session id and Claude Code version.

It is a snapshot, not a live monitor: the registry is read when the screen opens and nothing refreshes under the cursor.

• Up / Down -- move the focus (clamped, never wrapping)
• r -- re-read the registry into a new snapshot
• p -- prune: delete the registry files of the sessions whose processes are provably gone. Liveness and file identity are both re-checked at that moment, so a session that started while the screen was open keeps its file
• q or Esc -- close and return to the segment bar

Client selection

Before the segment bar, the interactive launcher shows a Client step: choose which client to launch --- claude (the official Claude Code CLI) or miniclaude (the miniclaude REPL). The cursor starts on the default_client configured in config.json (default: claude). A client whose binary is not installed is shown with a (not installed) suffix rather than hidden; selecting it still launches and fails with a clear message.

Pass --client <name> to skip the step and choose explicitly; non-interactive launches (e.g. -p) use default_client without prompting. When the selected client is not claude, the version step is skipped --- the version selects a claudewheel-managed claude binary, which does not apply to other clients.

Narrow terminals

When the segment bar is wider than the terminal, the renderer switches to a scrolling viewport:

• The focused segment is centered horizontally
• Edge arrows (<2, 3>) show how many segments are off-screen in each direction
• A minimap in the top-right corner shows all segments as small colored squares; the focused one has an opaque background highlight
• Partially visible segments at the viewport edges are clipped rather than wrapped

The viewport activates automatically and deactivates when the terminal is resized wider. All rendering is identical to the non-scrolling case when the bar fits.

Segment types

Profile, GitHub, and Model are creatable: their option lists end with a + sentinel that prompts for a new value and persists it to options.json. Directory is freeform: you can type any path. Version pulls a live npm listing merged with the locally installed binaries.

Commands

Segment overrides

Every enabled segment gets its own --<key> flag. These pre-fill the TUI:

c --profile myprofile --github myhandle
c --directory ~/Projects/foo --model claude-opus-4-7

If the override set covers every required segment, the TUI is skipped entirely and Claude Code launches directly.

Session passthrough

Mutually exclusive flags forwarded to Claude Code:

c -c                       # --continue: resume the most recent session
c -r                       # --resume: open Claude Code's session picker
c -r 0123abcd              # --resume <id>: jump to a specific session
c -p "summarize this repo" # --print: non-interactive print mode

These compose with segment overrides: c --profile personal -r opens the picker against the personal profile.

Print mode (-p) skips the TUI and launches Claude Code non-interactively. Extra flags after -- are passed through:

c -p "explain auth.py" -- --output-format json --allowedTools "Read,Bash"

Config directory

~/.claudewheel/ layout:

Defaults are regenerated on first run if any file is missing.

On startup, missing keys from the current defaults are merged into existing files (config, segments, themes) without overwriting user values. Schema-versioned migrations handle value changes that must be applied once (e.g. correcting a default).

Hooks

Drop an executable script into ~/.claudewheel/hooks/ whose name starts with pre-launch (e.g. pre-launch-token-refresh). It runs immediately before exec, with the chosen segment values exported as CL_<KEY> environment variables:

#!/usr/bin/env bash
# ~/.claudewheel/hooks/pre-launch-warn-work
if [[ "$CL_PROFILE" == "work" && "$CL_DIRECTORY" == "$HOME/Projects/personal-thing" ]]; then
    echo "Refusing to use the work profile on a personal project." >&2
    exit 1
fi

A nonzero exit aborts the launch (and prevents launch_count from being incremented). Hooks have a 10-second timeout.

Adding new options

• Profile / GitHub / Model: cycle the segment to its + sentinel, press Enter, type the new value. It is appended to options.json under the segment's values list and selected.
• Direct edit: open ~/.claudewheel/options.json and add to the relevant segment's values array. For profiles you also need a metadata.<name>.config_dir entry.
• Install a Claude Code version: run c --install <version> or pick a not-yet-installed version in the TUI and confirm the install prompt. Binaries land in ~/.local/share/claude/versions/<version>.

Themes

Two themes ship with the launcher: dark.json and light.json in ~/.claudewheel/themes/. Switch by setting theme in config.json to the file's basename. Themes define per-segment foreground / focus / option / unavailable colours and the search highlight palette. Add a new theme by writing another themes/<name>.json and pointing config.json at it.

Themes also include an overflow section for viewport chrome:

Tests

cd /home/m/Projects/claudewheel
python3 -m unittest discover tests/

240+ stdlib unittest tests covering segment cycling, fuzzy matching, requires-evaluation, install/manifest parsing, discovery merge logic, viewport scrolling, and config migration. Runs in under one second.