Skip to main content

​
Overview

cc-statusline offers flexible configuration through an interactive setup process. All features are pre-selected by default and can be customized to match your workflow.

​
Interactive Configuration

The init command guides you through configuration with intelligent defaults: 
npx @chongdashu/cc-statusline@latest init
1

Select Features

Choose which information to display in your statusline using arrow keys and spacebar.All features are enabled by default for the best experience.
2

Color Scheme

Enable or disable the modern color scheme and emojis.Default: Enabled for better visibility
3

Debug Logging

Optionally enable debug logging to .claude/statusline.log.Default: Disabled to reduce file clutter
4

Installation Location

Choose between global (~/.claude) or project-level (./.claude) installation.Default: Project for safety and isolation

​
Available Features

​
Core Features

These features are displayed on the first line of your statusline:
Displays your current working directory with ~ abbreviation for home directory.Example: 📁 ~/Projects/my-appRequirements: None
Shows the active git branch name in your repository.Example: 🌿 feature/new-statuslineRequirements: git installed (optional)
If git is not installed, this feature gracefully falls back to showing nothing
Displays which Claude model you’re currently using.Example: 🤖 Sonnet 4Requirements: None (extracted from Claude Code JSON)

​
Context & Session Features

Displayed on the second line for real-time awareness:
Shows remaining context window as a percentage with visual progress bar.Example: 🧠 Context Remaining: 83% [========--]Color coding:
  • Green (>40%): Plenty of space
  • Peach (20-40%): Getting full
  • Red (<20%): Nearly full
Requirements: jq (falls back to “TBD” without it)
Context is calculated from Claude Code’s native context_window.current_usage field
Displays time until usage limit resets with countdown and progress bar.Example: ⌛ 3h 7m until reset at 01:00 (37%) [===-------]Requirements: jq + ccusage integration
This feature requires both jq and ccusage to work properly

​
Usage Analytics

Displayed on the third line for cost tracking:
Real-time cost monitoring with optional burn rate.Example: 💰 $49.00 ($16.55/h)Requirements: ccusage (via npx ccusage@latest)
Burn rate is calculated from your recent usage pattern
Total token consumption with tokens-per-minute burn rate.Example: 📊 14638846 tok (279900 tpm)Requirements: jq + ccusage
Enhanced cost and token burn rate display.Shows both $/hour and tokens/minute metrics.Requirements: jq + ccusage

​
Configuration Options

​
Feature Selection

From src/cli/prompts.ts:18-40, the available features are: 
{
  type: 'checkbox',
  name: 'features',
  choices: [
    { name: '📁 Working Directory', value: 'directory', checked: true },
    { name: '🌿 Git Branch', value: 'git', checked: true },
    { name: '🤖 Model Name & Version', value: 'model', checked: true },
    { name: '🧠 Context Remaining', value: 'context', checked: true },
    { name: '💵 Usage & Cost', value: 'usage', checked: true },
    { name: '📊 Token Statistics', value: 'tokens', checked: true },
    { name: '⚡ Burn Rate', value: 'burnrate', checked: true },
    { name: '⌛ Session Reset Time', value: 'session', checked: false }
  ]
}
Session reset time is disabled by default because it requires ccusage integration

​
Color Schemes

When colors are enabled, cc-statusline uses a 256-color palette optimized for Claude Code terminals:
  • Directory: Cyan (\033[38;5;117m)
  • Git Branch: Green (\033[38;5;150m)
  • Model: Purple (\033[38;5;141m)
  • Context (>40%): Mint green (\033[38;5;158m)
  • Context (20-40%): Peach (\033[38;5;215m)
  • Context (<20%): Coral red (\033[38;5;203m)
  • Cost: Yellow (\033[38;5;228m)
  • Burn Rate: Highlighted orange (\033[38;5;215m)

​
Debug Logging

Enable logging to troubleshoot issues: 
# During init, select "Yes" for debug logging
Logs are written to .claude/statusline.log and include:
  • Timestamp of each statusline trigger
  • Input JSON from Claude Code
  • Extracted data values
  • Whether jq is available
Example log output: 
[2026-03-04 10:30:15] Status line triggered (cc-statusline v1.4.0)
[2026-03-04 10:30:15] Input:
{
  "workspace": { "current_dir": "/home/user/project" },
  "model": { "display_name": "Sonnet 4" }
}
[2026-03-04 10:30:15] Using jq for JSON parsing
[2026-03-04 10:30:15] Extracted: dir=~/project, model=Sonnet 4, context=83%, cost=49.00

​
Advanced Options

​
Custom Output Path

Generate the statusline to a custom location: 
cc-statusline init --output ./my-custom-statusline.sh

​
Skip Auto-Installation

Generate the script without automatic installation: 
cc-statusline init --no-install
You’ll need to manually configure .claude/settings.json: 
{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}

​
Environment Variables

cc-statusline respects standard environment variables: 
# Disable all color output
export NO_COLOR=1

​
Configuration File Structure

After installation, your project has: 
.claude/
├── statusline.sh      # Generated bash script
├── statusline.log     # Debug logs (if enabled)
└── settings.json      # Claude Code configuration
The statusline.sh script header contains your configuration: 
#!/bin/bash
# Generated by cc-statusline v1.4.0
# Custom Claude Code statusline - Created: 2026-03-04T10:30:15.000Z
# Theme: detailed | Colors: true | Features: directory, git, model, context, usage, tokens, burnrate
STATUSLINE_VERSION="1.4.0"

​
Reconfiguration

To update your configuration:
1

Run init again

cc-statusline init
2

Choose different options

Select your new feature set and preferences
3

Confirm overwrite

When prompted, confirm you want to overwrite the existing statusline:⚠️ Project statusline.sh already exists. Overwrite?
4

Restart Claude Code

Changes take effect after restarting Claude Code
Overwriting will replace your existing statusline script. Make a backup if you’ve made custom modifications.

​
Next Steps

Preview Your Configuration

Test your statusline before restarting Claude Code

Troubleshooting

Fix common configuration issues

Build docs developers (and LLMs) love

Get started for freeTalk to us