ccstatusline
Advanced tools
_ _ _ _
___ ___ ___| |_ __ _| |_ _ _ ___| (_)_ __ ___
/ __/ __/ __| __/ _` | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | | __/
\___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
🎨 A highly customizable status line formatter for Claude Code CLI Display model info, git branch, token usage, and other metrics in your terminal
.../Personal/ccstatusline)$X.YZ vs Cost: $X.YZ)/resume (Claude Code limitation)
npx or bunx - no global package neededCLAUDE_CONFIG_DIR environment variable# Run the configuration TUI with npm
npx ccstatusline@latest
# Or with Bun (faster)
bunx ccstatusline@latest
The interactive configuration tool provides a terminal UI where you can:
💡 Tip: Your settings are automatically saved to
~/.config/ccstatusline/settings.json
🔧 Custom Claude Config: If your Claude Code configuration is in a non-standard location, set the
CLAUDE_CONFIG_DIRenvironment variable:# Linux/macOS export CLAUDE_CONFIG_DIR=/custom/path/to/.claude # Windows PowerShell $env:CLAUDE_CONFIG_DIR="C:\custom\path\.claude"
ccstatusline works seamlessly on Windows with full feature compatibility across PowerShell (5.1+ and 7+), Command Prompt, and Windows Subsystem for Linux (WSL).
# Install Bun for Windows
irm bun.sh/install.ps1 | iex
# Run ccstatusline
bunx ccstatusline@latest
# Using npm
npx ccstatusline@latest
# Or with Yarn
yarn dlx ccstatusline@latest
# Or with pnpm
pnpm dlx ccstatusline@latest
For optimal Powerline rendering on Windows:
Windows Terminal (Recommended):
PowerShell/Command Prompt:
# Install JetBrains Mono Nerd Font via winget
winget install DEVCOM.JetBrainsMonoNerdFont
# Alternative: Install base JetBrains Mono font
winget install "JetBrains.JetBrainsMono"
# Or download manually from: https://www.nerdfonts.com/font-downloads
ccstatusline automatically handles Windows-specific paths:
/ and \ path separatorsIssue: Powerline symbols showing as question marks or boxes
# Solution: Install a compatible Nerd Font
winget install JetBrainsMono.NerdFont
# Then set the font in your terminal settings
Issue: Git commands not recognized
# Check if Git is installed and in PATH
git --version
# If not found, install Git:
winget install Git.Git
# Or download from: https://git-scm.com/download/win
Issue: Permission errors during installation
# Use non-global installation (recommended)
npx ccstatusline@latest
# Or run PowerShell as Administrator for global install
Issue: "Execution Policy" errors in PowerShell
# Temporarily allow script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Issue: Windows Defender blocking execution
# If Windows Defender flags the binary:
# 1. Open Windows Security
# 2. Go to "Virus & threat protection"
# 3. Add exclusion for the ccstatusline binary location
# Or use temporary bypass (not recommended for production):
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.bun\bin"
ccstatusline works perfectly in WSL environments:
# Install in WSL Ubuntu/Debian
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bunx ccstatusline@latest
WSL Benefits:
For the best experience, configure Windows Terminal with these recommended settings:
{
"profiles": {
"defaults": {
"font": {
"face": "JetBrainsMono Nerd Font",
"size": 12
},
"colorScheme": "One Half Dark"
}
}
}
Configure ccstatusline in your Claude Code settings:
Settings Location:
~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json)CLAUDE_CONFIG_DIR environment variable to use a different directoryFor Bun users:
{
"statusLine": "bunx ccstatusline@latest"
}
For npm users:
{
"statusLine": "npx ccstatusline@latest"
}
💡 Custom Config Directory: If you use a non-standard Claude Code configuration directory, set the
CLAUDE_CONFIG_DIRenvironment variable before running ccstatusline. The tool will automatically detect and use your custom location.
ccstatusline is optimized for Windows performance:
Some widgets have Windows-specific optimizations:
Once configured, ccstatusline automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions.
These settings affect where long lines are truncated, and where right-alignment occurs when using flex separators:
Configure global formatting preferences that apply to all widgets:
💡 Note: These settings are applied during rendering and don't add widgets to your widget list. They provide a consistent look across your entire status line without modifying individual widget configurations.
⚠️ VSCode Users: If colors appear incorrect in the VSCode integrated terminal, the "Terminal › Integrated: Minimum Contrast Ratio" (
terminal.integrated.minimumContrastRatio) setting is forcing a minimum contrast between foreground and background colors. You can adjust this setting to 1 to disable the contrast enforcement, or use a standalone terminal for accurate colors.
The Block Timer widget helps you track your progress through Claude Code's 5-hour conversation blocks:
Display Modes:
Features:
Some widgets support "raw value" mode which displays just the value without a label:
Model: Claude 3.5 Sonnet → Raw: Claude 3.5 SonnetSession: 2hr 15m → Raw: 2hr 15mBlock: 3hr 45m → Raw: 3hr 45mCtx: 18.6k → Raw: 18.6kAdd static text to your status line. Perfect for:
Execute shell commands and display their output dynamically:
pwd | xargs basename - Show current directory namenode -v - Display Node.js versiongit rev-parse --short HEAD - Show current commit hashdate +%H:%M - Display current timecurl -s wttr.in?format="%t" - Show current temperaturenpx -y ccusage@latest statusline - Display Claude usage metrics (set timeout: 5000ms)⚠️ Important: Commands should complete quickly to avoid delays. Long-running commands will be killed after the configured timeout. If you're not seeing output from your custom command, try increasing the timeout value (press 't' in the editor).
💡 Tip: Custom commands can be other Claude Code compatible status line formatters! They receive the same JSON via stdin that ccstatusline receives from Claude Code, allowing you to chain or combine multiple status line tools.
ccusage is a tool that tracks and displays Claude Code usage metrics. You can integrate it directly into your status line:
npx -y ccusage@latest statusline5000 (5 seconds for initial download)
📄 How it works: The command receives Claude Code's JSON data via stdin, allowing ccusage to access session information, model details, and transcript data for accurate usage tracking.
When terminal width is detected, status lines automatically truncate with ellipsis (...) if they exceed the available width, preventing line wrapping.
Complete API documentation is generated using TypeDoc and includes detailed information about:
To generate the API documentation locally:
# Generate documentation
bun run docs
# Clean generated documentation
bun run docs:clean
The documentation will be generated in the docs/ directory and can be viewed by opening docs/index.html in your web browser.
# Clone the repository
git clone https://github.com/sirmalloc/ccstatusline.git
cd ccstatusline
# Install dependencies
bun install
# Run in TUI mode (configuration)
bun run src/ccstatusline.ts
# Build for distribution
bun run build
ccstatusline/
├── src/
│ ├── ccstatusline.ts # Main entry point
│ ├── tui/ # React/Ink configuration UI
│ │ ├── App.tsx # Root TUI component
│ │ ├── index.tsx # TUI entry point
│ │ └── components/ # UI components
│ │ ├── MainMenu.tsx
│ │ ├── LineSelector.tsx
│ │ ├── ItemsEditor.tsx
│ │ ├── ColorMenu.tsx
│ │ ├── PowerlineSetup.tsx
│ │ └── ...
│ ├── widgets/ # Status line widget implementations
│ │ ├── Model.ts
│ │ ├── GitBranch.ts
│ │ ├── TokensTotal.ts
│ │ ├── OutputStyle.ts
│ │ └── ...
│ ├── utils/ # Utility functions
│ │ ├── config.ts # Settings management
│ │ ├── renderer.ts # Core rendering logic
│ │ ├── powerline.ts # Powerline font utilities
│ │ ├── colors.ts # Color definitions
│ │ └── claude-settings.ts # Claude Code integration (supports CLAUDE_CONFIG_DIR)
│ └── types/ # TypeScript type definitions
│ ├── Settings.ts
│ ├── Widget.ts
│ ├── PowerlineConfig.ts
│ └── ...
├── dist/ # Built files (generated)
├── package.json
├── tsconfig.json
└── README.md
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)MIT © Matthew Breedlove
Matthew Breedlove
Give a ⭐ if this project helped you!
FAQs
A customizable status line formatter for Claude Code CLI
The npm package ccstatusline receives a total of 1,409 weekly downloads. As such, ccstatusline popularity was classified as popular.
We found that ccstatusline demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket researchers found 10 typosquatted npm packages that auto-run on install, show fake CAPTCHAs, fingerprint by IP, and deploy a credential stealer.
Product
Socket Firewall Enterprise is now available with flexible deployment, configurable policies, and expanded language support.
Security News
Open source dashboard CNAPulse tracks CVE Numbering Authorities’ publishing activity, highlighting trends and transparency across the CVE ecosystem.
