_        _             _ _            
  ___ ___ ___| |_ __ _| |_ _   _ ___| (_)_ __   ___ 
 / __/ __/ __| __/ _ | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | |  __/
 \___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
                                                     

📚 Table of Contents

- Recent Updates
- Features
- Quick Start
- Windows Support
- Usage
- API Documentation
- Development
- Contributing
- Uninstall
- License
- Related Projects

---

🆕 Recent Updates

$3

$3

- Fix miscalculation in the block timer

$3

- Remaining Mode - You can now toggle the Context Percentage widgets between usage percentage and remaining percentage when configuring them in the TUI by pressing the 'l' key.

$3

- 👾 Emoji Support - You can now paste emoji into the custom text widget. You can also turn on the merge option to get emoji labels for your widgets like this:

!Emoji Support

$3

- 🚀 No Line Limit - Configure as many status lines as you need - the 3-line limitation has been removed

$3

- 🌳 Git Worktree widget - Shows the active worktree name when working with git worktrees
- 👻 Hide 'no git' message toggle - Git widgets now support hiding the 'no git' message when not in a repository (toggle with 'h' key while editing the widget)

$3

!Powerline Auto-Alignment

- 🎯 Widget Alignment - Auto-align widgets across multiple status lines in Powerline mode for a clean, columnar layout (toggle with 'a' in Powerline Setup)

$3

!Current Working Directory and Session Cost

- 📁 Current Working Directory - Display the current working directory with configurable segment display
- Set the number of path segments to show (e.g., show only last 2 segments: .../Personal/ccstatusline)
- Supports raw value mode for compact display
- Automatically truncates long paths with ellipsis
- 💰 Session Cost Widget - Track your Claude Code session costs (requires Claude Code 1.0.85+)
- Displays total session cost in USD
- Supports raw value mode (shows just $X.YZ vs Cost: $X.YZ)
- Real-time cost tracking from Claude Code session data
- Note: Cost may not update properly when using /resume (Claude Code limitation)
- 🐛 Bug Fixes
- Fixed Block Timer calculations for accurate time tracking across block boundaries
- Improved widget editor stability with proper Ctrl+S handling
- Enhanced cursor display in numeric input fields

$3

!Block Timer

- ⏱️ Block Timer - Track your progress through 5-hour Claude Code blocks
- Displays time elapsed in current block as hours/minutes (e.g., "3hr 45m")
- Progress bar mode shows visual completion percentage
- Two progress bar styles: full width (32 chars) or compact (16 chars)
- Automatically detects block boundaries from transcript timestamps

$3

- 📊 Real-time Metrics - Display model name, git branch, token usage, session duration, block timer, and more
- 📈 API Usage Tracking - Real-time 5-hour session and weekly utilization from Anthropic API with progress bars
- ⏱️ Reset Timer - Countdown to when your 5-hour session window resets
- 🎨 Fully Customizable - Choose what to display and customize colors for each element
- ⚡ Powerline Support - Beautiful Powerline-style rendering with arrow separators, caps, and custom fonts
- 📐 Multi-line Support - Configure multiple independent status lines
- 🖥️ Interactive TUI - Built-in configuration interface using React/Ink
- ⚙️ Global Options - Apply consistent formatting across all widgets (padding, separators, bold, background)
- 🚀 Cross-platform - Works seamlessly with both Bun and Node.js
- 🔧 Flexible Configuration - Supports custom Claude Code config directory via CLAUDE_CONFIG_DIR environment variable
- 📏 Smart Width Detection - Automatically adapts to terminal width with flex separators
- ⚡ Zero Config - Sensible defaults that work out of the box

---

🚀 Quick Start

$3

`bash


Run the configuration TUI with npm

> 💡 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_DIR environment variable:
> `bash
> # Linux/macOS
> export CLAUDE_CONFIG_DIR=/custom/path/to/.claude
>
> # Windows PowerShell
> $env:CLAUDE_CONFIG_DIR="C:\custom\path\.claude"
> `

---

🪟 Windows Support

ccstatusline works seamlessly on Windows with full feature compatibility across PowerShell (5.1+ and 7+), Command Prompt, and Windows Subsystem for Linux (WSL).

$3

#### Option 1: Using Bun (Recommended)
`powershell


Install Bun for Windows

