A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.

It is for developers who keep several Claude Code profiles on one machine -- separate accounts, plans, or permission setups -- and want to choose between them without editing config files or exporting environment variables by hand. Each profile is its own CLAUDE_CONFIG_DIR holding its own OAuth token, settings and permission rules, and claudewheel patch-profiles reconciles every managed profile back to one canonical guardrail model.

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 machine-wide sessions overview (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 does not seed 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 see every Claude Code session on this machine as a framed table -- one row per session, gathered across every profile claudewheel discovers (the vanilla default profile included) plus every session recorded in the lifecycle store under ~/.claudewheel/shared/lifecycle/. Nothing on the bar decides what it shows. The columns are the session's name, its state, its kind, its working directory, the Claude Code version, the model, how long ago it started, and its resident memory in MiB; the session you are sitting in is marked with a *.

The state is the registry's own status wherever a process is still running (working, idle, shell, waiting, or unverified when the process identity could not be checked) and what the lifecycle store recorded otherwise: starting, crashed, exited, or the mark you gave it (on-hold, blocked, done). A running process always beats a recorded mark. Finished sessions -- done and exited -- are hidden until you ask for them.

It is a snapshot, not a live monitor: both stores are read when the screen opens and again only when you ask, so nothing renumbers under the cursor.

• Up / Down, Page Up / Page Down, Home / End -- move the focus (clamped, never wrapping)
• Left / Right -- scroll the columns sideways, for a terminal narrower than the table
• Enter -- expand the focused row into its session id, pid, profile, config directory and transcript path
• a -- show the finished sessions too, and hide them again
• m, then h / b / d / c -- mark the focused session on hold, blocked or done, or clear its mark
• p -- prune: delete the registry files of the sessions that crashed. Liveness and file identity are both re-checked at that moment, so a session that started while the screen was open keeps its file
• r -- read both stores again
• q or Esc -- close and return to the segment bar

Opening the screen also writes two things into the lifecycle store, both idempotent: an end for every session that died without recording one, and the display name of each live session, which exists nowhere else once its process is gone.

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. --print-prompt) 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

Key	Label	Controls
profile	Profile	Maps to CLAUDE_CONFIG_DIR (e.g. ~/.claude-personal)
github	GH	Selects the GitHub account; gh auth token --user <acct> exported as GH_TOKEN
version	Ver	Picks the Claude Code binary in ~/.local/share/claude/versions/
model	Model	Passes the model id as --model; an Opus/Sonnet [1m] suffix selects 1M-context
directory	Dir	Working directory to cd into before launch
mcp	MCP	MCP profile mode (default, strict)
permissions	Perms	Permission mode passed to Claude Code. Offered: bypass, default. Accepted when pinned in options.json or passed with --set: plan, auto

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.

Model discovers itself: claudewheel asks the Anthropic API which models your account may use, appends any it has not seen to options.json, and orders the picker by release date, newest first. The list only ever grows -- a model that stops being served stays selectable, and an offline launch offers everything a previous one discovered.

Commands

