claude-code-status-line 1.2.10

# Installation Guide

Complete installation instructions for all platforms and methods.

**🌐 Quick Start:** Visit the [official site](https://ndave92.github.io/claude-code-status-line/) for easy copy-paste installation commands.

## 🚀 Automated Installer (Recommended)

The easiest way to install is using the automated installer.

### Step 1: Install the Installer Command

**macOS / Linux:**
```bash
mkdir -p ~/.claude/commands && curl -o ~/.claude/commands/install-statusline.md https://raw.githubusercontent.com/ndave92/claude-code-status-line/master/.claude/commands/install-statusline.md
```

**Windows (PowerShell):**
```powershell
New-Item -Path "$env:USERPROFILE\.claude\commands" -ItemType Directory -Force; Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ndave92/claude-code-status-line/master/.claude/commands/install-statusline.md" -OutFile "$env:USERPROFILE\.claude\commands\install-statusline.md"
```

### Step 2: Run the Installer

1. Restart Claude Code
2. Run the command:
   ```
   /install-statusline
   ```
3. Follow the interactive prompts to choose your installation method
4. If the statusline does not appear, trust the workspace and trigger another Claude Code interaction

The installer will:
- Detect your platform and architecture
- Offer to download pre-built binaries or compile from source
- Configure your `~/.claude/settings.json` automatically
- Set up slash commands: `/update-statusline` and `/customize-statusline`
- Guide you through configuration with an interactive wizard

### Workspace trust

Recent Claude Code versions only execute custom `statusLine` commands in trusted workspaces. If installation succeeds but no statusline appears:

1. Trust the workspace in Claude Code
2. Send another prompt or reopen the session
3. Re-check your `statusLine` config if it still does not run

### Recommended Claude Code versions

- Use Claude Code `2.1.69+` for full worktree metadata in the statusline
- Use Claude Code `2.1.47+` or newer for `/add-dir` scope hints (`+N dirs`)
- Use Claude Code `2.1.153+` to receive `COLUMNS`/`LINES` for accurate terminal-width detection
- Claude project config and auto-memory may be shared across git worktrees of the same repository; the statusline keeps its own config in `~/.claude/statusline/`

---

## 📦 Manual Installation Methods

### Option 1: Install from crates.io

If you have Rust installed:

```bash
cargo install claude-code-status-line
```

**Then configure Claude Code:**

Add to `~/.claude/settings.json`:
```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.cargo/bin/claude-code-status-line",
    "padding": 0
  }
}
```

### Option 2: Download Pre-built Binary

**macOS (Apple Silicon):**
```bash
# Create directory
mkdir -p ~/.claude/statusline

# Download binary
curl -L -o ~/.claude/statusline/claude-code-status-line https://github.com/ndave92/claude-code-status-line/releases/latest/download/claude-code-status-line-macos-aarch64

# Make executable
chmod +x ~/.claude/statusline/claude-code-status-line
```

**macOS (Intel):**
```bash
mkdir -p ~/.claude/statusline
curl -L -o ~/.claude/statusline/claude-code-status-line https://github.com/ndave92/claude-code-status-line/releases/latest/download/claude-code-status-line-macos-x86_64
chmod +x ~/.claude/statusline/claude-code-status-line
```

**Linux (x86_64):**
```bash
mkdir -p ~/.claude/statusline
curl -L -o ~/.claude/statusline/claude-code-status-line https://github.com/ndave92/claude-code-status-line/releases/latest/download/claude-code-status-line-linux-x86_64
chmod +x ~/.claude/statusline/claude-code-status-line
```

**Windows (PowerShell):**
```powershell
New-Item -Path "$env:USERPROFILE\.claude\statusline" -ItemType Directory -Force
Invoke-WebRequest -Uri "https://github.com/ndave92/claude-code-status-line/releases/latest/download/claude-code-status-line-windows-x86_64.exe" -OutFile "$env:USERPROFILE\.claude\statusline\claude-code-status-line.exe"
```

**Then configure Claude Code:**

Add to your settings file with the **absolute path** to the binary:

```json
{
  "statusLine": {
    "type": "command",
    "command": "/Users/yourname/.claude/statusline/claude-code-status-line",
    "padding": 0
  }
}
```

### Option 3: Build from Source

```bash
# Clone the repository
git clone https://github.com/ndave92/claude-code-status-line.git ~/.claude/statusline
cd ~/.claude/statusline

# Build release binary
cargo build --release

# The binary will be at: target/release/claude-code-status-line
```

**Then configure Claude Code:**

Add to `~/.claude/settings.json`:
```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline/target/release/claude-code-status-line",
    "padding": 0
  }
}
```

---

## 🔐 Authentication Setup

For Claude.ai Pro/Max subscribers, quota data comes directly from the statusline payload (`rate_limits`) and needs no extra authentication. The section below applies to the fallback path: when `rate_limits` is absent (API-key users, older Claude Code), the statusline needs access to your Claude Code OAuth session or an explicit `CLAUDE_OAUTH_TOKEN` to fetch quota from the usage endpoint.

Start by confirming Claude Code itself is logged in:

```bash
claude auth status
```

### macOS (Recommended)
The statusline automatically reads Claude Code credentials from macOS Keychain when available.

### Other Platforms
The statusline checks Claude Code's `~/.claude/.credentials.json` first, then falls back to the system keyring when available.

### Environment Variable (All Platforms)
Alternatively, set the `CLAUDE_OAUTH_TOKEN` environment variable:

```bash
export CLAUDE_OAUTH_TOKEN="your-token-here"
```

---

## ✅ Verify Installation

Check that the binary is working:

```bash
# Check version
claude-code-status-line --version

# Test with sample input
echo '{"workspace":{"current_dir":"/test"},"model":{"display_name":"Sonnet"},"context_window":{"context_window_size":200000,"current_usage":{"input_tokens":1000}}}' | claude-code-status-line
```

Your updated statusline should appear on the next Claude Code interaction. If it does not, trust the workspace or restart Claude Code to refresh custom commands.

---

## 🔄 Next Steps

- **[Configuration Reference](Configuration-Reference)** - Complete settings reference
- **[Customization Examples](Customization-Examples)** - See theme examples
- **Run `/customize-statusline`** - Interactive configuration wizard
- **[Updating](Updating)** - How to update to newer versions