Claude Code Status Bar

A real-time status bar for monitoring Claude Code API usage, integrating directly with Claude Code's statusLine feature to display token usage, costs, and burn rate at the bottom of your interface.

中文文档 / Chinese Documentation

What It Does

This tool adds a compact status bar to Claude Code that shows:

• Current model being used (reads from Claude Code context)
• Real token usage from your Claude session
• Cost calculation in USD based on actual usage
• Git branch and folder information
• Animated transitions for smooth updates

Example output:

claude-opus-4-1-20250805 | 19.43k | $1.46 | ⎇ main | 📁 my-project

Features

• Real Token Data: Reads actual token usage from Claude Code transcript files
• Real-time Model Detection: Automatically detects which Claude model you're using
• Accurate Cost Calculation: Calculates costs based on actual model pricing and real usage
• Git Integration: Shows current git branch
• Smooth Animations: Animated transitions when values change
• Color-coded Token Usage:
  • 🟢 Green: < 20k tokens
  • 🟡 Yellow: 20k-50k tokens
  • 🟠 Orange: 50k-100k tokens
  • 🔴 Red: > 100k tokens

Quick Start

One-Line Installation (No Authentication Required)

curl -fsSL https://raw.githubusercontent.com/B143KC47/ClaudeCode_status_bar/main/web-install.sh | bash

Features:

• ✅ No password or authentication required
• ✅ No sudo needed
• ✅ Downloads directly from public GitHub repository
• ✅ Installs to user home directory (~/.claude/)

This will:

1. Download and install the status bar to ~/.claude/ClaudeCode_status_bar
2. Auto-configure ~/.claude/settings.json to use a local Node command
3. If a settings file already exists, it will print a snippet for you to paste
4. Display instructions for restarting Claude Code

After installation, restart Claude Code to see the status bar at the bottom of your interface.

One-Line Uninstall

npm uninstall -g claude-code-status-bar && rm -rf ~/.claude/ClaudeCode_status_bar && sed -i '/"statusLine"/,/}/d' ~/.claude/settings.json

This will:

1. Remove the global npm package (if installed)
2. Delete the local installation directory
3. Remove the statusLine configuration from your Claude settings

Installation Options

Option 1: Automatic Installation (Recommended)

Use the one-line installer above for a completely passwordless and authentication-free setup. Alternatively, if you prefer to review the script first:

# Download and review the script
curl -fsSL https://raw.githubusercontent.com/B143KC47/ClaudeCode_status_bar/main/web-install.sh -o web-install.sh
cat web-install.sh  # Review the script
bash web-install.sh  # Run installation

Or clone and use the local install script:

git clone https://github.com/B143KC47/ClaudeCode_status_bar.git
cd ClaudeCode_status_bar
./install.sh

Option 2: Manual Installation

1. Clone this repository:

   git clone https://github.com/B143KC47/ClaudeCode_status_bar.git
   cd ClaudeCode_status_bar

2. Install dependencies:

   npm install

3. Install globally (optional):

   npm install -g .

4. Configure Claude Code by editing ~/.claude/settings.json:

   {
     "statusLine": {
       "type": "command",
       "command": "claude-statusbar",
       "padding": 0
     }
   }

   If you didn't install globally (passwordless web install), use a local Node command:

   {
     "statusLine": {
       "type": "command",
       "command": "node ~/.claude/ClaudeCode_status_bar/bin/statusline.js",
       "padding": 0
     }
   }

5. Restart Claude Code to see the status bar at the bottom of your interface.

Web Interface (Dashboard)

Run the Next.js web application for a demonstration dashboard with mock data.

1. Install dependencies:

   npm install

2. Run the development server:

   npm run dev

3. Open http://localhost:3000 in your browser

Note: The web dashboard uses mock data for demonstration purposes. The actual CLI status bar reads real token data from Claude Code.

How It Works

Architecture

1. Claude Code Integration

   • Claude Code executes the status bar command approximately every 300ms
   • Passes context JSON via stdin containing model info, version, and working directory
   • Displays the first line of output at the bottom of the interface

2. Data Flow

   Claude Code → Context JSON → stdin → statusline.js → Processing → stdout → Status Bar
   

