ccvitals

The vital signs of your Claude Code session — usage quota, context window, cost, git status and more, right in your terminal. Pure bash, zero Node, never blocks your prompt.

Why ccvitals

Install

Install ccvitals as a Claude Code plugin — no cloning or manual config required:

/plugin marketplace add educlopez/ccvitals
/plugin install ccvitals@ccvitals
/ccvitals:setup

/ccvitals:setup asks which modules you want, writes the config, and wires up settings.json automatically. Then restart Claude Code.

To reconfigure modules or switch to a two-line layout later:

/ccvitals:configure

Homebrew

brew install educlopez/tap/ccvitals
ccvitals          # interactive installer (or: ccvitals --all)

After brew upgrade ccvitals, run ccvitals --force once to relink. Remove with ccvitals uninstall.

Manual install (alternative)

If you prefer a git-clone workflow (symlinked install, instant git pull updates):

git clone https://github.com/educlopez/ccvitals.git
cd ccvitals
./install.sh

The installer shows an interactive menu where you pick which modules to enable:

ccvitals — Choose your modules:

  [x] 1) Directory      my-project
  [x] 2) Model          Opus 4.6
  [x] 3) Context        ░░░░░░░░░░░░░░░ 12%
  [x] 4) Usage quota    Max ██████░░░░ 58% 3h42m
  [x] 5) Git status     (main | 3 files +42 -8)

  Toggle: enter number (e.g. 4). Accept: Enter. All: a

Then restart Claude Code.

Install options

# Force reinstall (relink script + overwrite settings.json statusLine key)
./install.sh --force

# Skip menu — install all modules
./install.sh --all

# Skip menu — pick specific modules
./install.sh --modules=model,context,usage

# Two-line layout (these modules drop to row 2)
./install.sh --all --line2=context,usage,rtk,mode,lines

# Combine flags
./install.sh --force --modules=context,usage,git

The interactive installer also asks, after you pick your modules, which of them should drop to a second line (enter their numbers, or press Enter for a single line).

Update

cd ccvitals && git pull

Because the script is symlinked, git pull updates the statusline instantly — no reinstall needed. Restart Claude Code to see the new version.

Change modules later

Run /ccvitals:configure (plugin install) or re-run the installer with --force. You can also edit ~/.claude/.statusline-config.json directly:

{
  "modules": ["directory", "model", "context", "usage", "git", "rtk", "codegraph", "lines", "mode", "cost", "duration", "speed", "vim", "agent", "pr", "weekly"]
}

Remove any module from the array to hide it.

Two-line layout

Add an optional modules_line2 array to render those modules on a second row. Modules stay in modules for line 1; anything in modules_line2 drops to line 2. Omit modules_line2 entirely for a single line.

{
  "modules": ["directory", "model", "git", "codegraph"],
  "modules_line2": ["context", "usage", "rtk", "mode", "lines"]
}

Renders as:

my-project | Opus 4.6 | (main | 3 files +42 -8) | ⬡ 11.7k
███░░ 21% ⚠ | Max 58% 3h42m | rtk 86.8%↓ | ⚡ xhigh | +264 -195

Module order

Add an optional module_order array to control the left-to-right display order of modules. Any enabled module not listed is appended after the listed ones in the default order — so you can pin just the modules you care about without listing everything.

{
  "modules": ["directory", "model", "context", "git", "cost"],
  "module_order": ["cost", "git", "context", "model", "directory"]
}

Rules:

• Unknown names in module_order are silently ignored (forward-compatible with future modules).
• modules_line2 assignment is independent — module_order controls sequence, not which line a module lands on.
• Works with powerline mode.
• When module_order is absent the default order is preserved byte-for-byte.

Modules

