Customizable status line formatter for Claude Code CLI
npm install @vimukthid/ccslClaude Code Status Line - A customizable status line formatter for Claude Code CLI.
Transform Claude Code status data into beautifully formatted, themed terminal displays.
``bash`
npm install -g @vimukthid/ccsl
Requirements: Node.js 22.x or higher
`bashRun the installer
ccsl install
This automatically configures
~/.claude/settings.json with:`json
{
"statusLine": {
"type": "command",
"command": "npx @vimukthid/ccsl"
}
}
`$3
After installation, restart Claude Code to see your new status line!
How It Works
Claude Code passes JSON data via stdin to ccsl, which formats it into a beautiful status line:
`
Opus │ 42% │ ↑15.2k ↓4.5k │ $0.02
`Features
$3
| Widget | Description | Example |
|-------------|----------------------------|----------------------|
|
model | Claude model name | Opus |
| context | Context window usage % | 42% |
| tokens | Input/Output tokens | ↑15.2k ↓4.5k |
| cost | Session cost USD | $0.02 |
| duration | Session duration | 45s |
| lines | Lines added/removed | +156 -23 |
| directory | Current directory | my-project |
| version | Claude Code version | v1.0.80 |
| usage | Session usage with limit | ▰▰▰▱▱ 75/100 (Pro) |
| resetTime | Time until usage resets | 1h30m |$3
Colorful:
-
neon - Vibrant cyberpunk with electric colors
- rainbow - Colorful gradient transitions
- ocean - Cool blues and tealsProfessional:
-
minimal - Clean and subtle (default)
- monochrome - Pure grayscale
- corporate - Professional muted blues$3
-
auto - Detect terminal capabilities (default)
- nerd - Nerd Font icons
- unicode - Standard Unicode symbols
- ascii - Plain ASCII textCLI Commands
`bash
Interactive TUI configuration
ccslInstall/Uninstall from Claude Code
ccsl install # Add to Claude Code settings
ccsl uninstall # Remove from Claude Code settingsTheme management
ccsl theme # Quick switch theme
ccsl theme --list # List available themesOther commands
ccsl preview # Preview with sample data
ccsl init # Create local config file
ccsl init --global # Create global config file
ccsl config # Open TUI configuration (local)
ccsl config --global # Open TUI configuration (global)
ccsl --version # Show version
ccsl --help # Show help
`Configuration
$3
| Scope | Location | Priority | Use Case |
|--------|------------------------------|----------|-----------------------------|
| Local |
.ccslrc.json | Highest | Project-specific settings |
| Global | ~/.config/ccsl/config.json | Default | User-wide default settings |Configuration Priority: Local config takes precedence over global config. If no local config exists, the global config is used.
`bash
Configure global settings (applies to all projects)
ccsl config --globalConfigure local settings (project-specific)
ccsl config --local # or just: ccsl config
`$3
`json
{
"theme": "minimal",
"widgets": ["model", "context", "tokens", "cost"],
"separator": " │ ",
"icons": "auto",
"padding": 1
}
`$3
`json
{
"theme": "minimal",
"customTheme": {
"name": "my-theme",
"colors": {
"model": { "fg": "#61afef", "bold": true },
"context": { "fg": "#98c379" },
"contextHigh": { "fg": "#e5c07b" },
"contextCritical": { "fg": "#e06c75" },
"tokens": { "fg": "#c678dd" },
"cost": { "fg": "#e06c75" },
"duration": { "fg": "#56b6c2" },
"lines": { "fg": "#d19a66" },
"linesAdded": { "fg": "#98c379" },
"linesRemoved": { "fg": "#e06c75" },
"directory": { "fg": "#61afef" },
"version": { "fg": "#abb2bf" },
"separator": { "fg": "#5c6370" },
"usage": { "fg": "#98c379" },
"usageHigh": { "fg": "#e5c07b" },
"usageCritical": { "fg": "#e06c75" },
"resetTime": { "fg": "#61afef" }
}
}
}
`Input Format
ccsl receives JSON from Claude Code via stdin:
`json
{
"model": { "display_name": "Opus" },
"context_window": {
"used_percentage": 42.5,
"total_input_tokens": 15234,
"total_output_tokens": 4521
},
"cost": {
"total_cost_usd": 0.0234,
"total_duration_ms": 45000,
"total_lines_added": 156,
"total_lines_removed": 23
},
"workspace": { "current_dir": "/path/to/project" },
"version": "1.0.80",
"session_usage": {
"requests_used": 45,
"requests_limit": 100,
"usage_percentage": 45,
"reset_in_seconds": 7200,
"plan": "Pro"
}
}
`$3
The
session_usage object supports the following fields for the usage and resetTime widgets:| Field | Type | Description |
|--------------------|--------|-------------------------------------------|
|
requests_used | number | Number of requests used in current period |
| requests_limit | number | Maximum requests allowed |
| usage_percentage | number | Usage percentage (0-100) |
| reset_at | string | ISO timestamp when usage resets |
| reset_in_seconds | number | Seconds until usage resets |
| plan | string | Plan/tier name (e.g., "Pro", "Max") |Development
$3
`bash
Clone the repository
git clone https://github.com/vimukthid/ccsl.git
cd ccslInstall dependencies
npm installBuild
npm run buildRun tests
npm test
`$3
You can install ccsl locally without publishing to npm:
`bash
Option 1: Install globally from local directory
cd /path/to/ccsl
npm run build
npm linkNow you can use 'ccsl' command globally
ccsl --help
ccsl install
``bash
Option 2: Install directly from the built package
cd /path/to/ccsl
npm run build
npm pack # Creates @vimukthid-ccsl-1.0.5.tgzInstall the tarball globally
npm install -g ./vimukthid-ccsl-1.0.5.tgz
``bash
Option 3: Reference the local build in Claude Code settings
Edit ~/.claude/settings.json manually:
{
"statusLine": {
"type": "command",
"command": "node /path/to/ccsl/dist/cli.js"
}
}
`$3
`bash
Preview with sample data
npm run build && node dist/cli.js previewTest piped input (simulates what Claude Code sends)
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":45}}' | node dist/cli.js
`$3
`bash
Remove the global link
npm unlink -g @vimukthid/ccsl
``MIT