Skip to content
claudewheel
Updated Edit
On this page

claudewheel

Pick a profile. Pick a model. Launch.

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.

Get Started

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 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.

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: _Path | None=None, metadata_version: _Callable[[str], str]=_version) -> str

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

Resolution order (exact, not heuristic):

  1. <pkg>/../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.

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

where the repo-root package.json is absent.

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

package_json and metadata_version are injectable for testing.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search