@ttigger/claude-status

A portable Claude Code statusline HUD — model, project, git, context, and real usage limits in your terminal, plus desktop pings when a session finishes.

npx @ttigger/claude-status install

Why

Usage limits in the CLI — brings the claude.ai Session (5 h rolling) and Weekly (7 d) usage meters and their reset countdowns into every Claude Code session; no browser tab required.
At-a-glance usage gauges — Context, Session, and Weekly each render as a high-resolution bar (64 levels via Unicode sub-cell fills) over a solid track, so you read your remaining headroom straight from the fill instead of doing math on a percentage.
ping desktop notifications — juggling several sessions? Get a desktop notification the moment a turn finishes (only for turns over 30 s) or a session is blocked waiting for you — naming the project so you know which one to return to. On by default, quiet, zero-dependency. Details below.
One command, nothing to clone — npx @ttigger/claude-status install fetches and wires everything; works on any machine with Node ≥ 18.
4 curated styles — refined Clay claude default, soft-pastel mist, powerline neon, and ultra-compatible ascii.
Single-line adaptive layout — auto layout packs everything onto one line and gracefully wraps to two or three lines only when the terminal is narrow.
Theme-aware colors — reads ~/.claude/settings.json and mirrors Claude Code's light/dark/system theme; no manual palette config required.
cc launcher — a tiny cc shim that forwards all args to claude, saving keystrokes on every invocation.
cs short command — a built-in cs bin that runs the same CLI as claude-status (e.g. cs style claude, cs help cc).
Config with live preview — claude-status config set and claude-status preview let you tweak and instantly see the result in your actual terminal colors.
Pure Node, cross-OS — CommonJS, zero runtime dependencies, works on Windows, macOS, and Linux.

Quick Start

npx @ttigger/claude-status install

Then open a new Claude Code session. The HUD appears automatically at the top of every prompt.

The HUD

The default style is claude with the auto layout — a single adaptive line that packs onto one row on a wide terminal and only wraps to 2–3 rows when space runs out:

Opus 4.8·1M | claude-status | ⎇ main | Ctx █▉██████ 24% 47k | compact 60% | S ████▏███ 52% 3h12m | W ██▌█████ 31% 4d6h

On a narrow terminal the same data wraps (and sheds detail) automatically — see the claude style and the layout options below.

Element	What it shows
Model	Current model name, e.g. `Opus 4.8`. The `·1M` tag appears when the 1 M-token context window is active.
Project folder	The base name of the current working directory.
Git branch	Active branch name (blank when not in a git repo).
Context bar + %	A progress bar showing how full the context window is, plus a percentage and token count in thousands (e.g. `47k`).
Auto-compact remaining	The percentage of context headroom left before Claude Code triggers auto-compaction. This value is approximate — the threshold is configurable (default ~83.5 %) and may differ from Claude Code's internal trigger.
Session usage	Rolling 5-hour usage bar + percentage + countdown to reset (e.g. `3h12m`).
Weekly usage	7-day usage bar + percentage + countdown to reset (e.g. `4d6h`).

Cost estimate (API-key mode) & usage limits

In API-key / free usage the HUD can show a session cost estimate in place of the Session/Weekly bars:

$0.0123 est · 47k ctx

The $ value is cost.total_cost_usd from Claude Code's statusline data, in USD. The · 47k ctx part is the current context-window occupancy (tokens currently in context) — not cumulative session tokens.

This is an estimate

The dollar figure is a client-side estimate of the current session, computed locally from token counts. It is not a bill, not an account balance, and may differ from the real charge on the Anthropic Console. The est marker is always shown precisely to signal this — treat the number as a rough running estimate, not an invoice.

When it appears

The cost estimate appears only when Claude Code provides no rate_limits:

API-key / free usage — there are no subscription rate limits, so the estimate is shown.
A subscriber's very first render, before they send their first message.

Once a subscriber sends a message and rate_limits appear, the cost element automatically disappears and the normal Session (5 h) / Weekly (7 d) bars return. Subscribers stay clean — no dollar figures during normal subscription use.

`LIMIT` at 100%

When a Session or Weekly meter reaches 100% usage, it switches from a bar to a red LIMIT marker that still shows the reset countdown:

S LIMIT 3h12m

This just makes "you've hit the cap" obvious.

What it can't show

The HUD cannot display, because Claude Code does not expose this data to statusline scripts:

Usage-credit balance / remaining credit
Monthly spend limit
Current account balance
Auto-reload status

None of that billing data is available to statusline scripts, so it is not (and cannot be) shown — including by the LIMIT marker.

Hiding the cost estimate

The cost element is controlled by elements.cost (default true). To hide it:

