claude-limitline

A powerline-style statusline for Claude Code showing real-time usage limits, git info, and model details.

Features

• Powerline Style - Beautiful segmented display with smooth transitions
• 5-Hour Block Limit - Shows current usage percentage with time remaining until reset
• 7-Day Rolling Limit - Tracks weekly usage with progress indicator
• Repository Name - Displays current project/directory name
• Git Branch - Shows current branch with dirty indicator (●)
• Claude Model - Displays the active model (Opus 4.5, Sonnet 4, etc.)
• Multiple Themes - Dark, light, nord, gruvbox, tokyo-night, and rose-pine
• Real-time Tracking - Uses Anthropic's OAuth usage API for accurate data
• Cross-Platform - Works on Windows, macOS, and Linux

Example Output

 claude-limitline  main ●   Opus 4.5   12% (3h20m)   45% (wk 85%)

Prerequisites

• Node.js 18.0.0 or higher
• Claude Code CLI installed and authenticated (for OAuth token)
• Nerd Font (recommended, for powerline symbols)

Installation

From npm (recommended)

npm install -g claude-limitline

From Source

See Development section, then run npm link to make it available globally.

Quick Start

Add to your Claude Code settings file (~/.claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "npx claude-limitline"
  }
}

That's it! The status line will now show your usage limits in Claude Code.

Tip: For faster startup, use "command": "claude-limitline" after installing globally.

Configuration

Create a claude-limitline.json file in your Claude config directory (~/.claude/claude-limitline.json) or .claude-limitline.json in your current working directory:

{
  "display": {
    "style": "powerline",
    "useNerdFonts": true,
    "compactMode": "auto",
    "compactWidth": 80
  },
  "directory": {
    "enabled": true
  },
  "git": {
    "enabled": true
  },
  "model": {
    "enabled": true
  },
  "block": {
    "enabled": true,
    "displayStyle": "text",
    "barWidth": 10,
    "showTimeRemaining": true
  },
  "weekly": {
    "enabled": true,
    "displayStyle": "text",
    "barWidth": 10,
    "showWeekProgress": true,
    "viewMode": "smart"
  },
  "budget": {
    "pollInterval": 15,
    "warningThreshold": 80
  },
  "theme": "dark",
  "segmentOrder": ["directory", "git", "model", "block", "weekly"],
  "showTrend": true
}

Configuration Options

Option	Description	Default
display.useNerdFonts	Use Nerd Font symbols for powerline	true
display.compactMode	"auto", "always", or "never"	"auto"
display.compactWidth	Terminal width threshold for compact mode	80
directory.enabled	Show repository/directory name	true
git.enabled	Show git branch with dirty indicator	true
model.enabled	Show Claude model name	true
block.enabled	Show 5-hour block usage	true
block.displayStyle	"bar" or "text"	"text"
block.barWidth	Width of progress bar in characters	10
block.showTimeRemaining	Show time until block resets	true
weekly.enabled	Show 7-day rolling usage	true
weekly.displayStyle	"bar" or "text"	"text"
weekly.barWidth	Width of progress bar in characters	10
weekly.showWeekProgress	Show week progress percentage	true
weekly.viewMode	"simple" or "smart"	"simple"
budget.pollInterval	Minutes between API calls	15
budget.warningThreshold	Percentage to trigger warning color	80
theme	Color theme name	"dark"
segmentOrder	Array to customize segment order	["directory", "git", "model", "block", "weekly"]
showTrend	Show ↑↓ arrows for usage changes	true

Weekly View Modes

The weekly segment supports two view modes for displaying usage limits:

Mode	Description	Example
simple	Shows overall weekly usage only (default)	○ 47% (wk 85%)
smart	Model-aware: shows Sonnet + Overall when using Sonnet	◇7% | ○47% (wk 85%)

Note: Model-specific limits (Opus/Sonnet) are only available on certain subscription tiers. Smart mode shows only overall usage when using Opus/Haiku, and shows both Sonnet and overall when using Sonnet.

Available Themes

• dark - Default dark theme with warm browns and cool cyans
• light - Light background theme with vibrant colors
• nord - Nord color palette
• gruvbox - Gruvbox color palette
• tokyo-night - Tokyo Night color palette
• rose-pine - Rosé Pine color palette

Segments

The statusline displays the following segments (all configurable):

Segment	Description	Color (dark theme)
Directory	Current repo/project name	Brown/Orange
Git	Branch name + dirty indicator (●)	Dark Gray
Model	Claude model (Opus 4.5, Sonnet 4, etc.)	Dark Gray
Block	5-hour usage % + time remaining	Cyan (warning: Orange, critical: Red)
Weekly	7-day usage % + week progress	Green

How It Works

claude-limitline retrieves data from two sources:

1. Hook Data (stdin) - Claude Code passes JSON with model info, workspace, and session data
2. Usage API - Fetches usage limits from Anthropic's OAuth usage endpoint

OAuth Token Location

The tool automatically retrieves your OAuth token from Claude Code's credential storage:

Platform	Location
macOS	Keychain (Claude Code-credentials service)
Windows	Credential Manager or ~/.claude/.credentials.json
Linux	secret-tool (GNOME Keyring) or ~/.claude/.credentials.json

Note: On macOS, the token is read directly from the system Keychain where Claude Code stores it. No additional configuration is needed—just make sure you're logged into Claude Code (claude --login).

Development

git clone https://github.com/tylergraydev/claude-limitline.git
cd claude-limitline
npm install
npm run build    # Build once
npm run dev      # Watch mode

Testing

The project uses Vitest for testing with 170 tests covering config loading, themes, segments, utilities, and rendering.

npm test              # Run tests once
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Test Structure

File	Tests	Coverage
src/config/loader.test.ts	7	Config loading, merging, fallbacks
src/themes/index.test.ts	37	Theme retrieval, color validation
src/segments/block.test.ts	8	Block segment, time calculations
src/segments/weekly.test.ts	13	Weekly segment, week progress
src/utils/oauth.test.ts	19	API responses, caching, trends, macOS keychain
src/utils/claude-hook.test.ts	21	Model name formatting
src/utils/environment.test.ts	20	Git branch, directory detection
src/utils/terminal.test.ts	13	Terminal width, ANSI handling
src/utils/logger.test.ts	8	Debug/error logging
src/renderer.test.ts	24	Segment rendering, ordering, view modes

Debug Mode

Enable debug logging to troubleshoot issues:

# Linux/macOS
CLAUDE_LIMITLINE_DEBUG=true claude-limitline

# Windows (PowerShell)
$env:CLAUDE_LIMITLINE_DEBUG="true"; claude-limitline

# Windows (CMD)
set CLAUDE_LIMITLINE_DEBUG=true && claude-limitline

Debug output is written to stderr so it won't interfere with the status line output.

Troubleshooting

Model not showing

The model is passed via stdin from Claude Code. If running standalone, pipe in hook data:

echo '{"model":{"id":"claude-opus-4-5-20251101"}}' | claude-limitline

"No data" or empty output

1. Check OAuth token: Make sure you're logged into Claude Code (claude --login)
2. Check credentials file: Verify ~/.claude/.credentials.json exists
3. Enable debug mode: Run with CLAUDE_LIMITLINE_DEBUG=true

Git branch not showing

Make sure you're in a git repository. The git segment only appears when a .git directory is found.

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 amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by claude-powerline
• Built for use with Claude Code