claudewheel

Pick a profile. Pick a model. Launch.

TUI launcher for Claude Code: pick a profile, model, directory, and permissions from a segment bar, then launch.

Segment Bar Launcher

Visual TUI with horizontal segments for profile, model, directory, MCP mode, and permissions. Navigate with arrow keys, confirm with Enter.

Multi-Profile Management

Manage multiple Claude Code profiles with isolated settings, permissions, and MCP configurations. Create, delete, and migrate sessions between profiles.

Pre-Launch Health Checks

Diagnostics that verify API tokens, hook scripts, file permissions, and symlink integrity before launching a session.

Viewport Scrolling

Segment bar adapts to narrow terminals with automatic scrolling, edge arrows showing off-screen segments, and a colored minimap.

Customizable Themes

Dark and light themes with hex color support, configurable per-segment colors, and theme-aware rendering throughout the TUI.

A TUI launcher for Claude Code that presents a horizontal segment bar for selecting a profile, model, directory, MCP mode, and permissions before launching a session. Selections persist across launches, and the bar adapts to narrow terminals with viewport scrolling and a minimap.

#Documentation

CLI Reference -- all commands, flags, and arguments
API Reference -- auto-generated module and function docs
Guardrails -- enforcement tiers, subagent handling, command-string caveats, and upgrading profiles

#Overview

claudewheel manages multiple Claude Code profiles, each with isolated settings and permissions stored in ~/.claude-<name>/settings.json. The TUI renders a segment bar where each segment fans out into selectable options. Before launching, optional health checks verify API tokens, hook scripts, and file permissions.

Configuration lives in ~/.claudewheel/ (config.json, segments.json, options.json, state.json, and a themes/ directory). Themes support hex color definitions with dark and light variants.

#API Reference

The claudewheel API covers configuration, profile discovery, TUI rendering, terminal I/O, segment bar layout, theme parsing, and session launching. Modules are organized by concern: config and defaults handle persistent settings, renderer and terminal drive the display, segment defines the bar data model, launch builds the exec command, and profile resolves Claude Code profile directories.

#claudewheel

Package version detection from package.json or installed metadata.

#_default_package_json

python

def _default_package_json() -> _Path

Path to the repo-root package.json (one level above the package dir).

#_detect_version

python

def _detect_version(package_json=None, metadata_version=_version) -> str

Resolve the package version, preferring the repo-root package.json.

Resolution order (exact, not heuristic):

/../package.json -- present only in a source checkout (the wheel

packages only claudewheel/). In an editable/source checkout this file is authoritative and wins over possibly-stale installed metadata.

importlib.metadata.version("claudewheel") -- used for PyPI wheels,

where the repo-root package.json is absent.

"unknown" -- final fallback when neither source is available.

package_json and metadata_version are injectable for testing.