# ClaudeUsageStatusLine - Installation Guide

Display real-time Claude usage statistics directly in Claude Code's status line with beautiful colored output.

## Quick Start

### Windows

```powershell
# Extract the archive
Expand-Archive ClaudeUsageStatusLine-win-x64.zip -DestinationPath .\ClaudeUsageStatusLine

# Navigate to the directory
cd ClaudeUsageStatusLine

# Run the installer
.\install.exe

# Restart Claude Code
# The status line will appear automatically
```

### Linux / macOS

```bash
# Extract the archive
unzip ClaudeUsageStatusLine-{platform}.zip
cd ClaudeUsageStatusLine

# Run the installer
bash install.sh

# Restart Claude Code
# The status line will appear automatically
```

**Platform options:**
- `linux-x64` - Linux x64
- `osx-x64` - macOS Intel (x64)
- `osx-arm64` - macOS Apple Silicon (M1/M2/M3)

## What the Installer Does

1. **Copies executable** to installation directory:
   - Windows: `%LOCALAPPDATA%\ClaudeUsageStatusLine\`
   - Linux/Mac: `~/.local/bin/`

2. **Configures Claude Code** by updating `~/.claude/settings.json`:
   ```json
   {
     "statusLine": {
       "type": "command",
       "command": "/path/to/ClaudeUsageStatusline",
       "padding": 0
     }
   }
   ```

3. **Creates backup** of your existing settings (if any):
   - `~/.claude/settings.backup.{timestamp}.json`

4. **Sets permissions** on Unix systems (makes executable)

## Configuration

### Authentication

Run `claude auth login` to authenticate. This creates `~/.claude/.credentials.json` which the status line reads automatically.

## Status Line Format

Once configured, you'll see a 2-line status line in Claude Code:

```
~/Projects/MyApp | claude-sonnet-4-5
Session 2% | All: 1% (↻4h) | Sonnet: 1% (↻155h) | Extra: 12.56€/100€ | Ctx: 49%
```

### Color Coding

- **Green (0-50%)**: Good - plenty of capacity
- **Yellow (50-80%)**: Moderate - getting close
- **Red (80-100%)**: High - approaching limit
- **Blue**: Directory path
- **Cyan**: Model name

### What's Displayed

- **Session**: 5-hour rolling window usage
- **All**: 7-day all models usage
- **Sonnet**: 7-day Sonnet-only usage (Claude Max only)
- **Opus**: 7-day Opus-only usage (Claude Max only)
- **Extra**: Additional credits usage (Pro/Max with credits)
- **Ctx**: Context window usage percentage

**Note:** Fields vary by subscription tier (Free, Pro, Max, API).

## Advanced Usage

### Silent Installation

Install without prompts (useful for scripts):

**Windows:**
```powershell
.\install.exe --silent
```

**Linux/macOS:**
```bash
bash install.sh --silent
```

### Uninstall

Remove the statusLine configuration from Claude Code:

**Windows:**
```powershell
.\install.exe --uninstall
```

**Linux/macOS:**
```bash
bash install.sh --uninstall
```

**Note:** This doesn't delete the executable. To fully remove:

**Windows:**
```powershell
Remove-Item -Recurse "$env:LOCALAPPDATA\ClaudeUsageStatusLine"
```

**Linux/Mac:**
```bash
rm ~/.local/bin/ClaudeUsageStatusline
rm ~/.local/bin/appsettings.json
```

### Logs

Logs are stored in the installation directory:

**Windows:**
```
%LOCALAPPDATA%\ClaudeUsageStatusLine\logs\statusline-{date}.log
```

**Linux/Mac:**
```
~/.local/bin/logs/statusline-{date}.log
```

Logs contain only warnings and errors (not every status line query).

## Troubleshooting

### "Usage: error" appears

**Cause:** Invalid or missing credentials

**Solution:**
1. Run `claude auth login` to refresh your credentials
2. Verify that `~/.claude/.credentials.json` exists
3. Check logs for detailed error

### Status line doesn't appear

**Cause:** Claude Code not restarted or settings.json not updated

**Solution:**
1. Fully restart Claude Code (close and reopen)
2. Verify `~/.claude/settings.json` contains statusLine config
3. Run installer again if settings.json is missing the config
4. Check installer output for errors

### No colors in output

**Cause:** Terminal doesn't support ANSI colors or NO_COLOR is set

**Solution:**
1. Use a modern terminal (Windows Terminal, iTerm2, etc.)
2. Check if `NO_COLOR` environment variable is set: `echo $NO_COLOR`
3. Unset NO_COLOR if needed: `unset NO_COLOR`



### "Permission denied" on Linux/Mac

**Cause:** Executable permissions not set

**Solution:**
```bash
chmod +x ~/.local/bin/ClaudeUsageStatusline
# Or in installation directory
chmod +x ./ClaudeUsageStatusline
```

## Platform-Specific Notes

### Windows

- Requires Windows 10 or later
- Works with Windows Terminal, PowerShell 7+, or Command Prompt
- Path uses backslashes: `C:\Users\...\ClaudeUsageStatusLine\`

### Linux

- Tested on Ubuntu 22.04+ but should work on any modern Linux
- Installer uses `chmod` to set permissions
- Credentials are read automatically from `~/.claude/.credentials.json`

### macOS

- Requires macOS 12 (Monterey) or later
- **Intel Macs**: Use `osx-x64` build
- **Apple Silicon (M1/M2/M3)**: Use `osx-arm64` build
- First run may show security warning - allow in System Preferences

## Updating

To update to a newer version:

1. Download the new release archive
2. Extract it
3. Run the installer again

The installer will:
- Overwrite the old executable
- Keep your logs
- Update settings.json if needed


## Support

No support for this tool, it's free:

1. Check the logs first: `{installation-dir}/logs/statusline-{date}.log`
2. Run `claude auth login` to refresh your credentials
3. Try running the executable directly to see error messages


## License

MIT License - See LICENSE file