Command	Description
health	run diagnostic health checks on profiles, tokens, and hooks, then exit
config	open the ~/.claudewheel/ config directory in your $EDITOR
versions	list all installed Claude Code versions, marking the current symlink target
install	download and install a specific Claude Code version
uninstall	delete an installed Claude Code version binary from the versions directory
reset-options	delete options.json so it regenerates from defaults
show	print a summary of current segment selections, theme, and recent directories
migrate	move session data files from one profile to another, optionally filtered by UUID
stats	report shared-store stats and clean up legacy data
mv	rename a project directory and migrate session data
import	import session data from an external Claude Code directory
deploy-hooks	deploy built-in hook scripts to the ~/.claudewheel/scripts/ directory
patch-profiles	reconcile every managed profile and shared-settings.json to EXACTLY the canonical guardrail model (hooks, disallowedTools, permissions deny/ask, canonical settings keys); prunes drift and user-added extras -- the old additive, extras-preserving behavior is gone. Deploys any missing guardrail hook scripts. The 'default' profile (~/.claude) is never touched. Preview with --dry-run; writing needs a terminal or --approve-consequential.
reconcile-permissions	reconcile every managed profile and shared-settings.json to EXACTLY the canonical guardrail model (hooks, disallowedTools, permissions deny/ask and the canonical settings keys made exact; allow keeps only its non-conflicting entries); prunes all drift and user-added extras. The 'default' profile (~/.claude) is never touched. Pass --dry-run to preview the per-target diff without writing; writing needs a terminal to confirm at, or --approve-consequential.
purge-plugins	remove the Claude Code plugin tree from the selected profiles: the official-marketplace clone and every plugin installed from it, six to ten megabytes per profile. Opt-in and separate from the canonical reconciliation, which is exact and would otherwise delete plugin state on every run. Names the marketplaces and plugins it finds before removing them; --dry-run reports the inventory without touching anything. New launches do not collect a new tree -- the launch environment suppresses the auto-install, one-way per profile. The 'default' profile (~/.claude) is never touched.
launch	start the interactive TUI launcher to select a profile, model, and directory
profile	create, inspect, rename, delete, and manage Claude Code profiles and their stored tokens
profile create	run the create-profile wizard in one continuous alt-screen session: prompt for the profile name, config directory and launch options, write the profile directory together with its symlinks into the shared store, then drive an interactive Claude Code OAuth login so the profile is authenticated before you leave. Requires a real terminal, and prints the summary and auth outcome afterwards
profile delete	remove a registered profile: hand its directory to saferm, which archives it (the stored token among it) and then removes it, unlink its shared-store symlinks, drop its options.json registration, and clear any last_config reference in state.json. Prints the archive handle that restores it. Refuses a profile holding a live interactive Claude Code session unless --force-delete (background jobs and daemons do not block it), and takes conversation history only with --force-delete-data. saferm must be installed: without it the deletion would be irreversible, so it is refused rather than performed
profile show	print a detailed report for one profile: whether its directory exists on disk, whether it is registered or pinned in options.json, the state of its stored token, its resolved configuration and the session data it holds. Inspects default (~/.claude) like any other profile, and exits non-zero when the name matches no directory, registration or token
profile rename	move a profile to a new name, taking its directory (with the token stored inside it), its options.json registration and its session data with it. Validates that the old name exists, that the new one is free in both the directory tree and the options file, and that it fits the lowercase-letters-digits-hyphens charset. Refuses a profile holding a live interactive Claude Code session, and the reserved name default
profile fix-auth	repair one profile's authentication: strip the session credentials that shadow its stored long-lived token so the token is used again. Says so plainly when there is nothing to repair, and refuses a name with no profile directory behind it
profile set-plan	declare which plan a profile's Claude account is on, without a prompt. Claude Code resolves its subscription tier from the launch environment and only from there when auth is a stored setup token, so an undeclared profile launches with the tier null and tier-dependent features failing closed. Writes both plan fields into the profile's token entry, leaving the token itself alone; the interactive picker in the create flow and the pre-launch prompt write exactly the same thing
profile check-tokens	read every discovered profile's own stored OAuth token and validate each one against the Anthropic API, then print a table of profile name, status and a truncated token preview. The status distinguishes a valid token from an invalid one, an unreachable API and an indeterminate answer, and profiles holding no token are listed too
permission	add, remove, and list permission rules across Claude profiles
permission add	Add a permission rule to a profile's settings.json. Takes a category (allow, deny, or ask) and a rule string such as Bash or Read(//home/**). Writes the rule into the specified category array. Use --profile to target a single profile or --all-profiles to apply the rule across every registered profile. Skips duplicates if the rule already exists in the category.
permission remove	Remove a permission rule from a profile's settings.json. Takes a category (allow, deny, or ask) and the exact rule string to delete. The rule is removed from the specified category array and the file is saved. Use --profile to target a single profile or --all-profiles to remove the rule from every registered profile. Reports whether the rule was found.
permission list	List permission rules from a profile's settings.json. Displays rules in grouped or flat format controlled by --format. Use --category to filter output to a single category (allow, deny, or ask). Use --profile to inspect a single profile or --all-profiles to show rules from every registered profile, with each profile's rules displayed under a header. The framework-owned --json answers a machine instead: one envelope carrying every listed profile, whatever --format the human form would have used.

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

Which session a launch starts in is one selection with five alternatives, exactly one of which is elected per launch. Four of them forward to Claude Code; the fifth is the plain launch a bare c performs:

c --cont                              # --continue: resume the most recent session
c --resume 0123abcd                   # --resume <id>: jump to a specific session
c --resume ""                         # --resume: open Claude Code's own session picker
c --picker                            # browse this profile's sessions and pick one
c --print-prompt "summarize this repo" # --print: non-interactive print mode
c --new-session                       # start a new session -- what a bare `c` does

Three of them carry a short form: -c, -r <session> and -p <prompt> are --cont, --resume and --print-prompt. A short takes its value as the next argument, so -r 0123abcd is the spelling and -r=0123abcd is not one.

Naming two of them is refused: --cont --picker is --cont and --picker are mutually exclusive, from the parser rather than from claudewheel.

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

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

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

Config directory

~/.claudewheel/ layout:

Path	Purpose	Auto-written?
config.json	Theme, enabled segments, default flags, health-check switch, minimap mode	No (user-edited)
segments.json	Segment definitions (label, width, wrap, searchable, etc.)	No
options.json	Values, metadata, and discovery configs per segment	Only via + UX
state.json	last_config, recent_dirs, launch_count, npm cache	Yes, every launch
themes/*.json	Colour schemes (dark.json, light.json ship by default)	No
hooks/*	Executable scripts -- see below	No

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 pinned 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:

Key	Controls
arrow_fg	Colour of the <N / N> edge scroll indicators
minimap_fg	Colour of unselected minimap squares
minimap_focused_bg	Background highlight on the focused minimap square
minimap_char	Character used for minimap squares (default ▪)

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.