#### Option 2: Using Node.js
`powershell


Using npm

PowerShell/Command Prompt:
`powershell


Install JetBrains Mono Nerd Font via winget

#### Path Handling
ccstatusline automatically handles Windows-specific paths:
- Git repositories work with both / and \ path separators
- Current Working Directory widget displays Windows-style paths correctly
- Full support for mapped network drives and UNC paths
- Handles Windows drive letters (C:, D:, etc.)

$3

#### Common Issues & Solutions

Issue: Powerline symbols showing as question marks or boxes
`powershell


Solution: Install a compatible Nerd Font

Issue: Git commands not recognized
`powershell


Check if Git is installed and in PATH

Issue: Permission errors during installation
`powershell


Use non-global installation (recommended)

Issue: "Execution Policy" errors in PowerShell
`powershell


Temporarily allow script execution

Issue: Windows Defender blocking execution
`powershell


If Windows Defender flags the binary:

`bash


Install in WSL Ubuntu/Debian

#### Terminal Settings (settings.json)
`json
{
"profiles": {
"defaults": {
"font": {
"face": "JetBrainsMono Nerd Font",
"size": 12
},
"colorScheme": "One Half Dark"
}
}
}
`

#### Claude Code Integration
Configure ccstatusline in your Claude Code settings:

Settings Location:
- Default: ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json)
- Custom: Set CLAUDE_CONFIG_DIR environment variable to use a different directory

For Bun users:
`json
{
"statusLine": "bunx ccstatusline-usage@latest"
}
`

For npm users:
`json
{
"statusLine": "npx ccstatusline-usage@latest"
}
`

> 💡 Custom Config Directory: If you use a non-standard Claude Code configuration directory, set the CLAUDE_CONFIG_DIR environment variable before running ccstatusline. The tool will automatically detect and use your custom location.

$3

ccstatusline is optimized for Windows performance:
- Bun runtime: Significantly faster startup times on Windows
- Caching: Intelligent caching of git status and file operations
- Async operations: Non-blocking command execution
- Memory efficient: Minimal resource usage

$3

Some widgets have Windows-specific optimizations:

- Current Working Directory: Displays Windows drive letters and UNC paths
- Git Widgets: Handle Windows line endings (CRLF) automatically
- Custom Commands: Support both PowerShell and cmd.exe commands
- Block Timer: Accounts for Windows timezone handling

---

📖 Usage

Once configured, ccstatusline automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions.

$3

#### API Usage Widgets (Fork Enhancement)
- Session Usage - 5-hour session utilization with progress bar (e.g., "Session: [████░░░░░░░░░░░] 29.0%")
- Weekly Usage - 7-day utilization with progress bar (e.g., "Weekly: [█░░░░░░░░░░░░░░] 7.0%")
- Reset Timer - Time until 5-hour session window resets (e.g., "2:59 hr")
- Context Bar - Visual context window usage with bar (e.g., "Context: [███████░░░░░░░░] 103k/200k (51%)")

#### Standard Widgets
- Model Name - Shows the current Claude model (e.g., "Claude 3.5 Sonnet")
- Claude Session ID - Shows the current session UUID
- Git Branch - Displays current git branch name
- Git Changes - Shows uncommitted insertions/deletions (e.g., "+42,-10")
- Git Worktree - Shows the name of the current git worktree
- Session Clock - Shows elapsed time since session start (e.g., "2hr 15m")
- Session Cost - Shows total session cost in USD (e.g., "$1.23")
- Block Timer - Shows time elapsed in current 5-hour block or progress bar
- Current Working Directory - Shows current working directory with configurable path segments
- Version - Shows Claude Code version
- Output Style - Shows the currently set output style in Claude Code
- Tokens Input - Shows input tokens used
- Tokens Output - Shows output tokens used
- Tokens Cached - Shows cached tokens used
- Tokens Total - Shows total tokens used
- Context Length - Shows current context length in tokens
- Context Percentage - Shows percentage of context limit used (dynamic: 1M for Sonnet 4.5 with [1m] suffix, 200k otherwise)
- Context Percentage (usable) - Shows percentage of usable context (dynamic: 800k for Sonnet 4.5 with [1m] suffix, 160k otherwise, accounting for auto-compact at 80%)
- Terminal Width - Shows detected terminal width (for debugging)
- Custom Text - Add your own custom text to the status line
- Custom Command - Execute shell commands and display their output (refreshes whenever the statusline is updated by Claude Code)
- Separator - Visual divider between widgets (customizable: |, -, comma, space)
- Flex Separator - Expands to fill available space