3. Model Detection

   • Reads model.display_name or model.id from Claude Code context
   • No hardcoding - always shows the actual model you're using

Technical Details

The CLI tool (bin/statusline.js):

• Reads JSON context from stdin (provided by Claude Code)
• Extracts model information and session ID from context
• Reads actual token usage from Claude Code transcript files in ~/.claude/projects/
• Calculates costs based on real model pricing
• Implements smooth animations using state persistence
• Formats output with ANSI color codes
• Outputs single line to stdout

Customization

How Token Tracking Works

The status bar reads real token usage data from Claude Code:

1. Session Detection: Identifies your current Claude session from context
2. Transcript Reading: Reads JSONL transcript files from ~/.claude/projects/
3. Token Extraction: Extracts actual output tokens from assistant messages
4. Cost Calculation: Uses official Claude pricing for accurate cost tracking
5. State Persistence: Maintains state between updates for smooth animations

Customizing the Display

To customize the status bar output, modify the formatStatusLine() function in bin/statusline.js:

function formatStatusLine(data) {
  // Customize which information to display
  // Modify colors, separators, or add/remove fields
  // The function returns a single line string
}

Tech Stack

• Next.js 14: App Router with Server Actions
• TypeScript: Type-safe development
• Tailwind CSS: Responsive styling
• React Server Actions: Using 'use server' directive
• useFormState Hook: React DOM hook for server action state management
• Node.js CLI: Real-time token tracking for Claude Code

Implementation Details

Real Token Usage Tracking

The CLI status bar displays real token usage data from your Claude Code sessions:

• Full Model Version: Shows complete model ID (e.g., claude-opus-4-1-20250805)
• Actual Token Counts: Reads real output tokens from Claude Code transcript files
• Accurate Costs: Calculates costs using official Claude API pricing
• Session Tracking: Tracks tokens for your current session
• Smooth Animations: Uses state persistence for animated value transitions

Web Dashboard (Demo)

The Next.js web application provides a demonstration interface:

• Uses React Server Actions with 'use server' directive
• Implements useFormState hook for form state management
• Shows mock data for demonstration purposes
• Auto-refreshes every 5 seconds

Troubleshooting

Status bar not showing? ✅ FIXED!

The issue has been resolved! The problem was that the Claude Code settings file (~/.claude/settings.json) was missing the statusLine configuration. The configuration has been added:

{
  "model": "claude-opus-4-20250514",
  "statusLine": {
    "type": "command",
    "command": "claude-statusbar",
    "padding": 0
  }
}

To see the status bar:

1. Restart Claude Code (the configuration is already in place)
2. The status bar should appear at the bottom of your interface

If you still don't see it:

1. Ensure the script is executable: chmod +x bin/statusline.js
2. Check that the command in settings.json is correct:
   • If installed globally: "command": "claude-statusbar"
   • If using local path: "command": "/full/path/to/bin/statusline.js"
3. Restart Claude Code after configuration changes
4. Check if the command works manually: echo '{"model":{"display_name":"test"}}' | claude-statusbar
5. On Windows, test with PowerShell: echo '{"model":{"display_name":"test"}}' | node bin/statusline.js

Wrong model displayed?

• The tool reads the model from Claude Code's context automatically
• If showing "claude-3-opus" as default, Claude Code might not be passing model info
• Try the advanced version which has better fallback handling

Colors not displaying?

• Claude Code supports ANSI color codes
• If colors aren't showing, try --no-color option
• On Windows, ensure your terminal supports ANSI codes

Development

Project Structure

├── app/                    # Next.js app directory
│   ├── actions/           # Server actions
│   ├── components/        # React components
│   └── page.tsx          # Main page
├── bin/                   # CLI scripts
│   └── statusline.js     # Claude Code status line script
├── package.json          # Dependencies and scripts
└── README.md            # This file

Testing Locally

Test the status bar without Claude Code:

# Test basic version
echo '{"model":{"display_name":"claude-3.5-sonnet"}}' | node bin/statusline.js

Contributing

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

Acknowledgments

• Inspired by the Claude Code statusLine documentation
• Based on the ccusage statusline format options
• Built for the Claude Code community

License

MIT

---

Made with ❤️ for better Claude Code usage monitoring