statuskit

Modular statusline for Claude Code.

Statuskit displays contextual information below Claude's responses: current model, git status, API usage limits, and more. It reads JSON from Claude Code's statusline hook and renders formatted, colored output.

Features

• Modular architecture — enable only the modules you need
• Configurable — customize each module's behavior via TOML config
• Built-in modules:
  • model — current Claude model name
  • git — branch, remote status, changes, last commit, project/worktree location
  • usage_limits — API quota tracking (5h session, 7d weekly) with color-coded warnings
• Coming soon:
  • beads — display active beads tasks
  • External modules support — load custom modules from separate packages

Installation

# Using uv (recommended)
uv tool install claude-statuskit

# Using pipx
pipx install claude-statuskit

# Using pip
pip install claude-statuskit

Quick Start

Run the setup command to configure Claude Code:

# User-level setup (recommended for personal use)
statuskit setup

# Project-level setup (shared config for team)
statuskit setup --scope project

# Local setup (personal overrides, gitignored)
statuskit setup --scope local

Setup will:

1. Add the statusline hook to Claude Code settings
2. Create configuration file at the appropriate level
3. Update gitignore for local configs (if applicable)

After setup, restart Claude Code to see the statusline.

Example Output

Opus 4.5 · 47m · 120k free (60%)
claude-tools master ↑1 +2 ~1 ?3 · a1b2c3d 2h
Session: 45% (2h 30m) · Weekly: 12%

This shows:

• Line 1 (model): Model name, session duration, context window
• Line 2 (git): Project, branch, remote status, changes, last commit
• Line 3 (usage_limits): API quota for session and weekly limits

Configuration

Configuration files are loaded in priority order (first found wins):

Basic Configuration

# Modules to display (in order)
modules = ["model", "git", "usage_limits"]

# Enable debug output
debug = false

Module Configuration

Each module can be configured in its own section:

[git]
show_branch = true
commit_age_format = "compact"

[usage_limits]
show_session = true
show_weekly = true
multiline = false

Module Reference

model Module

Displays model name, session duration, and context window usage.

context_format values:

git Module

Displays git branch, remote status, changes, last commit, and project/worktree location.

commit_age_format values:

PR / MR display:

The git module can show the current branch's pull request (GitHub) or merge request (GitLab), rendered between the branch name and the sync indicator as a state-colored token — PR #42 ● (GitHub) or MR !7 ○ (GitLab):

Optional dependencies: this feature shells out to the official CLIs — gh for GitHub and glab for GitLab — reusing their authentication and host configuration (so self-hosted / Enterprise instances work with no extra setup). Neither CLI is required to install statuskit; when the relevant CLI is missing or unauthenticated the PR/MR segment is simply omitted. Lookups are cached (pr_cache_ttl, default 300s) so the status line never hits the network on every render. Set pr_provider to force a provider, or show_pr = false to disable the segment entirely. When pr_link is on, supporting terminals (iTerm2, Kitty, WezTerm) make the token Cmd/Ctrl-clickable; others show it as plain text.

usage_limits Module

Displays API usage limits with color-coded warnings based on consumption rate.

Session and Weekly come from the rate_limits block Claude Code puts in the statusline payload — no network call, refreshed on every API response. Per-model rows (Fable, …) are not in that payload, so they are fetched from the account usage endpoint at most once per cache_ttl and cached; the last payload block is cached too, so a brand-new session can show the overall rows before its first API response.

Session and Weekly need a recent Claude Code that sends rate_limits in the statusline payload. Without it (an older Claude Code, or a cold cache before the first payload with that block arrives), only the per-model rows render.

A row that comes from the cache after a failed refresh is marked with its age, e.g. Fable: 25% (Wed 08:00) (40m ago). When the endpoint answers 429, its Retry-After is honoured: no request goes out until the window it names has passed.

Time format values:

Color coding: Usage is colored based on consumption rate vs elapsed time:

• 🟢 Green — on track or under
• 🟡 Yellow — approaching the limit trajectory
• 🔴 Red — ahead of pace, may hit limit

License

MIT — see LICENSE for details.