# ClaudeUsageStatusLine - Installation Guide

Display real-time **Claude and z.ai (GLM)** usage statistics directly in Claude Code's status line with beautiful colored output. The provider is auto-detected from the model name sent by Claude Code — any model whose name contains `glm` (e.g. `glm-5.1`) routes to z.ai, everything else routes to Claude.

## 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 (Claude)

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

### z.ai Authentication (GLM models)

z.ai uses **two different tokens**:

- An **API key** (`ZAI_API_KEY`) — used for chat completions. *Not required* by the status line.
- A **web session JWT** — required by the billing endpoint `api.z.ai/api/platform-charge-zai/business/accountBalance` that the status line calls. This token is *different* from the API key and must be copied manually from your browser.

**Why manual?** The z.ai sign-in endpoint is protected by a mandatory TianCaptcha (Aliyun 阿里云验证码) which detects and blocks all automation tools (Selenium, Playwright, Puppeteer, etc.). There is no headless login path — the token has to come from a real browser session you control.

#### Step-by-step: copy the session JWT

1. Open **https://z.ai/manage-apikey/billing** in your regular browser.
2. Log in (and solve the captcha if prompted).
3. Press **F12** to open DevTools, then click the **Network** tab.
4. Refresh the page with **F5**.
5. In the Network request list, click the request named **`accountBalance`**.
6. Open the **Headers** sub-tab on the right and find `Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...`.
7. Copy the JWT **without** the `Bearer ` prefix (the token starts with `eyJhbGciOiJIUzUxMiJ9`).

#### Save the JWT with the helper tool

A companion binary `ClaudeUsageStatusline.ZaiRefresh` is shipped alongside the main status line executable. It guides you through the copy, validates the JWT format, and writes it to `~/.claude/.zai-credentials.json` for you:

**Windows:**
```powershell
# From the installation directory
& "$env:LOCALAPPDATA\ClaudeUsageStatusLine\ClaudeUsageStatusline.ZaiRefresh.exe"
```

**Linux / macOS:**
```bash
~/.local/bin/ClaudeUsageStatusline.ZaiRefresh
```

The tool will:
1. Open your default browser to `https://z.ai/manage-apikey/billing`.
2. Print the 7-step instructions in the terminal and wait for you to paste the JWT.
3. Validate that it starts with `eyJhbGciOiJIUzUxMiJ9` (HS512 header).
4. Save it to `~/.claude/.zai-credentials.json` in this format:
   ```json
   {
     "sessionToken": "eyJhbGciOiJIUzUxMiJ9...",
     "updatedAt": "2026-04-10T18:00:00Z"
   }
   ```

No `customerId` configuration is needed — the status line auto-extracts it from the JWT payload.

#### When to re-run ZaiRefresh

The session JWT has **no `exp` field** — its lifetime is controlled server-side and it will eventually be invalidated after periods of inactivity or an explicit logout. Signs that you need to refresh the token:

- The status line shows `Usage: z.ai session expired` for GLM models.
- The balance keeps its stale marker (`💰 ~9.88$`) for a long time even after using GLM.
- Logs contain `401 Unauthorized` from the z.ai billing endpoint.

Simply re-run `ClaudeUsageStatusline.ZaiRefresh` and paste a fresh JWT from the browser.

#### Optional: display balance in another currency

The z.ai `accountBalance` endpoint returns `totalBalance` without an explicit currency field — for most accounts this is USD. If you want the status line to display the balance in EUR, GBP, etc., edit `appsettings.json` next to the executable:

```json
{
  "Zai": {
    "NativeCurrency": "USD",
    "DisplayCurrency": "EUR",
    "ExchangeRateApi": "https://open.er-api.com/v6/latest/USD",
    "ExchangeRateCacheHours": 24
  }
}
```

When `NativeCurrency == DisplayCurrency`, no conversion or network call happens. Otherwise the rates are fetched once per `ExchangeRateCacheHours` and cached locally. If the rate API is unreachable and no cache exists, the balance is displayed unchanged in its native currency (graceful degradation).

**Security:** never commit `~/.claude/.zai-credentials.json` to git. It contains a live session token tied to your account. The status line never writes the JWT to `appsettings.json`.

## Status Line Format

Once configured, you'll see a status line in Claude Code. The format depends on the provider auto-detected from the model name:

**Claude mode** (default — any non-GLM model):
```
~/Projects/MyApp | Fable 5 (xhigh) | ⌛ 17% ↻ 3h49 | 📅 26% ↻ 42h | F 29% ↻ 42h | 🧠 49%
```

**z.ai mode** (when the model name contains `glm`, e.g. `glm-5.1`):
```
~/Projects/MyApp | GLM-5.1 | 💰 9.88$ | 🧠 49%
```

> z.ai only shows the account balance (not the usage windows) because the z.ai `accountBalance` endpoint only returns `totalBalance`. A `~` prefix in front of a value (e.g. `💰 ~9.88$`) means the displayed data is stale — the cache expired but the API returned 429 or is in backoff.

### 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`



### z.ai: "Usage: z.ai session expired" is displayed

**Cause:** The session JWT has been invalidated server-side (common after a few days of inactivity). A *missing* token shows `z.ai: token missing – follow instructions in the new window` instead, and a malformed one `Usage: invalid ZAI_SESSION_TOKEN – cannot extract customer ID` — same fix in all three cases.

**Solution:**
1. Run `ClaudeUsageStatusline.ZaiRefresh` and paste a fresh JWT from `https://z.ai/manage-apikey/billing` (Network tab → `accountBalance` → Authorization header, without `Bearer `).
2. Verify that `~/.claude/.zai-credentials.json` exists and contains a `sessionToken` starting with `eyJhbGciOiJIUzUxMiJ9`.
3. Check the logs for `401 Unauthorized` from the billing endpoint.

### z.ai: balance shows a stale `~` marker (`💰 ~9.88$`)

**Cause:** The cache is frozen because the API is in 429 backoff or the token expired server-side. The `~` prefix warns that the value may not reflect your real balance.

**Solution:**
1. Wait a few minutes — the backoff is typically 5 minutes.
2. If the prefix persists, re-run `ClaudeUsageStatusline.ZaiRefresh` to rotate the JWT.

### z.ai: wrong currency symbol or amount

**Cause:** `Zai:NativeCurrency` does not match what your account actually returns, or `Zai:DisplayCurrency` is unset.

**Solution:** Edit `appsettings.json` next to the executable and set `Zai:NativeCurrency` (usually `USD`) and `Zai:DisplayCurrency` to the currency you want on screen (e.g. `EUR`, `GBP`, `CAD`). See the "Optional: display balance in another currency" section above.

### "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


