claudeline

Customizable status line for Claude Code. Display model info, git status, context usage, costs, API usage limits, and more in your terminal.

Installation

# Install with a theme
npx claudeline --theme luca --install

# Or with a custom format
npx claudeline "claude:model fs:dir git:branch" --install

That's it. Restart Claude Code and your status line will appear.

Quick Start

# List available themes
npx claudeline --themes

# List all components
npx claudeline --list

# Preview what data is available
npx claudeline --preview

# Install to current project only
npx claudeline --theme powerline --install --project

# Uninstall
npx claudeline --uninstall

Themes

Theme	Format
minimal	claude:model fs:dir
default	[claude:model] emoji:folder fs:dir if:git(sep:pipe emoji:branch git:branch git:status)
powerline	bold:cyan:claude:model sep:powerline fs:dir if:git(...)
full	[bold:cyan:claude:model] fs:home sep:arrow green:git:branch git:status sep:pipe ctx:bar ctx:percent sep:pipe cost:total
git	[claude:model] emoji:folder fs:dir sep:pipe emoji:branch git:branch git:status git:ahead-behind if:dirty(...)
tokens	claude:model sep:pipe ctx:emoji ctx:tokens sep:pipe cost:lines
dev	[fs:dir] git:branch sep:pipe env:node sep:pipe time:now
dashboard	[bold:claude:model] fs:dir sep:pipe git:branch git:status sep:pipe ctx:percent sep:pipe cost:total sep:pipe time:now
context-focus	claude:model sep:pipe ctx:bar sep:pipe ctx:tokens sep:pipe ctx:emoji
cost	claude:model sep:pipe cost:total sep:pipe cost:duration sep:pipe cost:lines-both
simple	claude:model fs:dir git:branch
verbose	[claude:model] [claude:version] sep:pipe fs:home sep:pipe git:branch git:status git:ahead-behind sep:pipe ctx:bar ctx:percent sep:pipe cost:total cost:duration sep:pipe time:now
compact	claude:model sep:slash fs:dir sep:slash git:branch
colorful	bold:magenta:claude:model sep:arrow cyan:fs:dir sep:arrow green:git:branch yellow:git:status sep:arrow blue:ctx:percent
luca	Nerd font icons, colored repo:branch, dirty state, cost, 5h/weekly usage bars

When you install with --theme, claudeline stores a theme:name reference so your status line automatically picks up theme updates when you upgrade.

Format Syntax

Components use type:key format, separated by spaces:

claude:model fs:dir git:branch

Styling

Add color/style prefixes before any component:

green:git:branch           # green text
bold:cyan:claude:model     # bold cyan text
bg-red:white:text:ERROR    # white on red background

Grouping

Wrap components in brackets to add literal brackets:

[claude:model]    # outputs: [Sonnet 4]
(fs:dir)          # outputs: (myproject)
{git:branch}      # outputs: {main}
<ctx:percent>     # outputs: <45%>

Conditionals

Show components only when conditions are met:

if:git(git:branch git:status)     # only in git repos
if:dirty(text:UNCOMMITTED)        # only when working tree is dirty
if:subdir(fs:relative)            # only when in a subdirectory (not git root)
if:node(env:node)                 # only in Node.js projects
if:python(env:python)             # only in Python projects
if:rust(emoji:rust)               # only in Rust projects
if:go(emoji:go)                   # only in Go projects

Separators

Use sep:name between components:

claude:model sep:pipe fs:dir sep:arrow git:branch

Available separators:

• pipe → |
• arrow → →
• arrow-left → ←
• chevron → ›
• chevron-left → ‹
• dot → •
• dash → -
• slash → /
• colon → :
• double-colon → ::
• tilde → ~
• double-pipe → ‖
• bullet → ◦
• diamond → ◇
• star → ★
• powerline → ``
• powerline-left → ``
• space →
• none → (empty, useful for glueing components together)

Components Reference

Claude/Session

Component	Description
claude:model	Model display name (e.g., "Sonnet 4")
claude:model-id	Model ID (e.g., "claude-sonnet-4")
claude:model-letter	First letter of model name
claude:version	Claude Code version
claude:session	Session ID (first 8 chars)
claude:session-full	Full session ID
claude:style	Output style name

