#Getting Started

This tutorial walks through installing claudewheel, creating a profile, navigating the segment bar, and launching your first Claude Code session.

#Prerequisites

• Python 3.11 or later
• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• A terminal that supports ANSI colors

#Install claudewheel

Install from PyPI using pipx (recommended) or uv:

pipx install claudewheel

uv tool install claudewheel

Verify the installation:

claudewheel --help

If you previously used the deprecated npm package, remove it first:

npm uninstall -g claudewheel

#First run

Launch the TUI:

claudewheel

On the first run, claudewheel creates ~/.claudewheel/ and populates it with default configuration files: config.json, segments.json, options.json, state.json, and a themes/ directory with dark and light color schemes.

Before the segment bar appears, you are prompted to choose a client -- claude (the official Claude Code CLI) or miniclaude (an alternative REPL). Select claude to continue.

If no profiles exist yet, the launcher shows an empty Profile segment. You can create one from inside the TUI or ahead of time with the profile wizard.

#Create a profile

A profile is an isolated Claude Code configuration directory (~/.claudewheel/profiles/<name>/) with its own settings.json, OAuth credentials, and permission rules. Profiles let you maintain separate settings for different contexts -- personal projects, work, experimentation -- without them interfering with each other.

Run the profile wizard:

claudewheel profile create

The wizard walks through several steps:

1. Name -- a lowercase identifier (letters, digits, hyphens). This becomes both the directory name and the label in the segment bar.
2. Clone from -- optionally copy settings from an existing profile or start from the defaults template.
3. Advanced options -- toggle hook wiring, shared store symlinks, recap, auto-memory, cleanup period, and Co-Authored-By attribution.
4. Authentication -- after the profile directory is created, the wizard launches Claude Code under the new profile so you can complete OAuth login.

Once the wizard finishes, the new profile appears in the Profile segment the next time you launch the TUI.

You can also create a profile from inside the TUI itself: cycle the Profile segment to the + sentinel (the last entry in the list), press Enter, and type the new name.

#Understanding the segment bar

The segment bar is the core of the claudewheel interface -- a horizontal row of labeled cells rendered at the vertical center of your terminal. Each cell controls one aspect of the Claude Code session you are about to launch.

#The segments

#Navigation

• Left / Right -- move focus between segments.
• Up / Down -- cycle the focused segment through its available values. A blank --- entry is part of the cycle.
• Type characters -- on searchable segments (Profile, Model), start a fuzzy search. On freeform segments (Directory), type any value directly.
• Tab -- accept the current fuzzy match and advance to the next segment.
• Backspace -- delete a search or edit character. On a non-empty selected value, enters edit mode.
• Esc -- cancel the in-progress search or edit.
• S (uppercase) -- open the machine-wide sessions overview.
• Enter -- launch Claude Code with the current selections.
• q / Ctrl-C -- quit without launching.

An uppercase S typed with nothing in the search buffer does not start a fuzzy search -- it opens the sessions overview described below. Lowercase s still searches, and inside an in-progress search S is an ordinary character again.

#The sessions overview

Uppercase S opens a framed table of every Claude Code session on this machine, one row per session: every profile claudewheel discovers is read, the vanilla default profile included, and so is every session recorded in the lifecycle store under ~/.claudewheel/shared/lifecycle/. The selection in the bar does not narrow it. The columns are name, state, kind, working directory, Claude Code version, model, how long ago the session started, and resident memory in MiB; a * marks the session you are sitting in.

A session's state comes from whichever store can answer. Where a process is still running it is Claude Code's own status -- working, idle, shell, waiting, or unverified when the process identity could not be checked against the kernel. Where nothing is running it is what claudewheel recorded: starting for a session that has only just begun, crashed for one that died without saying so, exited for one that ended cleanly, or the mark you gave it. A running process always wins over a recorded mark. The finished states, done and exited, are hidden until you press a.

The screen is a snapshot taken when it opens: nothing re-reads either store under the cursor, so rows never renumber while you move through them.

• Up / Down, Page Up / Page Down, Home / End -- move the focus.
• Left / Right -- scroll the columns sideways when the terminal is narrower than the table. The handle along the bottom border shows how much of it you are seeing.
• Enter -- expand the focused row into three more lines: its session id, its pid, profile, name source and config directory, and its transcript path.
• a -- show the finished sessions as well, and hide them again.
• m -- mark the focused session, then h for on hold, b for blocked, d for done, or c to clear the mark. A mark is your own word about a session nothing is running; any other key cancels.
• p -- prune: delete the registry files left behind by the sessions that crashed (a kill -9, a reboot). Both the process and the file are re-checked at that moment, so a session that started while the screen was open is never pruned.
• r -- read both stores again.
• q / Esc -- close the overview and return to the segment bar.

