Skip to main content

​
Prerequisites

​
Required

Node.js 16+

Required for the CLI tool to run

Claude Code

The AI coding assistant you’re already using
1

Verify Node.js installation

Check your Node.js version:
node --version
Expected output:
v16.0.0 # or higher
If you don’t have Node.js installed, download it from nodejs.org
jq is a lightweight JSON processor that enables advanced features. Without it, your statusline will have limited functionality.

With jq

  • ✓ Context remaining percentage
  • ✓ Token statistics
  • ✓ Session timer
  • ✓ Full feature set

Without jq

  • ✗ No context tracking
  • ✗ No token stats
  • ✗ No session timer
  • ⚠️ Basic fallback parser
While cc-statusline works without jq, you’ll miss out on the most valuable features. We strongly recommend installing it.
Install jq using Homebrew:
brew install jq
Verify installation:
jq --version
# Output: jq-1.6 or higher

​
Optional dependencies

Most developers already have git installed. Verify with:
git --version
If not installed, download from git-scm.com
ccusage is used for session reset time tracking. It works via npx with no installation needed:
npx ccusage@latest --version
ccusage is optional and only needed for the session timer feature. All other features (including cost tracking) work without it.

​
Installation options

cc-statusline can be installed globally or on a per-project basis.

​
Installation process

1

Run the installer

Execute the installation command:
npx @chongdashu/cc-statusline@latest init
2

Choose installation location

The installer will ask where to install:
? Where would you like to install the statusline?
❯ Project-level (.claude/ in current directory)
  Global (~/.claude/ in home directory)
Choose project-level for per-project customization or global to use the same statusline everywhere.
3

Select features

Choose which features to enable (all are pre-selected by default):
? 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
Use Space to toggle features, Enter to confirm.
4

Installation completes

The installer will:
  • Generate your custom statusline script
  • Create .claude/statusline.sh with execute permissions
  • Update .claude/settings.json with the statusline configuration
  • Display a success message
✓ Statusline generated successfully!
✓ Settings updated in .claude/settings.json

🎉 Installation complete!

Restart Claude Code to see your new statusline.
5

Restart Claude Code

You must restart Claude Code for the statusline to appear.

​
File structure

After installation, you’ll have the following files: 
.claude/
├── statusline.sh    # Your generated statusline script
└── settings.json    # Auto-updated Claude Code configuration

#!/usr/bin/env bash
# Generated by cc-statusline v1.4.0
# https://www.npmjs.com/package/@chongdashu/cc-statusline
# Generated at: 2025-08-28T10:30:45.123Z

# Read JSON input from Claude Code
input=$(cat)

# Extract directory
dir=$(echo "$input" | jq -r '.workspace.current_dir // "unknown"')
dir=${dir/#$HOME/\~}

# Extract git branch
branch=$(git -C "$(pwd)" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")

# Extract model name
model=$(echo "$input" | jq -r '.model.display_name // "unknown"')

# Display statusline
echo "📁 $dir  🌿 $branch  🤖 $model"

{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}

​
Manual configuration

If auto-configuration fails, you can manually update your .claude/settings.json: 
{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}
Windows users need to prefix the command with bash to ensure the script runs in a bash environment (Git Bash, WSL, etc.).

​
Verify installation

Preview your statusline before restarting Claude Code: 
cc-statusline preview .claude/statusline.sh
Expected output: 
📊 Testing statusline with mock data...

📁 ~/Projects/my-app  🌿 main  🤖 Sonnet 4  📟 v1.0.85
🧠 Context Remaining: 75% [=======---]
💰 $12.34 ($25.68/h)

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

​
Safety features

cc-statusline includes several safety mechanisms:

Safe updates

Never overwrites existing statuslines without confirmation

Settings protection

Preserves your existing settings.json configurations

Conflict detection

Warns when other statuslines are configured

Smart defaults

Project-level installation by default for safety

​
Next steps

Quick start guide

Learn how to use cc-statusline in under 60 seconds

Build docs developers (and LLMs) love

Get started for freeTalk to us