claude-code-statusline-alansauce

# claude-code-statusline-alansauce

A two-line statusline plugin for Claude Code that shows everything you need at a glance.

![statusline screenshot](image.png)

## What it shows

The statusline renders two lines below your Claude Code input. Here is a breakdown of every component:

### Line 1 - Identity, Context, and Config

```
alanguo:/Users/alanguo/Codin/Tools [Opus 4.6] ctx:29% 60k/200k | 1 CLAUDE.md | 3 Rules | 0 MCPs | 1 Hooks
```

| Component | Example | Description |
|-----------|---------|-------------|
| **User** | `alanguo` | Your system username, pulled from `$USER`. Displayed in bold cyan. |
| **Working directory** | `:/Users/alanguo/Codin/Tools` | The full path of the project Claude Code is operating in. |
| **Model** | `[Opus 4.6]` | The active Claude model for the current session (e.g., Opus 4.6, Sonnet 4.6, Haiku 4.5). Displayed in yellow brackets. |
| **Context usage %** | `ctx:29%` | How much of the context window has been consumed. Color-coded: green (<50%), yellow (50-79%), red (80%+). Uses the native `used_percentage` value from Claude Code for accuracy. |
| **Context tokens** | `60k/200k` | Current token count vs. total context window size. Tokens include input, output, cache creation, and cache read tokens combined. Values are rounded up to the nearest thousand. |
| **CLAUDE.md count** | `1 CLAUDE.md` | Number of CLAUDE.md files detected across all scopes: `~/.claude/CLAUDE.md` (global), `./CLAUDE.md`, `./CLAUDE.local.md`, `./.claude/CLAUDE.md`, `./.claude/CLAUDE.local.md` (project). |
| **Rules count** | `3 Rules` | Total number of `.md` files in `~/.claude/rules/` (global) and `./.claude/rules/` (project). These are the rule files Claude Code loads into context. |
| **MCPs count** | `0 MCPs` | Number of MCP servers configured. Counts keys in `mcpServers` from both `~/.claude/settings.json` (global) and `./.mcp.json` (project). |
| **Hooks count** | `1 Hooks` | Number of hook event types configured. Counts keys in `hooks` from `~/.claude/settings.json` (global), `./.claude/settings.json` (project), and `./.claude/settings.local.json` (local). |

### Line 2 - Usage Limits, Session, and Git

```
5hr: 34% (resets 3h 14m) | weekly: 31% (resets 4d 22h) | Session:0m0s | (main) [Edited:36]
```

| Component | Example | Description |
|-----------|---------|-------------|
| **5-hour usage** | `5hr: 34% (resets 3h 14m)` | Your current 5-hour rolling rate limit utilization as a percentage. Fetched live from the Anthropic OAuth API (`/api/oauth/usage`). The countdown shows time until this window resets. Displayed in blue. Shows "N/A" for API key users. |
| **Weekly usage** | `weekly: 31% (resets 4d 22h)` | Your 7-day rolling rate limit utilization. Same API source as above. The countdown shows days and hours until reset. Displayed in magenta. Shows "N/A" for API key users. |
| **Session duration** | `Session:0m0s` | How long the current Claude Code session has been running. Uses `total_duration_ms` from Claude Code's stdin data when available. Falls back to calculating elapsed time from the transcript file's creation timestamp. Format: `Xh Ym` for sessions over an hour, `XmYs` for shorter sessions. Displayed in green. |
| **Git branch** | `(main)` | The current git branch name. Shows "detached" if in detached HEAD state, or "(not a git repo)" if the working directory is not a git repository. Displayed in yellow. |
| **Git file status** | `[Committed:2,Staged:5,Edited:36]` | A bracketed summary of file changes in the working tree. Up to three categories are shown, separated by commas. Only categories with a non-zero count appear. If all counts are zero, the brackets are hidden entirely. All git commands use `--no-optional-locks` to avoid interfering with other git processes. |

**Git status categories explained:**

| Label | Git command | What it means |
|-------|------------|---------------|
| `Committed:N` | `git diff --cached --name-only` | Files staged in the index, ready to be included in the next commit. These have been `git add`-ed. |
| `Staged:N` | `git diff --name-only` | Tracked files that have been modified in the working tree but not yet staged with `git add`. |
| `Edited:N` | `git ls-files --others --exclude-standard` | New files in the working directory that are not tracked by git and not ignored by `.gitignore`. |

### Color Coding

The statusline uses ANSI colors to make scanning fast:

| Color | Used for |
|-------|----------|
| Bold cyan | Username |
| Cyan | Working directory |
| Yellow | Model name, git branch |
| Green | Context usage under 50%, session duration |
| Yellow | Context usage 50-79% |
| Bold red | Context usage 80%+ (warning) |
| Blue | 5-hour usage |
| Magenta | Weekly usage |
| Dim | Separators and config count labels |

## Installation

### Via Claude Code Plugin Marketplace

```
/plugin marketplace add weihaog1/claude-code-statusline-alansauce
/plugin install claude-code-statusline-alansauce
/claude-code-statusline-alansauce:setup
```

### Manual Installation

1. Clone this repo:
   ```bash
   git clone https://github.com/weihaog1/claude-code-statusline-alansauce.git ~/.claude/plugins/claude-code-statusline-alansauce
   ```

2. Add to `~/.claude/settings.json`:
   ```json
   {
     "statusLine": {
       "type": "command",
       "command": "bash ~/.claude/plugins/claude-code-statusline-alansauce/statusline.sh",
       "padding": 0
     }
   }
   ```

3. Restart Claude Code.

## Dependencies

- `bash` (4.0+)
- `jq` - JSON processor
- `curl` - for API usage fetching
- `git` - for branch/status display

### Installing jq

| Platform | Command |
|----------|---------|
| macOS | `brew install jq` |
| Debian/Ubuntu | `sudo apt install jq` |
| Fedora | `sudo dnf install jq` |
| Arch | `sudo pacman -S jq` |
| Windows (Chocolatey) | `choco install jq` |
| Windows (Scoop) | `scoop install jq` |

## Platform Support

| Platform | Credentials Source | Status |
|----------|-------------------|--------|
| macOS | Keychain (`security` command) | Supported |
| Linux | `~/.claude/.credentials.json` | Supported |
| WSL | `~/.claude/.credentials.json` | Supported |
| Git Bash (Windows) | `~/.claude/.credentials.json` | Supported |

## API Usage Display

The statusline fetches rate limit data from the Anthropic API for Pro/Max/Team subscribers. This requires OAuth credentials (automatic if you're logged in via `claude` CLI). API key users will see "N/A" for usage fields.

## License

MIT