@raavalabs/claude-statusline 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-04-14
+
+### Added
+
+- Initial release
+- 3 visual styles: Powerline (arrows), Capsule (pills), TUI (bordered box)
+- 4 color themes: Dark, Nord, Tokyo Night, Gruvbox
+- 2-line layout with full session metrics
+- Line 1: directory, git branch/status, model name, session name
+- Line 2: context bar, rate limits (5h/7d), token counts, lines changed, vim mode, duration
+- Git status caching with session-based `/tmp` files (5s TTL, atomic writes)
+- Context-aware color thresholds (green/yellow/orange/red)
+- Rate limit bars with threshold coloring
+- ANSI truecolor (24-bit) rendering
+- Cross-platform setup script (Linux, macOS, WSL2, Windows via Git Bash)
+- Nerd Font installation guide
+- Zero external dependencies (Python 3 stdlib only)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wihitha Deshan (Demi) Thathsara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# Claude Statusline
+
+A customizable powerline status line for [Claude Code](https://claude.ai/code) with **3 visual styles**, **4 color themes**, and comprehensive session metrics — all in a clean 2-line layout.
+
+Zero external dependencies. Python 3.8+ stdlib only.
+
+---
+
+## Styles
+
+### Powerline
+
+Classic powerline arrows with colored segments flowing left to right.
+
+```
+ Documents/Career  main ●  Sonnet 4  fix-auth 
+████████░░ 80% │ 5h: ████ 23% 7d: ████ 41% │ in:45k out:12k c:13k │ +150 -30 │ 5m
+```
+
+### Capsule
+
+Rounded pill-shaped segments with soft edges.
+
+```
+ Documents/Career   main ●   Sonnet 4   fix-auth 
+████████░░ 80% │ 5h: ████ 23% 7d: ████ 41% │ in:45k out:12k c:13k │ +150 -30 │ 5m
+```
+
+### TUI
+
+Bordered box using Unicode box-drawing characters (no Nerd Font required).
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Documents/Career │ main ● │ Sonnet 4 │ fix-auth                                ┃
+┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+┃ ████████░░ 80% │ 5h: ████ 23% 7d: ████ 41% │ in:45k out:12k c:13k │ +150 -30 ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+---
+
+## Themes
+
+| Theme | Style |
+|-------|-------|
+| **Dark** | Warm browns, cool blues, cyan accents |
+| **Nord** | Arctic blue palette based on [Nord](https://www.nordtheme.com/) |
+| **Tokyo Night** | Purple/blue palette based on [Tokyo Night](https://github.com/enkia/tokyo-night-vscode-theme) |
+| **Gruvbox** | Retro warm palette based on [Gruvbox](https://github.com/morhetz/gruvbox) |
+
+---
+
+## Quick Install
+
+```bash
+git clone https://github.com/demigod97/claude-statusline.git
+cd claude-statusline
+./setup.sh
+```
+
+With style and theme options:
+
+```bash
+./setup.sh --style capsule --theme tokyonight
+```
+
+### Via npx
+
+```bash
+npx @raavalabs/claude-statusline
+```
+
+### Manual Install
+
+```bash
+# Create directory
+mkdir -p ~/.claude/statusline
+
+# Copy files
+cp powerline.py ~/.claude/statusline/
+cp config.default.json ~/.claude/statusline/config.json
+
+# Add to Claude Code settings (~/.claude/settings.json)
+# Add this key to the top-level object:
+#   "statusLine": {
+#     "type": "command",
+#     "command": "python3 ~/.claude/statusline/powerline.py",
+#     "refreshInterval": 5
+#   }
+```
+
+---
+
+## What It Shows
+
+### Line 1 — Identity
+
+| Segment | Description | Example |
+|---------|-------------|---------|
+| Directory | Last N levels of working directory | `Documents/Career` |
+| Git | Branch, dirty, ahead/behind, staged/modified/untracked | ` main ● ↑2 +1 ~3 ?2` |
+| Model | Current Claude model | `Sonnet 4` |
+| Session | Session name (if set) | `fix-auth-bug` |
+
+### Line 2 — Metrics
+
+| Segment | Description | Example |
+|---------|-------------|---------|
+| Context | Context window usage bar + percentage | `████████░░ 80%` |
+| Rate Limits | 5-hour and 7-day usage with mini bars | `5h: ████ 23% 7d: ██░░ 41%` |
+| Tokens | Input, output, and cache token counts | `in:45k out:12k c:13k` |
+| Lines | Lines added/removed in session | `+150 -30` |
+| Vim Mode | Current vim mode (when vim is enabled) | `NORMAL` |
+| Duration | Session duration | `5m` or `1h 23m` |
+
+### Color Thresholds
+
+Context and rate limit bars change color based on usage:
+
+| Usage | Color |
+|-------|-------|
+| < 50% | Green |
+| 50-75% | Yellow |
+| 75-90% | Orange |
+| > 90% | Red |
+
+---
+
+## Configuration
+
+Edit `~/.claude/statusline/config.json`:
+
+```json
+{
+  "style": "powerline",
+  "theme": "dark",
+  "path_levels": 2,
+  "bar_width": 10
+}
+```
+
+| Key | Values | Default | Description |
+|-----|--------|---------|-------------|
+| `style` | `powerline`, `capsule`, `tui` | `powerline` | Visual style |
+| `theme` | `dark`, `nord`, `tokyonight`, `gruvbox` | `dark` | Color theme |
+| `path_levels` | `1`-`5` | `2` | Directory depth shown |
+| `bar_width` | `4`-`20` | `10` | Width of progress bars in characters |
+
+Changes take effect on the next refresh (every 5 seconds).
+
+---
+
+## Requirements
+
+- **Python 3.8+** (uses only stdlib — no `pip install` needed)
+- **Claude Code** installed and running
+- **Nerd Font** (required for powerline and capsule styles; TUI works without)
+
+### Font Setup
+
+The powerline and capsule styles use Nerd Font glyphs (arrows, rounded caps, git branch icon). Install a patched Nerd Font and configure your terminal to use it.
+
+**Recommended:** [JetBrains Mono Nerd Font](https://github.com/ryanoasis/nerd-fonts/releases/latest)
+
+Quick install:
+
+```bash
+# macOS
+brew install --cask font-jetbrains-mono-nerd-font
+
+# Linux (Arch)
+sudo pacman -S ttf-jetbrains-mono-nerd
+
+# Windows (Scoop)
+scoop bucket add nerd-fonts && scoop install JetBrainsMono-NF
+```
+
+Then set the font in your terminal settings. See [fonts/FONTS.md](fonts/FONTS.md) for detailed platform-specific instructions.
+
+---
+
+## How It Works
+
+1. Claude Code pipes JSON session data to the script via stdin every 5 seconds
+2. The script parses model info, context window, rate limits, cost, git status, etc.
+3. Git status is cached per-session in `/tmp` files with a 5-second TTL and atomic writes
+4. Output is rendered with ANSI truecolor (24-bit) escape codes
+5. The terminal displays the 2-line (or 5-line for TUI) status bar
+
+### stdin JSON Shape
+
+```json
+{
+  "model": { "display_name": "Sonnet 4" },
+  "cwd": "/home/user/project",
+  "context_window": {
+    "used_percentage": 45,
+    "current_usage": {
+      "input_tokens": 45000,
+      "output_tokens": 12000,
+      "cache_creation_input_tokens": 5000,
+      "cache_read_input_tokens": 8000
+    }
+  },
+  "cost": {
+    "total_duration_ms": 300000,
+    "total_lines_added": 150,
+    "total_lines_removed": 30
+  },
+  "rate_limits": {
+    "five_hour": { "used_percentage": 23 },
+    "seven_day": { "used_percentage": 41 }
+  },
+  "session_name": "fix-auth-bug",
+  "vim": { "mode": "NORMAL" },
+  "transcript_path": "/home/user/.claude/sessions/abc123.jsonl"
+}
+```
+
+---
+
+## Uninstall
+
+```bash
+./setup.sh --uninstall
+```
+
+Or manually:
+
+```bash
+rm -rf ~/.claude/statusline
+# Then remove the "statusLine" key from ~/.claude/settings.json
+```
+
+---
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Linux | Fully supported |
+| macOS | Fully supported |
+| WSL2 | Fully supported (use Windows Terminal with Nerd Font) |
+| Windows (Git Bash) | Supported (requires Python 3 in PATH) |
+
+---
+
+## Troubleshooting
+
+### Status line not showing
+
+1. Check that `~/.claude/settings.json` has the `statusLine` config
+2. Verify Python 3 works: `python3 --version`
+3. Test manually: `echo '{}' | python3 ~/.claude/statusline/powerline.py`
+4. Restart Claude Code
+
+### Broken glyphs / boxes instead of arrows
+
+Install a Nerd Font and set it as your terminal font. See [fonts/FONTS.md](fonts/FONTS.md).
+
+Or switch to TUI style which uses only Unicode box-drawing characters:
+
+```bash
+# Edit ~/.claude/statusline/config.json
+{"style": "tui", "theme": "dark", "path_levels": 2, "bar_width": 10}
+```
+
+### Git info not showing
+
+- Make sure you're in a git repository
+- Check that `git` is in PATH: `which git`
+- Git status is cached for 5 seconds — changes may take a moment to appear
+
+### Colors look wrong
+
+Your terminal must support truecolor (24-bit). Most modern terminals do:
+- Windows Terminal, iTerm2, Alacritty, Kitty, WezTerm, GNOME Terminal (3.24+)
+
+Test: `echo -e "\x1b[38;2;255;100;0mTruecolor test\x1b[0m"` — should show orange text.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Test with: `npm test` (or pipe JSON manually)
+4. Submit a PR
+
+### Adding a Theme
+
+Add a new entry to the `THEMES` dict in `powerline.py`. Each theme needs colors for: `dir`, `git`, `model`, `session`, `context`, `rate`, `tokens`, `lines`, `vim`, `duration`.
+
+### Adding a Style
+
+Add a new `render_<style>_line()` function and wire it into the `main()` function's style dispatch.
+
+---
+
+## License
+
+[MIT](LICENSE) - Wihitha Deshan (Demi) Thathsara

package/config.default.json

@@ -0,0 +1,6 @@
+{
+  "style": "powerline",
+  "theme": "dark",
+  "path_levels": 2,
+  "bar_width": 10
+}

package/fonts/FONTS.md

@@ -0,0 +1,159 @@
+# Nerd Font Installation Guide
+
+Claude Statusline uses **Nerd Font** glyphs for powerline arrows and capsule shapes. You need a patched Nerd Font installed and configured in your terminal.
+
+**Recommended:** [JetBrains Mono Nerd Font](https://github.com/ryanoasis/nerd-fonts/releases/latest)
+
+> The TUI style uses only Unicode box-drawing characters and works without Nerd Fonts.
+
+---
+
+## Windows Terminal (Windows / WSL2)
+
+### Option A: Manual Download
+
+1. Go to [Nerd Fonts Releases](https://github.com/ryanoasis/nerd-fonts/releases/latest)
+2. Download `JetBrainsMono.zip`
+3. Extract the zip
+4. Select all `.ttf` files → Right-click → **Install for all users**
+
+### Option B: PowerShell (Admin)
+
+```powershell
+# Download
+Invoke-WebRequest -Uri "https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip" -OutFile "$env:TEMP\JetBrainsMono.zip"
+
+# Extract
+Expand-Archive "$env:TEMP\JetBrainsMono.zip" -DestinationPath "$env:TEMP\JetBrainsMono" -Force
+
+# Install (copies to system Fonts folder)
+Get-ChildItem "$env:TEMP\JetBrainsMono\*.ttf" | ForEach-Object {
+    Copy-Item $_.FullName "$env:WINDIR\Fonts"
+    New-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts" -Name $_.BaseName -Value $_.Name -Force
+}
+```
+
+### Option C: Chocolatey
+
+```powershell
+choco install nerd-fonts-jetbrainsmono
+```
+
+### Option D: Scoop
+
+```powershell
+scoop bucket add nerd-fonts
+scoop install JetBrainsMono-NF
+```
+
+### Configure Windows Terminal
+
+1. Open **Windows Terminal**
+2. Click the dropdown arrow → **Settings** (or press `Ctrl+,`)
+3. Go to **Profiles** → **Defaults** (or your specific WSL profile)
+4. Click **Appearance**
+5. Set **Font face** to: `JetBrainsMono Nerd Font`
+6. **Save**
+
+> If you don't see the font, restart Windows Terminal after installing.
+
+---
+
+## macOS (iTerm2 / Terminal.app)
+
+### Option A: Homebrew
+
+```bash
+brew install --cask font-jetbrains-mono-nerd-font
+```
+
+### Option B: Manual Download
+
+1. Download from [Nerd Fonts Releases](https://github.com/ryanoasis/nerd-fonts/releases/latest)
+2. Extract and double-click each `.ttf` to install via Font Book
+
+### Configure iTerm2
+
+1. Open **iTerm2** → **Settings** (`Cmd+,`)
+2. Go to **Profiles** → **Text**
+3. Set **Font** to: `JetBrainsMono Nerd Font`
+
+### Configure Terminal.app
+
+1. Open **Terminal** → **Settings** (`Cmd+,`)
+2. Go to **Profiles** tab
+3. Click **Change** next to Font
+4. Select `JetBrainsMono Nerd Font`
+
+---
+
+## Linux
+
+### Option A: Package Manager
+
+```bash
+# Ubuntu/Debian (22.04+)
+sudo apt install fonts-jetbrains-mono
+
+# Fedora
+sudo dnf install jetbrains-mono-fonts
+
+# Arch
+sudo pacman -S ttf-jetbrains-mono-nerd
+```
+
+### Option B: Manual Install
+
+```bash
+# Download and install to user fonts
+mkdir -p ~/.local/share/fonts
+cd ~/.local/share/fonts
+
+curl -fLO "https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip"
+unzip JetBrainsMono.zip -d JetBrainsMono
+rm JetBrainsMono.zip
+
+# Refresh font cache
+fc-cache -fv
+```
+
+### Configure Your Terminal
+
+The exact steps depend on your terminal emulator:
+
+| Terminal | Where to set font |
+|----------|-------------------|
+| GNOME Terminal | Hamburger menu → Preferences → Profile → Custom font |
+| Konsole | Settings → Edit Current Profile → Appearance → Font |
+| Alacritty | `~/.config/alacritty/alacritty.toml` → `[font.normal]` → `family = "JetBrainsMono Nerd Font"` |
+| Kitty | `~/.config/kitty/kitty.conf` → `font_family JetBrainsMono Nerd Font` |
+| WezTerm | `~/.config/wezterm/wezterm.lua` → `config.font = wezterm.font("JetBrainsMono Nerd Font")` |
+
+---
+
+## Verify Installation
+
+Run this in your terminal to check if Nerd Font glyphs render correctly:
+
+```bash
+echo -e "\ue0b0 \ue0b2 \ue0b4 \ue0b6 \ue0a0"
+```
+
+You should see: a right arrow, left arrow, rounded right cap, rounded left cap, and a git branch icon.
+
+If you see boxes or question marks, your terminal is not using a Nerd Font.
+
+---
+
+## Alternative Fonts
+
+Any Nerd Font will work. Popular choices:
+
+| Font | Install |
+|------|---------|
+| FiraCode Nerd Font | `brew install --cask font-fira-code-nerd-font` |
+| Hack Nerd Font | `brew install --cask font-hack-nerd-font` |
+| CascadiaCode Nerd Font | `brew install --cask font-caskaydia-cove-nerd-font` |
+| Meslo Nerd Font | `brew install --cask font-meslo-lg-nerd-font` |
+
+Browse all: [nerdfonts.com](https://www.nerdfonts.com/)

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@raavalabs/claude-statusline",
+  "version": "1.0.0",
+  "description": "A customizable powerline status line for Claude Code with 3 styles, 4 themes, and full session metrics",
+  "author": "Wihitha Deshan (Demi) Thathsara",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/demigod97/claude-statusline.git"
+  },
+  "homepage": "https://github.com/demigod97/claude-statusline#readme",
+  "bugs": {
+    "url": "https://github.com/demigod97/claude-statusline/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "statusline",
+    "powerline",
+    "terminal",
+    "status-bar",
+    "nerd-fonts",
+    "cli"
+  ],
+  "bin": {
+    "claude-statusline": "./setup.sh"
+  },
+  "files": [
+    "powerline.py",
+    "config.default.json",
+    "setup.sh",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "fonts/"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "scripts": {
+    "setup": "./setup.sh",
+    "test": "echo '{\"model\":{\"display_name\":\"Sonnet 4\"},\"cwd\":\"/home/user/project\",\"context_window\":{\"used_percentage\":45,\"current_usage\":{\"input_tokens\":45000,\"output_tokens\":12000,\"cache_creation_input_tokens\":5000,\"cache_read_input_tokens\":8000}},\"cost\":{\"total_duration_ms\":300000,\"total_lines_added\":150,\"total_lines_removed\":30},\"rate_limits\":{\"five_hour\":{\"used_percentage\":23},\"seven_day\":{\"used_percentage\":41}}}' | python3 powerline.py"
+  }
+}