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

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

Context Window

Cost

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.

File System

Git

Environment

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