# Claude Code Status line

> Claude Code: Configure statusLine, consume session JSON, display cost/context, understand refreshes, Windows support, and caching.

URL: https://docs.passion8.cc/en/docs/claude-code/statusline
Language: en
Publisher: Passion8

The status line is a custom display at the bottom of Claude Code. It runs a local command, sends session JSON on stdin, and displays stdout.




The script runs locally without model tokens. It can display context usage, model, estimated cost, Git branch, PR state, limits, and output style.




## Quick setup

Ask Claude Code to generate it:

```text
/statusline show model name and context percentage with a progress bar
```

Or configure statusLine manually:

```json title="~/.claude/settings.json"
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}
```

An inline command also works:

```json title="~/.claude/settings.json"
{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}
```

## Working script

```bash title="~/.claude/statusline.sh"
#!/bin/bash
input=$(cat)

model=$(echo "$input" | jq -r '.model.display_name // .model.id // "model"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // .cwd')
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
branch=$(git -C "$dir" branch --show-current 2>/dev/null || true)

printf "[%s] %s" "$model" "${dir##*/}"
[ -n "$branch" ] && printf " · %s" "$branch"
printf " · %s%% context · $%s\n" "$pct" "$cost"
```

Make it executable:

```bash
chmod +x ~/.claude/statusline.sh
```

## Refresh behavior

| Trigger | Behavior |
| --- | --- |
| New assistant response | Run the script again |
| Compaction completes | Update context/cost fields |
| Permission mode changes | Refresh permission-related display |
| Vim mode changes | Update vim.mode |
| refreshInterval | Additional timed refresh in seconds |

Updates are debounced by about 300 ms. A new update cancels an unfinished script. Output can include multiple lines, ANSI colors, and supported OSC 8 links.




Keep the script fast. Network calls, heavy commands, or scanning large repositories on every refresh can make the TUI sluggish.




## Common fields

| Field | Purpose |
| --- | --- |
| model.id, model.display_name | Active model |
| workspace.current_dir, cwd | Current directory |
| workspace.project_dir | Launch directory |
| workspace.added_dirs | Added directory access |
| cost.total_cost_usd | Client-estimated cost |
| context_window.used_percentage | Context usage |
| context_window.current_usage.cache_read_input_tokens | Latest cache-read tokens |
| context_window.current_usage.cache_creation_input_tokens | Latest cache-write tokens |
| rate_limits.five_hour.used_percentage | Five-hour usage percentage |
| session_id, session_name | Session identity/name |
| prompt_id | Prompt UUID for telemetry correlation |
| output_style.name | Current style |
| agent.name | Main agent chosen by flag/settings |
| pr.number, pr.review_state | Branch PR information |
| worktree.name, worktree.branch | Worktree session information |

## Passion8 use

The status line reads local session data. Useful fields include:

| Goal | Fields |
| --- | --- |
| Inspect cache reuse | cache_read_input_tokens and cache_creation_input_tokens |
| Decide when to compact | context_window.used_percentage |
| Track cost trends | cost.total_cost_usd |
| Distinguish tasks | session_name, current_dir, worktree.name |

Client estimates may differ from Passion8 billing. The console remains authoritative for balance and charges.

## Windows configuration

PowerShell example:

```powershell title="$HOME\\.claude\\statusline.ps1"
$inputJson = [Console]::In.ReadToEnd() | ConvertFrom-Json
$model = $inputJson.model.display_name
$pct = $inputJson.context_window.used_percentage
Write-Output "[$model] $pct% context"
```

Settings:

```json title="~/.claude/settings.json"
{
  "statusLine": {
    "type": "command",
    "command": "powershell -ExecutionPolicy Bypass -File \"$HOME\\.claude\\statusline.ps1\""
  }
}
```

## Cache effects

| Action | Effect |
| --- | --- |
| Add/edit statusLine | Does not normally change the system prompt or cache |
| Generate with /statusline | Ordinary model conversation with normal prefix reuse |
| Refresh script | Local execution, no model tokens |
| Run Git/shell within script | Affects local performance, not model context |

## Official references

- [Customize your status line](https://code.claude.com/en/docs/en/statusline.md)
- [Settings](https://code.claude.com/en/docs/en/settings.md)
- [Prompt caching](https://code.claude.com/en/docs/en/prompt-caching.md)