Status Line

The status line is a customizable bar at the bottom of Claude Code that runs any shell script you configure. Example: [Opus] 📁 my-app | 🌿 feature/auth with a progress bar 42% | $0.08 | ⏱ 7m 3s.

Use-cases:

Monitor context window usage as you work
Track session costs
Work across multiple sessions and need to distinguish them
Want git branch and status always visible

The statusline is a bash script located at ~/.claude/statusline.sh. You can use a shebang to use a different language to code the script (e.g. Python, Node).

/statusline command can be used to generate the code to display a custom status line — describe it in natural language, e.g. /statusline show model name and context percentage with a progress bar. You can also use natural language to remove it, e.g. /statusline clear or /statusline remove it.

~/.claude/settings.json is where the statusline is configured:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

The command can also be an inline one-liner (e.g. using jq) instead of a script file.

Example script logic:

Read all of stdin into a variable, extract fields with jq (e.g. .model.display_name, .context_window.used_percentage).
Build a progress bar with printf/tr.
Git status with colors: run git rev-parse --git-dir, git branch --show-current, git diff --cached --numstat (staged), git diff --numstat (modified); print +{staged} (green) and ~{modified} (yellow).
Cost and duration tracking: pull data.cost.total_cost_usd and data.cost.total_duration_ms, format as $X.XX | Xm Xs.

Claude Code sends the following JSON "Sessions data" as STDIN to the statusline script:

{
  "cwd": "/current/working/directory",
  "session_id": "abc123...",
  "transcript_path": "/path/to/transcript.jsonl",
  "model": { "id": "claude-opus-4-6", "display_name": "Opus" },
  "workspace": { "current_dir": "...", "project_dir": "..." },
  "version": "1.0.80",
  "output_style": { "name": "default" },
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_api_duration_ms": 2300,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15234,
    "total_output_tokens": 4521,
    "context_window_size": 200000,
    "used_percentage": 8,
    "remaining_percentage": 92,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  },
  "exceeds_200k_tokens": false,
  "vim": { "mode": "NORMAL" },
  "agent": { "name": "security-reviewer" },
  "worktree": {
    "name": "my-feature",
    "path": "/path/to/.claude/worktrees/my-feature",
    "branch": "worktree-my-feature",
    "original_cwd": "/path/to/project",
    "original_branch": "main"
  }
}