rtk, codegraph, lines, mode, cost, duration, speed, vim, agent, pr, weekly, pace, cache, tools, agents, todos, workflows, daily, compactions, tokens, thinking, mcp, spend, and session are opt-in (off by default). rtk and codegraph cache their output (rtk 60s globally, codegraph 15s per project) and refresh in the background, so they don't slow down rendering; each silently hides itself when its CLI isn't installed. tools, agents, todos, and workflows share one tail -n 300 + one jq invocation of the transcript per render, keeping the cost bounded regardless of transcript size. compactions uses grep -c on the full transcript (fast, O(n) line scan). tokens processes only new lines since the last render (incremental cache, negligible per-render cost). mcp uses mtime-based file cache so parsing only happens when config files change.

Features

• Modular — pick only the sections you want
• Context window — progress bar + percentage of context used
• Usage quota — 5-hour utilization with color-coded bar (Pro/Max/Team)
• Reset timer — countdown to when your 5h quota resets
• 7-day warning — shows weekly utilization when above 70%
• Git status — branch name, changed files count, lines added/removed
• Plan badge — shows your subscription tier (Pro, Max, Team)
• Smart caching — usage data cached for 60s, refreshed in background
• Cross-platform — works on macOS, Linux, and WSL

Color coding

Themes

ccvitals ships with six built-in color presets plus a custom mode. Set the "theme" key in ~/.claude/.statusline-config.json:

