Skip to main content

​
One command setup

Get started with cc-statusline in three simple steps:
1

Run the installer

Execute the interactive installer:
npx @chongdashu/cc-statusline@latest init
This command works immediately without any global installation. The @latest tag ensures you get the newest version.
2

Answer the prompts

The installer will ask two questions:1. Installation location:
? Where would you like to install the statusline?
❯ Project-level (.claude/ in current directory)
  Global (~/.claude/ in home directory)
2. Feature selection:
? Select the features you want to include:
◉ Directory display
◉ Git branch
◉ Model name & Claude Code version
◉ Output style
◉ Context usage (requires jq)
◉ Cost & burn rate
◯ Session reset time (requires ccusage)
◉ Token statistics
All features are pre-selected except session reset time. Use Space to toggle, Enter to confirm.
3

Restart Claude Code

Close and reopen Claude Code to see your new statusline:
📁 ~/my-project  🌿 main  🤖 Sonnet 4  📟 v1.0.85  🎨 default
🧠 Context Remaining: 95% [=========-]
💰 $2.48 ($12.50/h)  📊 485234 tok (8420 tpm)
The statusline won’t appear until you restart Claude Code.

​
What just happened?

The installer performed these actions automatically:

Generated script

Created an optimized bash script at .claude/statusline.sh

Updated config

Modified .claude/settings.json to register the statusline

Set permissions

Made the script executable with chmod +x

Validated setup

Checked for jq and provided installation guidance if missing

​
Preview before restart

Want to see your statusline without restarting Claude Code? Use the preview command: 
cc-statusline preview .claude/statusline.sh
Expected output: 
📊 Testing statusline with mock data...

📁 ~/Projects/cc-statusline  🌿 feature/docs  🤖 Sonnet 4  📟 v1.0.85  🎨 default
🧠 Context Remaining: 83% [========--]  ⌛ 3h 7m until reset at 01:00 (37%) [===-------]
💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)

✓ Statusline executed successfully
⚡ Execution time: 67ms
✓ Performance: Excellent (< 100ms)

📋 Enabled Features:
  ✓ Directory display
  ✓ Git branch
  ✓ Model info
  ✓ Context tracking
  ✓ Cost tracking
  ✓ Session timer
  ✓ Token statistics
The preview command uses mock data to simulate Claude Code’s JSON input, showing exactly how your statusline will look.

​
Understanding your statusline

Here’s what each element means:

​
Line 1: Environment information

📁 ~/my-project  🌿 main  🤖 Sonnet 4  📟 v1.0.85  🎨 default
Shows your current working directory with ~ abbreviation:
  • ~/my-project - Project in home directory
  • ~/code/work/api - Nested project path
  • /usr/local/bin - Absolute paths shown as-is
Displays the current git branch:
  • main - Default branch
  • feature/statusline - Feature branch
  • Empty if not in a git repository
Shows which Claude model is active:
  • Sonnet 4 - Claude 4.5 Sonnet
  • Opus 3 - Claude 3 Opus
  • Haiku 3 - Claude 3 Haiku
Displays your Claude Code version:
  • v1.0.85 - Release version
  • Helps track compatibility
Shows the current output style setting:
  • default - Standard output
  • XML - XML-formatted responses
  • JSON - JSON-formatted responses

​
Line 2: Context and session tracking

🧠 Context Remaining: 83% [========--]  ⌛ 3h 7m until reset at 01:00 (37%) [===-------]
Shows how much of your context window is available:
  • 95% [=========-] - Plenty of room
  • 50% [=====-----] - Half used
  • 10% [=---------] - Almost full (consider starting fresh)
Requires jq to be installed. Without jq, this feature won’t display.
Countdown to when your usage limits reset:
  • 3h 7m until reset at 01:00 - Time remaining
  • (37%) [===-------] - Progress bar showing elapsed time
  • Helps you plan when to start resource-intensive tasks
Requires ccusage and is the only feature that needs this external tool.

​
Line 3: Cost and token analytics

💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)
Displays your current session costs:
  • $49.00 - Total cost so far
  • ($16.55/h) - Burn rate (cost per hour)
  • Helps you stay within budget
The burn rate is calculated from Claude Code’s native cost and duration data - no external tools needed!
Shows token consumption metrics:
  • 14638846 tok - Total tokens used (input + output)
  • (279900 tpm) - Tokens per minute burn rate
  • Uses Claude Code’s native context_window data
As of v1.4.0, token stats are calculated natively from Claude Code’s JSON input - no ccusage needed!

​
Common first-time issues

Problem: Claude Code started but no statusline appears.Solutions:
1

Check settings.json

Verify the configuration exists:
cat .claude/settings.json
Should contain:
{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}
2

Check permissions

Ensure the script is executable:
ls -l .claude/statusline.sh
Should show: -rwxr-xr-x (note the x for executable)If not, fix it:
chmod +x .claude/statusline.sh
3

Test manually

Run the script directly:
echo '{}' | .claude/statusline.sh
This should output your statusline (with some missing data due to empty JSON).
Problem: Installer warns that jq is not installed.Impact:
  • No context remaining percentage
  • No token statistics
  • No session timer
  • Basic fallback parser used (less reliable)
Solution:
brew install jq
After installing jq, re-run the installer:
npx @chongdashu/cc-statusline@latest init
Problem: Statusline takes a long time to display.Solutions:
  1. Check performance: 
    cc-statusline preview .claude/statusline.sh
    Look for the execution time in the output.
  2. Disable heavy features: Re-run init and disable session timer (requires external ccusage call): 
    npx @chongdashu/cc-statusline@latest init
  3. Check for stale processes: 
    ps aux | grep ccusage | grep -v grep
    Kill any hanging processes if found.
Problem: Statusline shows without colors or with garbled characters.Causes:
  • NO_COLOR environment variable is set
  • Terminal doesn’t support 256 colors
  • Using a non-standard terminal
Solutions:
  1. Check NO_COLOR: 
    echo $NO_COLOR
    If it outputs anything, unset it: 
    unset NO_COLOR
  2. Verify terminal color support: 
    echo $TERM
    Should be xterm-256color or similar.

​
Next steps

Now that you have cc-statusline running, explore these topics:

Configuration

Customize your statusline with advanced options

Features

Learn about all available features in detail

Troubleshooting

Solutions for common issues

Advanced usage

Custom installations and manual configuration

​
Tips for best experience

Enable all features - Unless you’re experiencing performance issues, keep all features enabled for maximum visibility.
Install jq - The advanced features are worth it. Install jq for the full experience.
Use preview frequently - Test changes with cc-statusline preview before restarting Claude Code.
Monitor burn rate - Keep an eye on the $/h metric to stay within your budget.
Watch context usage - When it drops below 20%, consider starting a fresh session for better responses.

Build docs developers (and LLMs) love

Get started for freeTalk to us