# Claude Code Status Line
A configurable status line binary for Claude Code that shows workspace info: current working directory, git branch, model name, context usage (integer percentage showing how close to auto-compact, optionally with decimal precision), quota limits (5h/7d as whole numbers) with reset timers, and optional API cost—all with per-section color customization, powerline arrows, and width-aware trimming.
<img width="904" height="99" alt="Képernyőfotó 2025-12-30 - 15 01 35" src="https://github.com/user-attachments/assets/bbf1173a-e77b-4ea2-a1fe-3bd3868779d1" />
## Features
- **Powerline-style arrows** with per-section color customization (bg, fg, muted) for each section.
- Fallback to classic pipe separator for terminals without powerline font support.
- Sections: current directory, git branch + dirty indicator, model name, context usage, quota (5h/7d), optional session cost.
- Width-aware rendering: drops lower-priority sections when the terminal is narrow; quota timers drop before quota percentages.
- Terminal width detection with fallbacks (supports `CLAUDE_TERMINAL_WIDTH` and `COLUMNS`).
- Cross-platform: macOS keychain via `security`; other platforms via the `keyring` crate; also supports `CLAUDE_OAUTH_TOKEN`.
## Example output
**Powerline style** (default, requires powerline-compatible font):
```
~/projects/statusline (main)* Sonnet 4.5 ctx: 71% 5h: 12% (2h 30m) 7d: 5% (4d 12h)
```
Each section can have its own background color with smooth arrow transitions.
**Classic pipe separator** (fallback, set `USE_POWERLINE = false`):
```
Narrow terminal (low-priority sections dropped):
```
~/projects/statusline (main)* Sonnet 4.5
```
Notes:
- `*` appears when the git working tree is dirty (i.e. the branch has uncommitted changes).
- **Context usage** (`ctx: 96%`) shows **percentage until auto-compact**, not raw context token usage. The calculation includes the 22.5% autocompact buffer that Claude Code reserves (45k tokens for a 200k window). This means:
- `ctx: 0%` = conversation just started, plenty of space
- `ctx: 96%` = approaching auto-compact, ~4% free space remaining
- `ctx: 100%` = auto-compact will trigger (free space ≈ 0%)
- The percentage represents how "full" your context window is including the reserved buffer, making it easier to understand when compaction will occur rather than showing raw token counts. By default, context is displayed as a floored integer (e.g., 99.9% → 99%) to match Claude Code's notification style. Set `CONTEXT_USE_FLOAT = true` to show decimal precision (e.g., 99.9%).
- **Quota percentages** (`5h: 12%`, `7d: 5%`) are provided by the official Anthropic API and displayed as whole numbers without decimals. This is by design—the API returns integer precision only. **Limitation**: When quota reaches 100%, the displayed percentage may be inaccurate due to API behavior. This is an Anthropic limitation, not a bug in the statusline.
- Exact truncation depends on your terminal width and `RIGHT_MARGIN`.
## Quick start
### Prerequisites
- Rust toolchain: https://rustup.rs/
- **After installing Rust**: Either restart your shell OR run `source $HOME/.cargo/env` (Linux/macOS) or `source $env:USERPROFILE\.cargo\env` (Windows PowerShell) to make `cargo` available
- Claude Code installed
- **Powerline-compatible font** (recommended): Nerd Fonts, Powerline fonts, or similar for proper arrow rendering. If you don't have one, set `USE_POWERLINE = false` for classic pipe separators.
- Runtime dependencies:
- `git` (for git section)
- `curl` (for quota fetching; ensure it's in PATH)
### Installation (macOS / Linux)
**HTTPS:**
```bash
git clone https://github.com/ndave92/claude-code-status-line.git ~/.claude/statusline
cd ~/.claude/statusline
cargo build --release
```
**SSH:**
```bash
git clone git@github.com:ndave92/claude-code-status-line.git ~/.claude/statusline
cd ~/.claude/statusline
cargo build --release
```
### Installation (Windows PowerShell)
**HTTPS:**
```powershell
git clone https://github.com/ndave92/claude-code-status-line.git $env:USERPROFILE\.claude\statusline
cd $env:USERPROFILE\.claude\statusline
cargo build --release
```
**SSH:**
```powershell
git clone git@github.com:ndave92/claude-code-status-line.git $env:USERPROFILE\.claude\statusline
cd $env:USERPROFILE\.claude\statusline
cargo build --release
```
## Updating
To update to the latest version:
### If you haven't customized the code:
```bash
# Navigate to your statusline directory
cd ~/.claude/statusline
# Pull the latest changes
git pull
# Rebuild
cargo build --release
```
### If you have customizations:
```bash
# Navigate to your statusline directory
cd ~/.claude/statusline
# Stash your changes
git stash
# Pull the latest changes
git pull
# Reapply your customizations
git stash pop
# Resolve any conflicts if they occur
# Edit src/main.rs to merge your customizations with new changes
# Rebuild
cargo build --release
```
After rebuilding, restart Claude Code to see the updated statusline.
## Configure Claude Code
Claude Code runs your command, passes session context as JSON on stdin, and uses the first line of stdout as the status line.
**Settings file locations:**
- User settings: `~/.claude/settings.json`
- Project settings: `.claude/settings.json`
(Exact locations can vary depending on how Claude Code is installed/configured.)
**If the settings file doesn't exist**, create it first:
```bash
# macOS/Linux
mkdir -p ~/.claude
touch ~/.claude/settings.json
# Windows PowerShell
New-Item -Path "$env:USERPROFILE\.claude" -ItemType Directory -Force
New-Item -Path "$env:USERPROFILE\.claude\settings.json" -ItemType File
```
**Add the statusLine configuration:**
```json
{
"statusLine": {
"type": "command",
"command": "/absolute/path/to/claude-code-status-line",
"padding": 0
}
}
```
Examples:
- macOS/Linux:
- `~/.claude/statusline/target/release/claude-code-status-line`
- Windows:
- Use a full absolute path to `claude-code-status-line.exe`
Restart Claude Code to see the status line.
## Configuration
Edit constants at the top of `src/main.rs`, then rebuild with:
```bash
cargo build --release
```
### Toggle sections
```rust
const SHOW_CWD: bool = true; // enables current working directory section
const CWD_FULL_PATH: bool = true; // whether to show the full path or just the last directory
const SHOW_GIT: bool = true; // enables git section
const SHOW_MODEL: bool = true; // enables model name section
const SHOW_CONTEXT: bool = true; // enables context usage section
const CONTEXT_USE_FLOAT: bool = false; // set to true to show floating point (e.g., 99.9%), false for integer floored (e.g., 99.9% → 99%)
const SHOW_QUOTA: bool = true; // enables quota usage section with reset timers
const SHOW_COST: bool = false; // optional; enables API cost section (mainly for API key users)
const DEFAULT_TERMINAL_WIDTH: usize = 120; // fallback terminal width if detection fails
const RIGHT_MARGIN: usize = 20; // reserve space for Claude Code's right-side messages to prevent soft wrapping (0 = no margin)
```
**Percentage formatting:**
- **Context** (`ctx: 96%`): Shows floored integer by default (e.g., 99.9% → 99%) to match Claude Code's notification style. Represents percentage until auto-compact (includes the 22.5% buffer). At `ctx: 100%`, auto-compact triggers. Set `CONTEXT_USE_FLOAT = true` to show decimal precision (e.g., `ctx: 99.9%`).
- **Quota** (`5h: 12%`, `7d: 5%`): Shows whole numbers without decimals since the Anthropic API returns integer precision. Note that quota percentages may be inaccurate when reaching 100% due to API limitations.
**Quota caching:**
```rust
const QUOTA_CACHE_TTL: u64 = 0; // Cache TTL in seconds (0 = disabled, set to e.g. 300 for 5 minutes)
```
Priority: earlier sections (added first in `main`) are higher priority and will remain visible longer when width is limited.
### Powerline arrows
```rust
const POWERLINE_ARROW: char = '\u{E0B0}'; // - requires powerline-compatible font
const USE_POWERLINE: bool = true; // set to false for classic pipe separator style
```
**Font requirement:** Powerline arrows require a powerline-compatible font (e.g., Nerd Fonts, Powerline fonts). If you see a missing character symbol instead of smooth arrows, either install a compatible font or set `USE_POWERLINE = false`.
### Classic pipe separator mode
When `USE_POWERLINE = false`, the statusline uses the classic global color system with pipe separators:
```rust
const SEPARATOR_CHAR: char = '|'; // you can try '/' or '·' for alternative separators
const USE_DARK_THEME: bool = true; // theme selection for classic mode colors
// Dark theme colors (classic mode)
const DARK_BG: (u8, u8, u8) = (217, 119, 87); // Claude Burnt Orange #D97757
const DARK_FG: (u8, u8, u8) = (38, 38, 36); // Claude Dark Gray #262624
const DARK_SEP: (u8, u8, u8) = (38, 38, 36); // Claude Dark Gray #262624
const DARK_MUTED: (u8, u8, u8) = (65, 65, 62); // Claude Medium Gray #41413E
// Light theme colors (classic mode)
const LIGHT_BG: (u8, u8, u8) = (217, 119, 87); // Claude Burnt Orange #D97757
const LIGHT_FG: (u8, u8, u8) = (250, 249, 245); // Claude Cream #FAF9F5
const LIGHT_SEP: (u8, u8, u8) = (250, 249, 245); // Claude Cream #FAF9F5
const LIGHT_MUTED: (u8, u8, u8) = (130, 129, 122); // Claude Light Gray #82817A
const SHOW_BACKGROUND: bool = true; // Set to false for transparent background
```
### Per-section colors (powerline mode)
When `USE_POWERLINE = true`, each section has its own `SectionColors` defining background, foreground, and muted colors (RGB tuples 0–255):
```rust
struct SectionColors {
bg: (u8, u8, u8), // background color
fg: (u8, u8, u8), // foreground (text) color
muted: (u8, u8, u8), // muted text color (for timers and dirty indicator)
}
```
**Per-section color constants** (customize in `src/main.rs`):
```rust
const CWD_COLORS: SectionColors = SectionColors {
bg: (217, 119, 87), // Claude Burnt Orange #D97757
fg: (38, 38, 36), // Claude Dark Gray #262624
muted: (65, 65, 62), // Claude Medium Gray #41413E
};
const GIT_COLORS: SectionColors = SectionColors {
bg: (38, 38, 36), // Claude Dark Gray #262624
fg: (217, 119, 87), // Claude Burnt Orange #D97757
muted: (130, 129, 122), // Claude Light Gray #82817A
};
const MODEL_COLORS: SectionColors = SectionColors {
bg: (217, 119, 87), // Claude Burnt Orange #D97757
fg: (38, 38, 36), // Claude Dark Gray #262624
muted: (65, 65, 62), // Claude Medium Gray #41413E
};
const CONTEXT_COLORS: SectionColors = SectionColors {
bg: (38, 38, 36), // Claude Dark Gray #262624
fg: (217, 119, 87), // Claude Burnt Orange #D97757
muted: (130, 129, 122), // Claude Light Gray #82817A
};
const QUOTA_5H_COLORS: SectionColors = SectionColors {
bg: (217, 119, 87), // Claude Burnt Orange #D97757
fg: (38, 38, 36), // Claude Dark Gray #262624
muted: (65, 65, 62), // Claude Medium Gray #41413E
};
const QUOTA_7D_COLORS: SectionColors = SectionColors {
bg: (38, 38, 36), // Claude Dark Gray #262624
fg: (217, 119, 87), // Claude Burnt Orange #D97757
muted: (130, 129, 122), // Claude Light Gray #82817A
};
const COST_COLORS: SectionColors = SectionColors {
bg: (217, 119, 87), // Claude Burnt Orange #D97757
fg: (38, 38, 36), // Claude Dark Gray #262624
muted: (65, 65, 62), // Claude Medium Gray #41413E
};
```
**Customization examples:**
- Create a multi-colored statusline by setting different `bg` values for each section
- Make quota timers stand out by setting `QUOTA_COLORS.muted` to a lighter/darker shade
- Create a dark/light gradient by varying background brightness across sections
**Official Claude colors for reference:**
```rust
(217, 119, 87); // Claude Burnt Orange #D97757
(250, 249, 245); // Claude Cream #FAF9F5
(38, 38, 36); // Claude Dark Gray #262624
(65, 65, 62); // Claude Medium Gray #41413E
(130, 129, 122); // Claude Light Gray #82817A
```
## Environment variables
- `CLAUDE_OAUTH_TOKEN`: OAuth token override (bypasses credentials file, keychain, and keyring lookup).
- `CLAUDE_TERMINAL_WIDTH`: force a specific terminal width (integer).
- `COLUMNS`: used as a terminal width fallback (integer).
- `STATUSLINE_DEBUG`: if set, prints debug logs to stderr (quota fetch failures, width info).
## Quota caching
Quota data can be cached in your system temp directory as `claude-code-status-line-quota-{uid}.json` (where `{uid}` is the user ID) to reduce latency and API calls. By default, caching is **disabled** (`QUOTA_CACHE_TTL = 0`). To enable caching, set `QUOTA_CACHE_TTL` to the desired TTL in seconds (e.g., `300` for 5 minutes). The user ID in the filename reduces collisions; combined with atomic temp-file patterns this improves safety.
## Platform notes
### macOS
- Reads Claude Code credentials via `security` (Keychain) unless `CLAUDE_OAUTH_TOKEN` is set.
### Linux
- First tries to read credentials from `~/.claude/.credentials.json` (more reliable, works out of the box).
- Falls back to the `keyring` crate if the credentials file doesn't exist.
- The credentials file approach is recommended for systems where keyring services may not be available or properly configured.
### Windows
- First tries to read credentials from `%USERPROFILE%\.claude\.credentials.json`.
- Falls back to the `keyring` crate backend if the credentials file doesn't exist.
- The credentials file approach may be more reliable if Windows Credential Manager integration has issues.
## FAQ
### Understanding the Display
**Q: What does the context percentage (`ctx: X%`) mean?**
The context percentage shows **percentage until auto-compact**, not your raw context usage. This makes it easy to understand when Claude Code will trigger auto-compaction.
The calculation includes the 22.5% autocompact buffer that Claude Code reserves (45k tokens for a 200k context window). This buffer is counted as "used" space.
Examples:
- `ctx: 0%` = Conversation just started, plenty of space available
- `ctx: 96%` = Approaching auto-compact, approximately 4% free space remaining
- `ctx: 100%` = Auto-compact will trigger (free space ≈ 0%)
This approach is more intuitive than showing raw token counts because it directly answers "how close am I to auto-compact?"
**Q: Why doesn't my context percentage match Claude Code's notifications exactly?**
The statusline uses **floored integer display by default** (e.g., 99.9% → 99%), showing whole numbers without decimals. This provides a cleaner display and typically aligns well with Claude Code's notification percentages. However, minor differences (~1%) between the statusline and Claude Code's notifications can occur due to different rounding or display methods.
If you prefer decimal precision like `ctx: 99.9%`, you can enable it:
```rust
const CONTEXT_USE_FLOAT: bool = true; // Set in src/main.rs
```
Then rebuild with `cargo build --release`.
**Q: Why are quota percentages whole numbers (like `5h: 8%` instead of `5h: 8.3%`)?**
The Anthropic API returns quota utilization as integers only—this is by design, not a limitation of the statusline. The API simply doesn't provide sub-percentage precision.
Note: When quota reaches 100%, the displayed percentage may be inaccurate due to API behavior. This is an Anthropic limitation.
**Q: What does the `*` next to my git branch mean?**
The asterisk indicates your git working tree is "dirty", meaning you have uncommitted changes (modified, added, or deleted files).
Examples:
- `(main)` = Clean working tree, no uncommitted changes
- `(main)*` = You have uncommitted changes
**Q: Why do some sections disappear on narrow terminals?**
The statusline uses **width-aware rendering** to prevent line wrapping. When your terminal is too narrow to fit all sections, lower-priority sections are dropped.
**Priority order** (highest to lowest):
1. Current directory (`SHOW_CWD`)
2. Git branch (`SHOW_GIT`)
3. Model name (`SHOW_MODEL`)
4. Context usage (`SHOW_CONTEXT`)
5. Quota percentages (`SHOW_QUOTA`)
6. Quota reset timers (dropped first)
7. Cost (`SHOW_COST`)
The priority is determined by the order sections are added in the `main()` function.
You can adjust the `RIGHT_MARGIN` constant to control how much space is reserved for Claude Code's right-side messages:
```rust
const RIGHT_MARGIN: usize = 20; // Default: 20 characters
```
---
### Customization
**Q: How do I change the colors?**
**For Powerline mode** (`USE_POWERLINE = true`):
Edit the `*_COLORS` constants in `src/main.rs`. Each section has its own `SectionColors` with three RGB values:
```rust
const GIT_COLORS: SectionColors = SectionColors {
bg: (38, 38, 36), // Background - Claude Dark Gray
fg: (217, 119, 87), // Foreground/text - Claude Burnt Orange
muted: (130, 129, 122), // Muted text (for timers) - Claude Light Gray
};
```
RGB format: `(red, green, blue)` with values 0-255.
**Official Claude color palette:**
```rust
(217, 119, 87); // Claude Burnt Orange #D97757
(250, 249, 245); // Claude Cream #FAF9F5
(38, 38, 36); // Claude Dark Gray #262624
(65, 65, 62); // Claude Medium Gray #41413E
(130, 129, 122); // Claude Light Gray #82817A
```
**For Classic mode** (`USE_POWERLINE = false`):
Edit the theme constants:
```rust
const USE_DARK_THEME: bool = true; // Switch between dark/light themes
// Dark theme colors
const DARK_BG: (u8, u8, u8) = (217, 119, 87); // Background
const DARK_FG: (u8, u8, u8) = (38, 38, 36); // Foreground text
const DARK_SEP: (u8, u8, u8) = (38, 38, 36); // Separator color
const DARK_MUTED: (u8, u8, u8) = (65, 65, 62); // Muted text
```
After changing colors, rebuild: `cargo build --release`
**Q: How do I hide/show specific sections?**
Toggle the `SHOW_*` constants in `src/main.rs`:
```rust
const SHOW_CWD: bool = true; // Current working directory
const SHOW_GIT: bool = true; // Git branch + dirty indicator
const SHOW_MODEL: bool = true; // Model name (e.g., "Sonnet 4.5")
const SHOW_CONTEXT: bool = true; // Context percentage
const SHOW_QUOTA: bool = true; // Quota (5h/7d) with reset timers
const SHOW_COST: bool = false; // API cost (useful for API key users)
```
Example - hide model name and cost:
```rust
const SHOW_MODEL: bool = false;
const SHOW_COST: bool = false;
```
Rebuild after changes: `cargo build --release`
**Q: How do I change section order/priority?**
Section priority is determined by the order sections are added in the `main()` function. Earlier sections have higher priority and stay visible longer on narrow terminals.
To change the order, you'll need to modify the code in `src/main.rs` around line 850-950 where sections are added with `sections.push()`.
The current order (highest to lowest priority):
1. CWD → 2. Git → 3. Model → 4. Context → 5. Quota → 6. Cost
**Q: How do I make the statusline shorter for narrow terminals?**
Multiple approaches:
1. **Reduce right margin** (most common):
```rust
const RIGHT_MARGIN: usize = 10; ```
2. **Disable non-essential sections**:
```rust
const SHOW_COST: bool = false; const SHOW_MODEL: bool = false; ```
3. **Show only directory name instead of full path**:
```rust
const CWD_FULL_PATH: bool = false; ```
Rebuild after changes: `cargo build --release`
**Q: Can I use custom separators instead of powerline arrows?**
Yes! Disable powerline mode and choose your separator:
```rust
const USE_POWERLINE: bool = false; // Switch to classic mode
const SEPARATOR_CHAR: char = '/'; // Try '/', '·', '|', '•', etc.
```
Examples:
- `const SEPARATOR_CHAR: char = '|';` → `~/projects | main | Sonnet 4.5`
- `const SEPARATOR_CHAR: char = '/';` → `~/projects / main / Sonnet 4.5`
- `const SEPARATOR_CHAR: char = '·';` → `~/projects · main · Sonnet 4.5`
Rebuild after changes: `cargo build --release`
**Q: How do I prevent text overlap with Claude's right-side messages?**
Adjust the `RIGHT_MARGIN` constant to reserve more space:
```rust
const RIGHT_MARGIN: usize = 30; // Increase from default 20
```
This leaves 30 characters of space for Claude Code's notification messages like "X% left until auto-compact".
If your statusline is still overlapping:
- Increase `RIGHT_MARGIN` further
- Disable some sections to make the statusline shorter
- Use `CWD_FULL_PATH = false` to shorten the directory display
---
### Troubleshooting
**Q: Status line not appearing at all**
**Check your settings:**
1. Verify `~/.claude/settings.json` (or `%USERPROFILE%\.claude\settings.json` on Windows) contains:
```json
{
"statusLine": {
"type": "command",
"command": "/absolute/path/to/claude-code-status-line",
"padding": 0
}
}
```
2. **Path must be absolute**, not relative:
- ✅ macOS/Linux: `~/.claude/statusline/target/release/claude-code-status-line`
- ✅ Windows: `C:\Users\YourName\.claude\statusline\target\release\claude-code-status-line.exe`
- ❌ Bad: `./claude-code-status-line`
3. **Verify binary exists:**
```bash
ls -la ~/.claude/statusline/target/release/claude-code-status-line
Get-Item $env:USERPROFILE\.claude\statusline\target\release\claude-code-status-line.exe
```
4. **Make it executable** (macOS/Linux only - Windows doesn't need this):
```bash
chmod +x ~/.claude/statusline/target/release/claude-code-status-line
```
5. **Restart Claude Code** after any changes to settings.
**Q: Quota shows `5h: -` / `7d: -`**
This happens when the statusline can't fetch quota data from the Anthropic API. Common causes:
**1. Credential access issues (most common):**
- **Linux**: Verify `~/.claude/.credentials.json` exists:
```bash
ls -la ~/.claude/.credentials.json
cat ~/.claude/.credentials.json ```
- **Windows**: Verify `%USERPROFILE%\.claude\.credentials.json` exists:
```powershell
# PowerShell
Get-Item $env:USERPROFILE\.claude\.credentials.json
Get-Content $env:USERPROFILE\.claude\.credentials.json
# Or cmd.exe
dir %USERPROFILE%\.claude\.credentials.json
type %USERPROFILE%\.claude\.credentials.json
```
Example path: `C:\Users\YourName\.claude\.credentials.json`
**2. Network issues:**
- Check your internet connection
- Firewall might be blocking `curl`
**3. Missing curl:**
```bash
# macOS/Linux
which curl
# Windows PowerShell/cmd
where curl
```
**4. Workaround - set token manually:**
```bash
# macOS/Linux
export CLAUDE_OAUTH_TOKEN="your-token-here"
# Windows PowerShell
$env:CLAUDE_OAUTH_TOKEN="your-token-here"
# Windows cmd.exe
set CLAUDE_OAUTH_TOKEN=your-token-here
```
**Q: Powerline arrows display as boxes, question marks, or missing characters**
You need a **powerline-compatible font** installed and configured in your terminal.
**Solutions:**
1. **Install a compatible font** (recommended):
- [Nerd Fonts](https://www.nerdfonts.com/) (recommended)
- [Powerline Fonts](https://github.com/powerline/fonts)
- Popular choices: "JetBrains Mono Nerd Font", "FiraCode Nerd Font", "Hack Nerd Font"
2. **Configure your terminal** to use the font:
- iTerm2: Preferences → Profiles → Text → Font
- VS Code terminal: Settings → Terminal → Font Family
- Windows Terminal: Settings → Profiles → Appearance → Font face
3. **Fallback - use classic mode** (no font required):
```rust
const USE_POWERLINE: bool = false; ```
**Q: Colors look wrong or don't appear**
**Cause:** Your terminal may not support 24-bit truecolor ANSI codes.
**Check terminal support:**
- Modern terminals (iTerm2, Windows Terminal, VS Code terminal): Full support ✅
- Older terminals (cmd.exe, basic xterm): Limited support ❌
**Solutions:**
1. **Use a modern terminal** with truecolor support
2. **Try transparent background mode**:
```rust
const SHOW_BACKGROUND: bool = false; ```
3. **Adjust colors** to use simpler RGB values:
```rust
const GIT_COLORS: SectionColors = SectionColors {
bg: (100, 100, 100), fg: (255, 255, 255), muted: (150, 150, 150),
};
```
4. **Test your terminal's color support** (Unix/macOS only):
```bash
curl -s https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh | bash
```
**Q: Context percentage seems stuck or not updating**
**Possible causes:**
1. **Cached binary** - Claude Code might be using an old version:
```bash
cargo build --release ```
2. **Check if Claude Code is sending updates** (Unix/macOS):
```bash
STATUSLINE_DEBUG=1 ~/.claude/statusline/target/release/claude-code-status-line < /dev/null
```
**Windows PowerShell:**
```powershell
$env:STATUSLINE_DEBUG=1
& "$env:USERPROFILE\.claude\statusline\target\release\claude-code-status-line.exe"
```
Look for error messages in stderr.
3. **Verify the calculation** matches `/context` output:
- Run `/context` in Claude Code
- Compare with statusline percentage
- Should match within rounding (statusline has 1 decimal precision)
**Q: Build fails with Rust compilation errors**
**Common issues:**
1. **Rust not installed:**
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
2. **Cargo not in PATH after install:**
```bash
source $HOME/.cargo/env
```
3. **Outdated Rust version:**
```bash
rustup update stable
cargo build --release
```
4. **Corrupted build cache:**
```bash
cargo clean
cargo build --release
```
**Q: "command not found" when Claude Code tries to run the statusline**
**Cause:** The binary path in `settings.json` is incorrect or not absolute.
**Fix:**
1. **Find the correct absolute path:**
```bash
realpath ~/.claude/statusline/target/release/claude-code-status-line
Resolve-Path $env:USERPROFILE\.claude\statusline\target\release\claude-code-status-line.exe
```
2. **Update settings.json with the full path:**
```json
{
"statusLine": {
"type": "command",
"command": "/Users/yourname/.claude/statusline/target/release/claude-code-status-line",
"padding": 0
}
}
```
3. **Verify the file exists:**
```bash
ls -la ~/.claude/statusline/target/release/claude-code-status-line
Get-Item $env:USERPROFILE\.claude\statusline\target\release\claude-code-status-line.exe
```
4. **Check permissions** (macOS/Linux only):
```bash
chmod +x ~/.claude/statusline/target/release/claude-code-status-line
```
---
### General
**Q: Does this slow down Claude Code?**
**No, the performance impact is minimal:**
- The binary runs once per prompt/message, not continuously
- Typical execution time: <50ms for everything except quota fetching
- Quota fetching adds ~100-200ms (only when `SHOW_QUOTA = true`)
- **No persistent processes** - the binary exits immediately after printing the statusline
**To reduce latency further:**
- Enable quota caching (avoids API calls):
```rust
const QUOTA_CACHE_TTL: u64 = 300; ```
- Disable quota display:
```rust
const SHOW_QUOTA: bool = false;
```
**Q: Is this safe to use? (credential/security concerns)**
**Yes, the statusline is safe:**
1. **Read-only credential access** - Only reads credentials, never writes or modifies them
2. **Uses same sources as Claude Code** - macOS Keychain, system keyring, or credentials file
3. **No data sent elsewhere** - Only communicates with Anthropic's official API for quota (when enabled)
4. **Open source** - You can audit the code yourself: [GitHub repo](https://github.com/ndave92/claude-code-status-line)
5. **MIT licensed** - Free to use, modify, and audit
**What data is sent:**
- When `SHOW_QUOTA = true`: OAuth token sent to `api.anthropic.com/v1/quota` (official API)
- Otherwise: No network requests
**Q: Does this work with API keys (not Claude Pro subscription)?**
**Yes, but with limitations:**
- API keys don't have quota limits, so quota sections will show `5h: -` and `7d: -`
- All other sections work normally (CWD, git, model, context)
- **The cost section is useful for API users:**
```rust
const SHOW_COST: bool = true; ```
This will show your session cost in USD, e.g., `$0.05`.
**Q: How do I update to the latest version?**
**If you installed via git clone** (see [Updating](#updating) section for details):
```bash
# macOS/Linux
cd ~/.claude/statusline
git pull
cargo build --release
# Restart Claude Code
# Windows PowerShell
cd $env:USERPROFILE\.claude\statusline
git pull
cargo build --release
# Restart Claude Code
```
**If you downloaded as ZIP:**
1. **Download the latest release** from [GitHub Releases](https://github.com/ndave92/claude-code-status-line/releases) or download the repository as ZIP again
2. **If you have customizations**, back them up first:
```bash
cp ~/.claude/statusline/src/main.rs ~/statusline-custom-backup.rs
Copy-Item $env:USERPROFILE\.claude\statusline\src\main.rs $env:USERPROFILE\statusline-custom-backup.rs
copy %USERPROFILE%\.claude\statusline\src\main.rs %USERPROFILE%\statusline-custom-backup.rs
```
3. **Extract the new ZIP** to replace the old directory
4. **Reapply your customizations** by copying constants from the backup to the new `src/main.rs`
5. **Rebuild:**
```bash
cd ~/.claude/statusline cargo build --release
```
6. **Restart Claude Code**
**With git stash (if using git):**
```bash
# macOS/Linux
cd ~/.claude/statusline
git stash # Save your customizations
git pull # Get latest version
git stash pop # Reapply your customizations
cargo build --release
# Windows PowerShell
cd $env:USERPROFILE\.claude\statusline
git stash
git pull
git stash pop
cargo build --release
```
**Q: Can I contribute to this project?**
**Yes! Contributions are welcome:**
- **Report issues:** [GitHub Issues](https://github.com/ndave92/claude-code-status-line/issues)
- **Submit pull requests:** Fork the repo and submit PRs
- **Suggest features:** Open an issue with your idea
- **Share customizations:** Show off your color schemes and configurations
**Project is MIT licensed** - you're free to modify, distribute, and use it however you like.
## Development
Build (fast):
```bash
cargo build
```
Build (optimized):
```bash
cargo build --release
```
Run tests:
```bash
cargo test
```
## Testing the binary manually
You can simulate Claude Code input by piping JSON to stdin:
```bash
printf '%s' '{"workspace":{"current_dir":"'"$(pwd)"'"},"model":{"display_name":"Sonnet 4.5"},"context_window":{"context_window_size":200000,"current_usage":{"input_tokens":15420}},"cost":{"total_cost_usd":0.0}}' \
| ./target/release/claude-code-status-line
```
To debug width handling:
```bash
STATUSLINE_DEBUG=1 CLAUDE_TERMINAL_WIDTH=60 ./target/release/claude-code-status-line < /dev/null
```
## License
MIT