default — classic 16-color ANSI (adapts to your terminal's palette; used when the key is absent)

pastel — soft lavender/cyan palette

tokyo-night — blue/purple night palette

catppuccin — Catppuccin Mocha

dracula — high-contrast Dracula

nord — arctic, cool-toned Nord

mono — bold/white only, no color

Why does default look different on my machine? The default theme emits classic 16-color ANSI codes, so your terminal's palette decides the final colors — it blends in with whatever theme your terminal uses. The named presets use fixed truecolor values and look identical in every terminal.

Switch theme by running /ccvitals:configure (plugin install) or editing the config directly:

{
  "modules": ["directory", "model", "context", "usage", "git"],
  "theme": "tokyo-night"
}

Per-project config

Create a .ccvitals.json file at your project's workspace root to override any global config keys for that project. Any key present in the project file wins; absent keys keep their global values.

{ "theme": "dracula", "smart": true, "modules": ["directory", "model", "context", "git"] }

Supported keys: modules, modules_line2, module_order, theme, colors, powerline, powerline_separator, context_display, pace_display, daily_budget, session_budget, spend_windows, weekly_split, smart, icons, responsive, git_operation, git_status_split, git_sha, git_stash, git_age.

The merge uses jq -s '.[0] * .[1]' (global * project). Values are only consumed as JSON data — never executed.

Powerline mode

Set "powerline": true in ~/.claude/.statusline-config.json to render each module as a shaded segment separated by the Nerd Font arrow glyph (U+E0B0, ``) instead of |:

{
  "modules": ["directory", "model", "context", "usage", "git"],
  "theme": "tokyo-night",
  "powerline": true
}

Segments alternate between two background shades drawn from the active theme. Each inter-segment boundary gets a  glyph whose foreground color matches the previous segment's background, creating a seamless chevron effect. A final trailing arrow resets to the terminal default background.

Nerd Font required — the `` glyph renders correctly only when your terminal uses a Nerd Font (e.g. JetBrainsMono Nerd Font, FiraCode Nerd Font, MesloLGS NF). Without one the separator appears as a box or question mark.

Subagent rows

When Claude Code spawns sub-agents (e.g. during /sdd-apply, multi-agent workflows, or background tasks), it shows an agent panel below the prompt. ccvitals replaces the default name · description · tokens row for each sub-agent with a richer, theme-aware row:

◐ code-reviewer  Reviewing the auth module for security issues  1.2k  myproject
✓ formatter  Formatting complete  5.2M  other

Each row shows:

• Status icon — ◐ CYAN (running), ✓ GREEN (completed), ✗ RED (stopped/failed), · GRAY (unknown)
• Label or name of the sub-agent
• Description — truncated so the whole row fits within the available terminal width
• Token count — 1.2k / 5.2M format; hidden when zero
• Project folder — basename of the sub-agent's working directory

This is enabled automatically when you install ccvitals via ./install.sh or /ccvitals:setup. The rows respect your active theme.

Disable subagent rows

To keep Claude Code's default sub-agent panel, remove the subagentStatusLine key from ~/.claude/settings.json:

jq 'del(.subagentStatusLine)' ~/.claude/settings.json > ~/.claude/settings.json.tmp \
  && mv ~/.claude/settings.json.tmp ~/.claude/settings.json

Custom separator

Override the separator glyph with any string via "powerline_separator":

{
  "modules": ["directory", "model", "context"],
  "powerline": true,
  "powerline_separator": "▶"
}

Use a plain ASCII fallback (e.g. "|" or ">") if you don't have a Nerd Font installed.

Custom colors

Set "theme": "custom" and supply a "colors" object with any of the seven color keys (red, green, blue, yellow, cyan, gray, magenta). Missing keys fall back to the default palette. Values must be #RRGGBB hex strings:

{
  "modules": ["directory", "model", "context", "usage", "git"],
  "theme": "custom",
  "colors": {
    "blue": "#7aa2f7",
    "green": "#9ece6a",
    "magenta": "#bb9af7",
    "cyan": "#7dcfff",
    "yellow": "#e0af68",
    "red": "#f7768e",
    "gray": "#565f89"
  }
}

Truecolor terminals (iTerm2, Kitty, WezTerm, most modern Linux terminals) display the full RGB palette. The default and mono presets use the classic 16-color ANSI codes and work on every terminal.

Module config keys

Some modules accept additional config keys in .statusline-config.json:

pace_display — quota forecast mode (pace module)

{ "pace_display": "eta" }

daily_budget — daily spend budget (daily module)

{ "daily_budget": 10 }

Optional USD budget for the daily module. When set, displays Σ $4.20/$10 with color: GREEN <50%, YELLOW <80%, MAGENTA <100%, RED ≥100%.

session_budget — per-session cost cap (cost module)

{ "session_budget": 5 }

Optional USD budget for the cost module. When set, the cost segment shows $1.50/$5.00 (current / cap) with color: GRAY <50%, YELLOW 50–79%, RED ≥80%.

When unset, cost renders exactly as before ($0.42 in GRAY).

spend_windows — windows shown by the spend module

{ "spend_windows": ["7d", "30d"] }

Controls which time windows the spend module displays. Supported values: "7d", "30d". Default: both.

{ "spend_windows": ["7d"] }

The spend module reads the per-day ledger that daily writes to ~/.claude/.ccvitals-daily/. Historical data only accumulates from when daily was first enabled — there is no automatic backfill of earlier transcripts.

weekly_split — per-model weekly breakdown (weekly module)

{ "weekly_split": true }

When true and the OAuth cache contains seven_day_opus/seven_day_sonnet utilization, displays 7d O:42% S:18% instead of the single progress bar. Falls back to the bar when per-model data is unavailable (note: requires the OAuth fetch path to have run at least once).

tools_skill_names — show skill name for Skill invocations (tools module)

{ "tools_skill_names": false }

When true (default), a pending Skill tool invocation renders its .input.skill argument (e.g. ⚒ deploy-to-vercel) in YELLOW instead of the generic label. Set to false to always show Skill in CYAN, like any other tool.

MCP tool names (mcp__server__tool) are always compacted to server:tool regardless of this setting.

smart — hide modules when their value isn't notable

{ "smart": true }

When true, modules only appear when their value is notable. Default: false (behavior identical to before).

All other modules are unaffected. ETA mode (pace_display: "eta") always shows when enabled.

icons — icon set

{ "icons": "ascii" }

responsive — trim line 1 to fit terminal width

{ "responsive": true }

When true and COLUMNS is set, ccvitals drops the lowest-priority modules from line 1 until the visible output fits within the terminal width. Priority order (dropped first → last):

thinking → mcp → codegraph → rtk → lines → duration → cost → speed → vim → weekly → daily → spend → tokens → compactions → pr → agent → mode → cache → pace → tools → agents → todos → workflows → git → usage → context → model → directory

Note: Powerline mode + responsive is not yet supported — responsive is silently skipped when powerline: true.

git extras — additional git detail (all default false)

Each option is a boolean key in .statusline-config.json (or .ccvitals.json):

Example — enable multiple extras at once:

{
  "modules": ["git"],
  "git_operation": true,
  "git_status_split": true,
  "git_sha": true,
  "git_stash": true,
  "git_age": true
}

All five extras use a single git status --porcelain pass (already needed for the base module). Only git_sha, git_stash, and git_age add one lightweight subprocess each.

session_turns — show turn counter in session module

{ "session_turns": true }

When true, the session module appends a turn counter derived from message_count in the hook state file (e.g. § my-refactor ·12). Default: false. Requires hooks to be installed.

Hooks integration

ccvitals ships an optional hook script (ccvitals-hook.sh) that Claude Code calls on every event. This is pure opt-in infrastructure: nothing is wired unless you ask.

What it enables

Claude Code hooks (v2.1.84+ for TaskCreated, v2.1.152+ for MessageDisplay) fire a script on session and message events. ccvitals-hook.sh listens and writes per-session state to ~/.claude/.ccvitals-state/<session_id>.json. Statusline modules read that file at zero parse cost — no extra process needed.

Currently powered by hooks:

Install (opt-in)

./install.sh --hooks            # wire hooks only (add to an existing install)
./install.sh --all --hooks      # all modules + hooks in one pass

Or use the interactive installer — it asks whether to wire hooks after the module menu.

The hook script is registered in ~/.claude/settings.json under the hooks key for these events: SessionStart, MessageDisplay, TaskCreated, PostCompact, Stop. Any existing hooks you have for those events are preserved — ccvitals only appends its entry if not already present.

Enable the session module

{ "modules": ["session", "model", "context", "git"] }

With turn counter:

{ "modules": ["session", "model", "context"], "session_turns": true }

The module is silently hidden when hooks are not installed or the state file is absent — no errors.

Uninstall

./uninstall.sh removes only the ccvitals hook entries from settings.json (matching by script path) and deletes ~/.claude/.ccvitals-state/. Your other hooks are untouched.

Privacy

All data stays local. The hook script reads event JSON from stdin and writes only to ~/.claude/.ccvitals-state/ — no network calls, no external services. State files are cleaned up automatically after 48 hours.

Requirements

• Claude Code CLI
• jq — JSON processor (install)
• git — to clone and update the repo
• bash 3.2+ (pre-installed on most systems)

The statusline itself uses curl at runtime to fetch your usage quota, but the installer no longer downloads anything — it links the cloned statusline.sh.

How it works

1. Claude Code pipes JSON context (model, workspace, context window) to the script via stdin
2. The script reads ~/.claude/.statusline-config.json to know which modules are enabled
3. For the usage/weekly modules: prefers rate_limits data straight from Claude Code's stdin JSON (zero-latency, no network). When absent, falls back to fetching quota from the Anthropic API with OAuth credentials:
   • macOS (Claude Code 2.x+): reads from the macOS Keychain using profile-specific service names
   • Fallback: reads from ~/.claude/.credentials.json (older Claude Code versions or non-macOS)
4. Usage data is cached locally (~/.claude/.usage-cache/usage.json) for 60 seconds to avoid blocking the statusline
5. Git info is gathered from the current workspace directory
6. Only enabled modules are rendered into the final colorized line

Multi-account setup

If you use CLAUDE_CONFIG_DIR to manage multiple accounts, the statusline respects it:

CLAUDE_CONFIG_DIR=~/.claude-work claude

The installer also respects CLAUDE_CONFIG_DIR — run it with the variable set to install for a specific account. Each account gets its own module config.

Compatibility

Uninstall

From the cloned repo:

./uninstall.sh

This removes the statusline symlink, module config, the statusLine key from your settings, and the usage cache directory. (The cloned repo is left untouched — delete it manually if you no longer want it.)

License

MIT