Opening the screen also records two things, both idempotent: an ended event for any session that died without writing one, and the display name of each live session -- the registry is the only place that name exists, and it goes away with the process.

#Fan-out display

Above and below the focused segment, a vertical "fan-out" shows other available options dimmed in the segment's accent color. This lets you see all choices at a glance without cycling through them one by one.

#Narrow terminals

When the bar is wider than your terminal, the renderer switches to a scrolling viewport. The focused segment stays centered, edge arrows (<2, 3>) indicate how many segments are off-screen, and a minimap in the top-right corner shows all segments as colored squares.

#Launch a session

Once every segment has a value you are satisfied with, press Enter. claudewheel runs any pre-launch hooks, resolves your selections into the correct binary path, environment variables, and flags, then execs Claude Code.

Your selections persist in state.json, so the next time you launch, the bar starts with your previous choices pre-filled.

#Skipping the TUI

If you already know what you want, pass segment values as flags to skip the TUI entirely:

claudewheel --profile work --model claude-opus-4-7 --directory ~/Projects/myapp

When every required segment is covered by flags, the TUI is skipped and Claude Code launches directly.

#Session passthrough

Which session a launch starts in is one selection over five alternatives, and exactly one of them is elected per launch:

claudewheel --cont                              # resume the most recent session
claudewheel --resume 0123abcd                   # resume a specific session by ID or title
claudewheel --resume ""                         # open Claude Code's own session picker
claudewheel --picker                            # browse this profile's sessions and pick one
claudewheel --print-prompt "summarize this repo" # non-interactive print mode
claudewheel --new-session                       # start a new session, as a bare launch does

Naming two of them is a parse error naming both, and naming none of them is the plain launch --new-session spells out.

--cont, --resume and --print-prompt also answer to -c, -r <session> and -p <prompt>. A short form takes its value as the next argument, so -r 0123abcd works and -r=0123abcd does not.

These compose with segment overrides:

claudewheel --profile personal --picker      # session picker against the personal profile

#Common workflows

#Switching profiles

You have two main ways to switch between profiles:

• In the TUI -- focus the Profile segment (Left/Right keys) and cycle through options (Up/Down) or type to fuzzy-search.
• Via flags -- pass --profile <name> to pre-select or skip selection entirely.

Each profile carries its own settings.json with permissions, hooks, and preferences. Switching profiles is how you move between different permission setups (strict for production work, relaxed for experiments) or different GitHub accounts.

#Changing models

Focus the Model segment and cycle or search. Models are listed from options.json, newest release first. The [1m] suffix on a model name enables the extended 1M-token context window and sits directly under the model it applies to.

That list keeps itself current: claudewheel asks the Anthropic API which models your account may use and appends any it has not seen before. Nothing is ever removed, so a model that stops being served stays selectable and an offline launch still offers everything a previous one discovered. Pinned models stay at the top of the list, ahead of the date ordering.

To add a model the API does not list at all, cycle to the + sentinel and type the full model ID. It is saved to options.json for future launches.

Some models need a minimum Claude Code version. One of those shows up dimmed when the version you are about to launch -- the one selected in the Version segment, or whatever the claude symlink points at when nothing is selected -- is older than the model needs, and pressing Enter on it refuses the launch instead of starting a session that would fail. Select a new enough version in the Version segment, or install one with claudewheel install <version>, and the model lights up again.

From the command line:

claudewheel --model claude-opus-4-7

#Running health checks

Verify that your profiles, tokens, hooks, and permissions are correctly configured:

claudewheel health

This checks OAuth token validity, hook script deployment, permission array consistency against the canonical guardrail model, and file permissions.

#Managing versions

List installed Claude Code versions:

claudewheel versions

Install a specific version:

claudewheel install 2.1.119

In the TUI, the Version segment shows both installed and available versions. Selecting a not-yet-installed version prompts you to install it.

#Keeping guardrails up to date

After upgrading claudewheel, reconcile your profiles with the latest guardrail rules:

claudewheel reconcile-permissions --dry-run   # preview changes
claudewheel reconcile-permissions             # apply, confirming at the prompt
claudewheel patch-profiles                    # sync hooks and disallowedTools

Both writing forms confirm before they touch anything -- the reconciliation is exact, so it prunes hand-added permission rules and hook entries and nothing is backed up. From a script, where there is no terminal to confirm at, pass --approve-consequential.

#Next steps

• CLI Reference -- full documentation for every command and flag
• Guardrails -- how the enforcement tiers, hooks, and permission arrays work
• API Reference -- module-level documentation for contributors