claude-statusline-powerline
Version:
Beautiful powerline-style statusline for Claude Code with git integration, session tracking, and cost monitoring
466 lines (378 loc) โข 12.2 kB
Markdown
# Claude Statusline Powerline
[](https://badge.fury.io/js/claude-statusline-powerline)
[](https://www.npmjs.com/package/claude-statusline-powerline)
[](https://packagephobia.com/result?p=claude-statusline-powerline)
[](https://github.com/spences10/claude-statusline-powerline/blob/main/LICENSE)
[](https://www.typescriptlang.org/)
A beautiful powerline-style statusline for Claude Code with git
integration, session tracking, and settings config IntelliSense
support.
## โจ Features
- ๐จ **Powerline styling** with beautiful separators and colors
- ๐ฟ **Enhanced git integration** - comprehensive status with
superscript symbols
- ๐ **Directory display** - current working directory
- ๐ฑ **Model info** - shows which Claude model you're using
- ๐ฐ **Session tracking** - real-time token usage and cost estimation
- ๐ **Context monitoring** - smart warnings at 75% and 90% usage
- ๐ง **Context caching** - displays cache hit rate and warm/cold
sessions
- ๐ฏ **Settings IntelliSense** - autocomplete, validation, and hover
docs in settings files
## ๐ Available Segments
| Segment | Icon | Description | Example Output |
| ------------- | ---- | ----------------------------------------- | ------------------------------ |
| **Model** | โก | Shows the Claude model being used | `โก Claude Sonnet 4` |
| **Directory** | ๐ | Current working directory name | `๐ my-project` |
| **Git** | ๐ฟ | Git branch and status with superscript | `๐ฟ main โบ3 ห1 แต2` |
| **Session** | ๐ฐ | Token usage, cost, and context monitoring | `๐ฐ 1.2k โข $0.01 999k left` |
| **Usage** | ๐ | Aggregated usage statistics from database | `๐ 29.9k โข $8.83 7d` |
| **Context** | ๐ง | Cache performance and session state | `๐ง 10.5k cached (70% reused)` |
All segments can be **shown/hidden** (via `lines` configuration),
**reordered**, and **customized** through the configuration file.
## Themes & Configuration
### ๐จ Color Themes:
- **`dark`** - Default professional dark theme
- **`electric`** - High-contrast electric theme with vibrant colors
- **`night-owl`** - Dark theme inspired by Night Owl
- **`dracula`** - Popular Dracula theme colors
- **`gruvbox`** - Retro groove color scheme
- **`one-dark`** - Atom's One Dark theme
- **`monokai`** - Classic Monokai theme
- **`nord`** - Arctic, north-bluish theme
- **`tokyo-night`** - Modern dark theme
- **`solarized-light`** - Light theme based on Solarized
- **`gruvbox-light`** - Light variant of Gruvbox
- **`alucard`** - Dark red theme inspired by Hellsing
### โก Available Separator Styles:
- `thick` - Standard powerline separator โถ
- `thin` - Thin powerline separator โ
- `curvy` - Curved separator (Victor Mono compatible)
- `angly` - Angular separator \
- `angly2` - Alternative angular separator /
- `flame` - Dramatic flame-style effect ๐ฅ
- `wave` - Wave-like alternating effect ๐
- `lightning` - High-energy lightning effect โก
- `none` - No separator
## ๐ง Configuration
### JSON Configuration with IntelliSense
Claude Statusline Powerline uses JSON configuration files with
**IntelliSense support**:
**Primary config location:**
`~/.claude/claude-statusline-powerline.json`
**Project-specific override:**
`./.claude/claude-statusline-powerline.json`
### โก IntelliSense Features
- **๐ฏ Autocomplete** - All available options as you type
- **๐ Hover documentation** - Descriptions for every property
- **๐จ Color validation** - Hex color patterns with examples
### Example Configuration
```json
{
"$schema": "https://raw.githubusercontent.com/spences10/claude-statusline-powerline/main/statusline.schema.json",
"color_theme": "dark",
"font_profile": "nerd-font",
"segment_config": {
"segments": [
{
"type": "model"
},
{
"type": "directory"
},
{
"type": "git"
},
{
"type": "session"
},
{
"type": "usage"
},
{
"type": "context"
}
]
}
}
```
### Configuration Options
**Color Themes:**
- `"dark"` - Classic blue/gray/yellow theme
- `"electric"` - Purple/cyan/red theme
- `"night-owl"` - Dark theme with blue/purple accents
- `"dracula"` - Purple/pink/green Dracula theme
- `"gruvbox"` - Warm retro colors
- `"one-dark"` - Blue/purple Atom theme
- `"monokai"` - Classic yellow/orange/green
- `"nord"` - Cool blue/teal arctic theme
- `"tokyo-night"` - Modern purple/blue theme
- `"solarized-light"` - Light theme with blue accents
- `"gruvbox-light"` - Light warm theme
- `"alucard"` - Dark red/crimson theme
**Font Profiles:**
- `"powerline"` - Basic powerline font support
- `"nerd-font"` - Full Nerd Font support with more icons
### Multi-line Layout & Segment Ordering
Control segment layout and ordering using the `lines` configuration:
```json
{
"segment_config": {
"lines": [
{
"directory": true,
"git": true
},
{
"model": true,
"session": true
},
{
"context": true
}
],
"segments": [
{ "type": "git" },
{ "type": "model" },
{ "type": "directory" },
{ "type": "session" }
]
}
}
```
**Control rules:**
- **Visibility**: Only segments present in `lines` configuration are
shown
- **Between lines**: Order determined by position in `lines` array
- **Within lines**: Order determined by property order in each line
object
- **Styling**: Use `segments` array to configure colors, icons,
separators, etc.
### Custom Icons
Customize the icons used in each segment with the `icons` property in
segment styles:
```json
{
"segment_config": {
"segments": [
{
"type": "model",
"style": {
"icons": {
"ai": "๐ค"
}
}
},
{
"type": "directory",
"style": {
"icons": {
"folder": "๐๏ธ"
}
}
},
{
"type": "git",
"style": {
"icons": {
"branch": "๐ฟ",
"clean": "โ
",
"dirty": "โ ๏ธ"
}
}
},
{
"type": "session",
"style": {
"icons": {
"cost": "๐ฒ"
}
}
}
]
}
}
```
**Available Icons:**
- `ai` - AI/Model segment icon
- `folder` - Directory/folder icon
- `branch` - Git branch icon
- `clean` - Clean git status icon
- `dirty` - Dirty git status icon (fallback)
- `ahead` - Commits ahead of remote
- `behind` - Commits behind remote
- `conflicts` - Merge conflicts
- `staged_add` - Staged additions/modifications
- `staged_del` - Staged deletions
- `unstaged` - Unstaged working directory changes
- `untracked` - Untracked files
- `cost` - Session cost/usage icon
You can use any Unicode character, emoji, or Nerd Font icon code
(e.g., `\uF07B` for folder).
### Custom Separators
Customize separators for individual segments or git states:
```json
{
"segment_config": {
"segments": [
{
"type": "git",
"style": {
"separator": {
"clean": "thick",
"dirty": "lightning",
"conflicts": "flame"
}
}
},
{
"type": "model",
"style": {
"separator": {
"style": "curvy"
}
}
}
]
}
}
```
### Single Line Layout
For simple single-line statuslines, just omit the `lines`
configuration:
```json
{
"segment_config": {
"segments": [
{ "type": "model" },
{ "type": "directory" },
{ "type": "git" },
{ "type": "session" }
]
}
}
```
Segments will appear in the order enabled segments are found.
## ๐ฟ Enhanced Git Status
The git segment displays comprehensive repository information using
beautiful superscript symbols optimized for Victor Mono font:
### Git Status Symbols
**Powerline Font Profile:**
- `โก2` - 2 commits ahead of remote
- `โฃ1` - 1 commit behind remote
- `โ ๏ธ` - Merge conflicts present
- `โบ3` - 3 staged additions/modifications
- `โป1` - 1 staged deletion
- `ห2` - 2 unstaged changes in working directory
- `แต4` - 4 untracked files
**Example outputs:**
- Clean repo: ` main โ`
- Complex status: ` main โก2 โบ3 ห1 แต2`
- With conflicts: ` main โ ๏ธ โบ1`
- Behind remote: ` main โฃ3 ห2`
### Truncation Control
Long segment content is automatically truncated. You can configure the
maximum length per segment:
```json
{
"segment_config": {
"segments": [
{
"type": "git",
"style": {
"truncation_length": 15
}
}
]
}
}
```
## ๐ฆ Installation
Install globally with your preferred package manager:
```bash
# npm
npm install -g claude-statusline-powerline
# pnpm
pnpm add -g claude-statusline-powerline
# bun
bun add -g claude-statusline-powerline
# volta
volta install claude-statusline-powerline
```
The statusline will be automatically configured for Claude Code with a
default config file!
## Font Setup
For the best experience, use a powerline-compatible font:
**Recommended fonts:**
- **Victor Mono** (built and tested with this)
- Any [Nerd Font](https://www.nerdfonts.com/)
The statusline uses these symbols: `(powerline separators) and` (git
branch)
## How It Works
Claude Code sends session information via stdin as JSON:
```json
{
"session_id": "...",
"model": { "display_name": "Claude Sonnet 4" },
"workspace": { "current_dir": "/path/to/project" }
}
```
The statusline script processes this and outputs a coloured
powerline-style status.
## ๐๏ธ Local Usage Database
Claude Statusline Powerline maintains a local SQLite database at
`~/.claude/statusline-usage.db` to track usage analytics and power
both the **Session** and **Usage** segments with high-performance data
access.
**Stored Data:**
- **Session records** with start/end times and token usage
- **Daily summaries** with total costs and model usage
- **Project mapping** linking sessions to directory paths
- **Cache performance** metrics for optimization insights
**Performance Benefits:**
- **Session segment**: 31x faster than file parsing (0.11ms vs 3.44ms)
- **Usage segment**: Pre-aggregated daily/weekly/monthly summaries
- **Real-time insights** without impacting statusline responsiveness
- **Efficient SQLite queries** for instant data access
**These segments are database-only** and require the SQLite database
to function. They are not included in the default configuration but
can be enabled by adding them to your config:
```json
{
"segment_config": {
"segments": [{ "type": "session" }, { "type": "usage" }]
}
}
```
The database automatically tracks usage data as you use Claude Code.
If the database is unavailable, these segments simply won't appear.
## Segments
1. **Model** - Shows the Claude model name
2. **Directory** - Shows current directory name
3. **Git** - Enhanced status with superscript symbols
4. **Session** - Current session token usage, cost, and context
monitoring
- **Powered by SQLite database**
- Format: `๐ฐ {tokens}k โข ${cost} {context}`
- Context shows: remaining tokens (< 75%), percentage (75-89%), or
warning (!90%+)
- Must be manually enabled in configuration
5. **Usage** - Aggregated usage statistics across time periods
- **Powered by SQLite database** with pre-calculated summaries
- Format: `๐ {tokens}k โข ${cost} {period}`
- Shows daily/weekly/monthly aggregated data
- Must be manually enabled in configuration
6. **Context** - Cache performance and session state
- Shows cache hit rate and total cached tokens for warm sessions
- Displays "Cold" for new sessions without significant cache usage
## Credits
This project was inspired by
[claude-powerline](https://github.com/Owloops/claude-powerline) by
[@Owloops](https://github.com/Owloops) - thanks for the initial
concept and inspiration!
Built for
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) by
[Anthropic](https://www.anthropic.com/).
## License
MIT