claude-status config set elements.cost false

With it off, the old — waiting for first message note returns in no-rate_limits situations.

Styles

Four styles are available. Choose with claude-status style <name> (shortcut) or claude-status config set style <name>.

`claude` (default — refined Clay design)

Default layout is auto (single adaptive line). Shown here as three (grouped lines) to make the parts clear; labels are Ctx / S / W and the bar is 8 cells wide:

Opus 4.8·1M | claude-status | ⎇ main
Ctx █▉██████ 24% 47k | compact 60%
S ████▏███ 52% 3h12m | W ██▌█████ 31% 4d6h

`mist`

Soft pastel pills (Catppuccin / Rosé Pine inspired):

Opus 4.8·1M |  claude-status  |  ⎇ main 
 Ctx █▉██████ 24% 47k  | compact 60%
 S ████▏███ 52% 3h12m  |  W ██▌█████ 31% 4d6h

`neon`

Powerline segments (Tokyo Night inspired). Rounded ◖◗ caps work in any Unicode terminal — no Nerd Font required; install one (and set CLAUDE_STATUS_NERD=1) for sharper powerline glyphs:

◖ Opus 4.8·1M ◗◖ claude-status ◗◖ ⎇ main ◗
◖ Ctx █▉██████ 24% 47k ◗◖ compact 60% ◗
◖ S ████▏███ 52% 3h12m ◗◖ W ██▌█████ 31% 4d6h ◗

`ascii` (most compatible)