---

$3

> ⚠️ 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.

$3

The Block Timer widget helps you track your progress through Claude Code's 5-hour conversation blocks:

!Block Timer

Display Modes:
- Time Display - Shows elapsed time as "3hr 45m" (default)
- Progress Bar - Full width 32-character progress bar with percentage
- Progress Bar (Short) - Compact 16-character progress bar with percentage

Features:
- Automatically detects block boundaries from transcript timestamps
- Floors block start time to the hour for consistent tracking
- Shows "Block: 3hr 45m" in normal mode or just "3hr 45m" in raw value mode
- Progress bars show completion percentage (e.g., "[████████████████████████░░░░░░░░] 73.9%")
- Toggle between modes with the (p) key in the widgets editor

$3

Some widgets support "raw value" mode which displays just the value without a label:
- Normal: Model: Claude 3.5 Sonnet → Raw: Claude 3.5 Sonnet
- Normal: Session: 2hr 15m → Raw: 2hr 15m
- Normal: Block: 3hr 45m → Raw: 3hr 45m
- Normal: Ctx: 18.6k → Raw: 18.6k

---

$3

#### Custom Text Widget
Add static text to your status line. Perfect for:
- Project identifiers
- Environment indicators (dev/prod)
- Personal labels or reminders

#### Custom Command Widget
Execute shell commands and display their output dynamically:
- Refreshes whenever the statusline is updated by Claude Code
- Receives the full Claude Code JSON data via stdin (model info, session ID, transcript path, etc.)
- Displays command output inline in your status line
- Configurable timeout (default: 1000ms)
- Examples:
- pwd | xargs basename - Show current directory name
- node -v - Display Node.js version
- git rev-parse --short HEAD - Show current commit hash
- date +%H:%M - Display current time
- curl -s wttr.in?format="%t" - Show current temperature
- npx -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.

---

$3

ccusage is a tool that tracks and displays Claude Code usage metrics. You can integrate it directly into your status line:

1. Add a Custom Command widget
2. Set command: npx -y ccusage@latest statusline
3. Set timeout: 5000 (5 seconds for initial download)
4. Enable "preserve colors" to keep ccusage's color formatting

!ccusage integration

> 📄 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.

$3

When terminal width is detected, status lines automatically truncate with ellipsis (...) if they exceed the available width, preventing line wrapping.

---

📖 API Documentation

Complete API documentation is generated using TypeDoc and includes detailed information about:

- Core Types: Configuration interfaces, widget definitions, and render contexts
- Widget System: All available widgets and their customization options
- Utility Functions: Helper functions for rendering, configuration, and terminal handling
- Status Line Rendering: Core rendering engine and formatting options

$3

To generate the API documentation locally:

`bash


Generate documentation

The documentation will be generated in the docs/ directory and can be viewed by opening docs/index.html in your web browser.

$3

- Types: Core TypeScript interfaces and type definitions
- Widgets: Individual widget implementations and their APIs
- Utils: Utility functions for configuration, rendering, and terminal operations
- Main Module: Primary entry point and orchestration functions

---

🛠️ Development

$3

- Bun (v1.0+)
- Git
- Node.js 18+ (optional, for npm publishing)

$3

`bash


Clone the repository

`bash


Run in TUI mode (configuration)

`
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
`


🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

🗑️ Uninstall

`bash
npm uninstall -g ccstatusline-usage
rm -rf ~/.npm/_npx ~/.config/ccstatusline ~/.cache/ccstatusline*
jq 'del(.statusLine)' ~/.claude/settings.json > /tmp/cs.json && cat /tmp/cs.json > ~/.claude/settings.json
``

---

📄 License

MIT © Matthew Breedlove

---

👤 Author

Matthew Breedlove

- GitHub: @sirmalloc

---

🔗 Related Projects

- tweakcc - Customize Claude Code themes, thinking verbs, and more.
- ccusage - Track and display Claude Code usage metrics.

---

🙏 Acknowledgments

- Built for use with Claude Code CLI by Anthropic
- Powered by Ink for the terminal UI
- Made with ❤️ for the Claude Code community

---

Star History