Context Window

Component	Description
ctx:percent	Usage percentage (e.g., "45%")
ctx:remaining	Remaining percentage
ctx:tokens	Used/total tokens (e.g., "50k/200k")
ctx:in	Input tokens
ctx:out	Output tokens
ctx:size	Context window size
ctx:bar	Progress bar [████░░░░░░]
ctx:bar:N	Progress bar with width N
ctx:emoji	Status emoji (🟢🟡🟠🔴)
ctx:used-tokens	Total used tokens

Cost

Component	Description
cost:total	Total cost (e.g., "$0.42")
cost:total-cents	Cost in cents (e.g., "42¢")
cost:duration	Total session duration
cost:api	API call duration
cost:lines	Net lines changed (+/-)
cost:added	Lines added
cost:removed	Lines removed
cost:lines-both	Lines added and removed

Usage/Limits

Requires Clusage, a macOS menu bar app that tracks your Claude API usage. Clusage writes usage data to ~/.claude/clusage-api.json, which claudeline reads automatically. Install Clusage and add at least one account for usage components to work.

Component	Description	Example
usage:5h	5-hour utilization %	12%
usage:week	7-day utilization %	58%
usage:7d	Alias for usage:week	58%
usage:5h-reset	Time until 5h reset	3h 32m
usage:week-reset	Time until weekly reset	2d 5h
usage:7d-reset	Alias for usage:week-reset	2d 5h
usage:5h-bar	5h progress bar with H label	H▰▰▱▱▱▱▱▱
usage:5h-bar:N	5h bar with width N	H▰▱▱▱▱
usage:week-bar	Weekly progress bar with W label	W▰▰▰▰▰▱▱▱
usage:week-bar:N	Weekly bar with width N	W▰▰▰▱▱
usage:5h-emoji	5h status emoji (🟢🟡🟠🔴)	🟢
usage:week-emoji	Weekly status emoji	🟡
usage:7d-emoji	Alias for usage:week-emoji	🟡
usage:velocity	5h usage velocity	2.3 pp/hr
usage:intensity	Usage intensity level	moderate
usage:eta	Time until rate limit ceiling	1h 23m
usage:7d-granular	Interpolated 7-day utilization	46.3%
usage:7d-projected	Projected 7-day at reset	62%
usage:budget	Daily usage budget	14.3 pp/day
usage:budget-status	Budget pacing status	on_track

File System

Component	Description
fs:dir	Current directory name
fs:path	Full current path
fs:project	Project directory name
fs:project-path	Full project path
fs:home	Path with ~ for home
fs:cwd	Working directory
fs:relative	Path relative to project

Git

Component	Description
git:branch	Current branch name
git:status	Clean (✓) or dirty (*)
git:status-emoji	✨ or 📝
git:status-word	"clean" or "dirty"
git:ahead	Commits ahead (↑N)
git:behind	Commits behind (↓N)
git:ahead-behind	Both ahead/behind
git:stash	Stash count (⚑N)
git:staged	Staged files (●N)
git:modified	Modified files (+N)
git:untracked	Untracked files (?N)
git:dirty	Combined dirty status with per-type colors (green staged, red untracked, yellow modified)
git:repo-branch	Condensed repo:branch format
git:commit	Short commit hash
git:commit-long	Full commit hash
git:tag	Current tag
git:remote	Remote name
git:repo	Repository name
git:user	Git user name
git:email	Git user email
git:remote-url	Remote URL

Environment

Component	Description
env:node	Node.js version
env:node-short	Node version without 'v'
env:bun	Bun version
env:npm	npm version
env:pnpm	pnpm version
env:yarn	Yarn version
env:python	Python version
env:deno	Deno version
env:rust	Rust version
env:go	Go version
env:ruby	Ruby version
env:java	Java version
env:user	Current username
env:hostname	Full hostname
env:hostname-short	Short hostname
env:shell	Current shell
env:term	Terminal type
env:os	Operating system
env:arch	CPU architecture
env:os-release	OS release
env:cpus	CPU count
env:memory	Total memory