Opus 4.8·1M | claude-status | main
Ctx [##------] 24% 47k | compact 60%
Ses [####----] 52% 3h12m | Wk [##------] 31% 4d6h

`ping` — session completion notifications

ping fires a desktop notification when a Claude Code turn finishes or when a session is blocked waiting for your input — naming the project so you know which session to return to. Useful when you run several sessions at once. It is on by default but quiet: a finished-turn ping only fires for turns longer than 30 seconds.

macOS uses osascript, Linux uses notify-send, Windows shows a toast via BurntToast (if you already have it) or a tray balloon, falling back to a terminal bell. Zero dependencies — it never installs anything.
Nothing is sent over the network; everything is local.

Configure with cs config set <key> <value>:

Key	Default	Meaning
`ping.enabled`	`true`	master switch (turn it off: `cs config set ping.enabled false`)
`ping.minSeconds`	`30`	only ping for turns at least this long
`ping.onWaiting`	`true`	ping when Claude is blocked waiting for input/permission
`ping.waitingCooldownSec`	`60`	debounce repeated waiting pings
`ping.sound`	`false`	play the OS notification sound

Skip wiring it at install time with npx @ttigger/claude-status install --no-ping.

Configuration

Configuration is stored in ~/.claude/claude-status.config.json. Only the keys you change are written — it is a deep merge, so you never need to specify the full config.

CLI

Command	Description
`claude-status config set <key> <value>`	Set a single config key
`claude-status config get <key>`	Print the current value of a key
`claude-status config list`	Print all current settings
`claude-status config reset [key]`	Reset one key (or all) to defaults

Tip: claude-status style and claude-status layout are quick shortcuts. claude-status style claude is shorthand for config set style claude; claude-status style with no argument shows a gallery of all styles (● marks the current one). Likewise, claude-status layout two switches layout and claude-status layout lists available layouts. Even shorter: cs style claude — the built-in cs bin is an alias for claude-status.

Dotted keys for nested settings

claude-status config set elements.weekly false       # hide weekly usage
claude-status config set elements.cost false         # hide the API-key cost estimate
claude-status config set colorThresholds.green 40    # green up to 40 %
claude-status config set colorThresholds.yellow 70   # yellow 40–70 %, red above
claude-status config set autoCompact.thresholdPct 80 # approximate compaction threshold
claude-status config set barWidth 10                 # wider bars
claude-status config set style claude                # switch style
claude-status config set layout two                  # two-line layout

Example config file

{
  "style": "claude",
  "layout": "auto",
  "barWidth": 8,
  "colorThresholds": {
    "green": 50,
    "yellow": 80
  },
  "elements": {
    "model": true,
    "project": true,
    "gitBranch": true,
    "context": true,
    "autoCompact": true,
    "session": true,
    "weekly": true,
    "cost": true
  },
  "autoCompact": {
    "thresholdPct": 83.5
  }
}

Only include keys you want to override — unset keys fall back to defaults.

Preview

See the HUD rendered in your actual terminal colors before committing to a style:

claude-status preview --style neon
claude-status preview --style mist --layout three

preview is a live WYSIWYG render — it applies the real theme colors from ~/.claude/settings.json and prints every layout variant side by side.

Commands

Command	Description
`npx @ttigger/claude-status install`	Install / re-install the HUD into Claude Code
`claude-status uninstall`	Remove the HUD and restore `~/.claude/settings.json` from backup
`claude-status style [<name>]`	No arg: gallery of all styles (● = current). With name: switch style (shortcut for `config set style <name>`).
`claude-status layout [<name>]`	No arg: show current + available layouts. With name: switch layout (shortcut for `config set layout <name>`).
`cs <args...>`	Built-in shorthand for `claude-status <args...>` (e.g. `cs style claude`, `cs help cc`). Installed automatically.
`claude-status alias <name> [--for cc\|self]`	Add a shell alias. `--for cc` (default): alias points at the `cc` launcher. `--for self`: alias points at `claude-status` itself (pick any name, e.g. `qq`). Writes to shell RC on macOS/Linux, prints `Set-Alias` line on Windows.
`claude-status config set <key> <value>`	Set a config value
`claude-status config get <key>`	Get a config value
`claude-status config list`	List all config values
`claude-status config reset [key]`	Reset to default(s)
`claude-status preview [--style s] [--layout l]`	Live WYSIWYG preview
`claude-status help [<topic>]`	Print help (topics: `styles` `layout` `colors` `cc` `troubleshooting`)

Updating / Uninstall

Update to the latest version:

npx @ttigger/claude-status@latest install

Uninstall:

claude-status uninstall

The uninstaller restores ~/.claude/settings.json from the .bak backup created during install, so your previous hooks configuration is preserved.

`cc` Launcher

The cc bin is a thin wrapper that calls claude and passes all arguments through unchanged. It saves a few keystrokes on every invocation.

Name collision on macOS / Linux: cc is the POSIX name for the system C compiler. The installer detects this and warns you on macOS and Linux so you can make an informed choice. Windows has no such collision.

Setting an alias — recommended approach: run claude-status alias clc at any time. On macOS/Linux it appends alias clc=cc to ~/.zshrc or ~/.bashrc (idempotent — safe to run again). On Windows it prints a Set-Alias clc cc line for you to add to your PowerShell $PROFILE.

You can also set the alias during install with --alias:

npx @ttigger/claude-status install --alias clc

Either way, clc (or whatever name you choose) becomes a shortcut for cc, avoiding any conflict with the system compiler.

cs short command for the CLI: the package also ships a built-in cs bin that is a direct alias for claude-status (not for cc). Use it for CLI commands: cs style claude, cs alias clc, cs help cc, etc.

Note: if you already have a cs on PATH (e.g. Scala's coursier tool), the installer warns you that the new cs may shadow it. In that case you can create your own short name instead: claude-status alias qq --for self writes a shell alias called qq pointing at claude-status itself (any name works). Use --for cc (or omit --for) to alias the cc launcher as usual.

Custom alias for the CLI itself: claude-status alias <name> --for self lets you pick any name for the claude-status CLI. On macOS/Linux it writes to ~/.zshrc / ~/.bashrc; on Windows it prints the Set-Alias line for your $PROFILE.

Security

No data leaves your machine — the package only reads/writes ~/.claude/settings.json (with a .bak backup), reads your config and theme, runs local git, and spawns claude. See SECURITY.md for the full data boundary statement.

Name		Name	Last commit message	Last commit date
Latest commit History 118 Commits
.claude/skills		.claude/skills
.github/workflows		.github/workflows
bin		bin
media		media
scripts		scripts
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

@ttigger/claude-status

Why

Quick Start

The HUD

Cost estimate (API-key mode) & usage limits

This is an estimate

When it appears

`LIMIT` at 100%

What it can't show

Hiding the cost estimate

Styles

`claude` (default — refined Clay design)

`mist`

`neon`

`ascii` (most compatible)

`ping` — session completion notifications

Configuration

CLI

Dotted keys for nested settings

Example config file

Preview

Commands

Updating / Uninstall

`cc` Launcher

Security

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

@ttigger/claude-status

Why

Quick Start

The HUD

Cost estimate (API-key mode) & usage limits

This is an estimate

When it appears

LIMIT at 100%

What it can't show

Hiding the cost estimate

Styles

claude (default — refined Clay design)

mist

neon

ascii (most compatible)

ping — session completion notifications

Configuration

CLI

Dotted keys for nested settings

Example config file

Preview

Commands

Updating / Uninstall

cc Launcher

Security

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`LIMIT` at 100%

`claude` (default — refined Clay design)

`mist`

`neon`

`ascii` (most compatible)

`ping` — session completion notifications

`cc` Launcher

Packages