claude-statuskit 0.3.0

Modular statusline for Claude Code

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):

Level	Path	Use case
Local	.claude/statuskit.local.toml	Personal overrides, gitignored
Project	.claude/statuskit.toml	Shared team configuration
User	~/.claude/statuskit.toml	Global personal defaults

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.

Parameter	Type	Default	Description
show_duration	bool	true	Show session duration
show_context	bool	true	Show context window usage
context_format	string	"free"	Context display format (see below)
context_compact	bool	false	Use compact numbers (e.g., 150k instead of 150,000)
context_threshold_green	int	50	Percentage of free context to show green
context_threshold_yellow	int	25	Percentage of free context to show yellow (below = red)

context_format values:

Value	Output example
"free"	150,000 free (75.0%)
"used"	50,000 used (25.0%)
"ratio"	50,000/200,000 (25.0%)
"bar"	[███████░░░] 70%

git Module

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

Parameter	Type	Default	Description
show_project	bool	true	Show project (repository) name
show_worktree	bool	true	Show worktree name with 🌲 indicator
show_folder	bool	true	Show current subfolder relative to repo root
show_branch	bool	true	Show current branch name
show_remote_status	bool	true	Show ahead/behind/diverged status
show_changes	bool	true	Show staged/modified/untracked counts
show_commit	bool	true	Show last commit hash and age
commit_age_format	string	"relative"	Commit age format (see below)

commit_age_format values:

Value	Output example
"relative"	2 hours ago
"compact"	2h

usage_limits Module

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

Parameter	Type	Default	Description
show_session	bool	true	Show 5-hour session limit
show_weekly	bool	true	Show 7-day weekly limit
show_sonnet	bool	false	Show Sonnet-only weekly limit
show_reset_time	bool	true	Show time until reset
multiline	bool	true	Display each limit on separate line
show_progress_bar	bool	false	Show visual progress bar
bar_width	int	10	Progress bar width in characters
session_time_format	string	"remaining"	Time format for session limit
weekly_time_format	string	"reset_at"	Time format for weekly limit
sonnet_time_format	string	"reset_at"	Time format for Sonnet limit
cache_ttl	int	60	Cache lifetime in seconds

Time format values:

Value	Output example
"remaining"	2h 30m
"reset_at"	Thu 17:00

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.