Time

Component	Description
time:now	Current time (HH:MM)
time:seconds	Time with seconds
time:12h	12-hour format
time:date	Short date (Jan 15)
time:full	Full date (2024-01-15)
time:iso	ISO timestamp
time:unix	Unix timestamp
time:weekday	Short weekday
time:weekday-long	Full weekday
time:month	Short month
time:month-long	Full month
time:year	Year
time:day	Day of month
time:hour	Hour (24h)
time:minute	Minute
time:elapsed	Session elapsed time

Nerd Font Icons

Use nerd:name for Nerd Font glyphs. Requires a Nerd Font in your terminal.

Files: folder, folder-open, file, file-code

Git: branch, repo, commit, merge, tag, stash, pr, diff, compare

Status: check, x, warn, error, info, question, bell, pin

Decorative: star, fire, rocket, sparkle, lightning, heart, diamond, circle, square, triangle

Tech: node, python, rust, go, ruby, java, docker, terminal, code, database, cloud, server, package, gear, lock, unlock, key, shield

Arrows: up, down, left, right, arrow-right, arrow-left

Time: clock, calendar, history

OS: apple, linux, windows

Other: search, eye, bug, wrench, plug, wifi, bluetooth, cpu, memory, home, user

Emojis

Use emoji:name for Unicode emojis (no Nerd Font required):

Files: folder 📁, file 📄, home 🏠

Git: branch 🌿, commit 📝, merge 🔀, tag 🏷️, stash 📦

Status: check ✓, x ✗, warn ⚠, error ❌, success ✅, info ℹ

Decorative: star ★, fire 🔥, rocket 🚀, sparkle ✨, lightning ⚡, heart ❤, diamond ◆, circle ●, square ■, triangle ▲

Tech: node ⬢, python 🐍, rust 🦀, go 🐹, ruby 💎, java ☕, docker 🐳

Indicators: green 🟢, yellow 🟡, orange 🟠, red 🔴

Arrows: up ↑, down ↓, left ←, right →

Other: clock 🕐, calendar 📅, money 💰

Colors & Styles

Prefix any component with styles:

Colors: black, red, green, yellow, blue, magenta, cyan, white, gray

Bright colors: bright-red, bright-green, bright-yellow, bright-blue, bright-magenta, bright-cyan, bright-white

Backgrounds: bg-black, bg-red, bg-green, bg-yellow, bg-blue, bg-magenta, bg-cyan, bg-white

Styles: bold, dim, italic, underline, inverse, strikethrough

Chain multiple styles: bold:green:underline:git:branch

Custom Text

Use text:value for literal text:

text:Hello text:World
text:"Hello World"      # with spaces

CLI Options

-i, --install          Install to ~/.claude/settings.json
-u, --uninstall        Remove statusline configuration
    --project          Use project .claude/ instead of global
-t, --theme <name>     Use a preset theme
-l, --list             List all components
    --themes           List all themes
-p, --preview          Show sample JSON data
    --no-emoji         Disable emojis
    --no-color         Disable colors
    --use-bunx         Force bunx in command
    --use-npx          Force npx in command
    --global-install   Use claudeline directly (global install)
-V, --version          Show version
-h, --help             Show help

How It Works

When you run --install, claudeline updates your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "npx claudeline run theme:luca",
    "padding": 0
  }
}

Claude Code pipes session data as JSON to this command, and claudeline outputs the formatted status line.

Testing

Test your format without installing:

# Get sample data
npx claudeline --preview

# Test with sample data
echo '{"model":{"display_name":"Sonnet 4"}}' | npx claudeline run "claude:model fs:dir"

# Test a theme
echo '{"model":{"display_name":"Opus"}}' | npx claudeline run theme:dashboard

Package Managers

claudeline auto-detects bun vs node and uses the appropriate runner:

• Running with bun → installs bunx claudeline run ...
• Running with node → installs npx claudeline run ...

Override with --use-bunx or --use-npx.

License

MIT