Customize your status line

The status line is a customizable bar at the bottom of Claude Code that runs any shell script you configure. It receives JSON session data on stdin and displays whatever your script prints, giving you a persistent, at-a-glance view of context usage, costs, git status, or anything else you want to track. Status lines are useful when you:

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

The status line renders in its own row above the built-in footer badges and does not replace them. With a custom status line configured, Claude Code stops showing most of the footer’s keyboard hints, including esc to interrupt, the ? for shortcuts fallback, and the hold space to speak voice dictation hint. To add clickable link badges to the footer when an ID appears in the conversation, without writing a script, configure footerLinksRegexes instead. Here’s an example of a multi-line status line that displays git info on the first line and a color-coded context bar on the second.

A multi-line status line showing model name, directory, git branch on the first line, and a context usage progress bar with cost and duration on the second line

This page walks through setting up a basic status line, explains how the data flows from Claude Code to your script, lists all the fields you can display, and provides ready-to-use examples for common patterns like git status, cost tracking, and progress bars.

Set up a status line

Use the /statusline command to have Claude Code generate a script for you, or manually create a script and add it to your settings.

Use the /statusline command

The /statusline command accepts natural language instructions describing what you want displayed. Claude Code generates a script file in ~/.claude/ and updates your settings automatically:

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

Approve the file edit prompts if Claude Code asks for permission during setup.

Manually configure a status line

Add a statusLine field to your user settings (~/.claude/settings.json, where ~ is your home directory) or project settings. Set type to "command" and point command to a script path or an inline shell command. For a full walkthrough of creating a script, see Build a status line step by step.

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

The command field runs in a shell, so you can also use inline commands instead of a script file. This example uses jq to parse the JSON input and display the model name and context percentage:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

The optional padding field adds extra horizontal spacing (in characters) to the status line content. Defaults to 0. This padding is in addition to the interface’s built-in spacing, so it controls relative indentation rather than absolute distance from the terminal edge. The optional refreshInterval field re-runs your command every N seconds in addition to the event-driven updates. The minimum is 1. Set this when your status line shows time-based data such as a clock, or when background subagents change git state while the main session is idle. Leave it unset to run only on events. The optional hideVimModeIndicator field suppresses the built-in -- INSERT -- text below the prompt. Set this to true when your script renders vim.mode itself, so the mode is not shown twice.

Disable the status line

Run /statusline and ask it to remove or clear your status line (e.g., /statusline delete, /statusline clear, /statusline remove it). You can also manually delete the statusLine field from your settings.json.

Build a status line step by step

This walkthrough shows what’s happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.

Running /statusline with a description of what you want configures all of this for you automatically.

These examples use Bash scripts, which work on macOS and Linux. On Windows, see Windows configuration for PowerShell and Git Bash examples.

A status line showing model name, directory, and context percentage

Create a script that reads JSON and prints output

Claude Code sends JSON data to your script via stdin. This script uses jq, a command-line JSON parser you may need to install, to extract the model name, directory, and context percentage, then prints a formatted line.Save this to ~/.claude/statusline.sh (where ~ is your home directory, such as /Users/username on macOS or /home/username on Linux):

#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)

# Extract fields using jq
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Output the status line - ${DIR##*/} extracts just the folder name
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"

Make it executable

Mark the script as executable so your shell can run it:

chmod +x ~/.claude/statusline.sh

Add to settings

Tell Claude Code to run your script as the status line. Add this configuration to ~/.claude/settings.json, which sets type to "command" (meaning “run this shell command”) and points command to your script:

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

Your status line appears at the bottom of the interface. Settings reload automatically, but changes won’t appear until your next interaction with Claude Code.

How status lines work

Claude Code runs your script and pipes JSON session data to it via stdin. Your script reads the JSON, extracts what it needs, and prints text to stdout. Claude Code displays whatever your script prints. When it updates Your script runs once when a session starts, including when you resume one. After that, it runs again when:

A new assistant message arrives
/compact finishes
The permission mode changes
Vim mode toggles
A refreshInterval timer elapses, if you set one

Claude Code debounces updates at 300ms, so rapid changes batch together and your script runs once after the changes stop. If a new update triggers while your script is still running, Claude Code cancels the in-flight script. If you edit your script, the changes appear the next time an update trigger re-runs it. The event-driven triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. To keep time-based or externally-sourced segments current during idle periods, set refreshInterval to also re-run the command on a fixed timer. What your script can output

Multiple lines: each echo or print statement displays as a separate row. See the multi-line example.
Colors: use ANSI escape codes like \033[32m for green (terminal must support them). See the git status example.
Links: use OSC 8 escape sequences to make text clickable (Cmd+click on macOS, Ctrl+click on Windows/Linux). Requires a terminal that supports hyperlinks like iTerm2, Kitty, or WezTerm. See the clickable links example.

Sizing output to the terminal Claude Code captures your script’s output instead of connecting it directly to the terminal, so tput cols and language-level width detection cannot read the terminal size from inside the script. Read the COLUMNS and LINES environment variables instead. Claude Code sets these to the current terminal dimensions before running your script. Requires Claude Code v2.1.153 or later.

The status line runs locally and does not consume API tokens. It temporarily hides during certain UI interactions, including autocomplete suggestions, the help menu, and permission prompts.

Available data

Claude Code sends the following JSON fields to your script via stdin:

Field	Description
`model.id`, `model.display_name`	Current model identifier and display name
`cwd`, `workspace.current_dir`	Current working directory. Both fields contain the same value; `workspace.current_dir` is preferred for consistency with `workspace.project_dir`.
`workspace.project_dir`	Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session
`workspace.added_dirs`	Additional directories added via `/add-dir` or `--add-dir`. Empty array if none have been added
`workspace.git_worktree`	Git worktree name when the current directory is inside a linked worktree created with `git worktree add`. Absent in the main working tree. Populated for any git worktree, unlike `worktree.*` which applies only to `--worktree` sessions
`workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name`	Repository identity parsed from the `origin` remote, for example `"github.com"`, `"anthropics"`, `"claude-code"`. Absent outside a git repository or when no `origin` remote is configured
`cost.total_cost_usd`	Estimated session cost in USD, computed client-side. May differ from your actual bill. Resets to $0 when `/clear` starts a new session
`cost.total_duration_ms`	Total wall-clock time since the session started, in milliseconds
`cost.total_api_duration_ms`	Total time spent waiting for API responses in milliseconds
`cost.total_lines_added`, `cost.total_lines_removed`	Lines of code changed
`context_window.total_input_tokens`, `context_window.total_output_tokens`	Token counts currently in the context window, from the most recent API response. Input includes cache reads and writes
`context_window.context_window_size`	Maximum context window size in tokens. 200000 by default, or 1000000 for models with extended context.
`context_window.used_percentage`	Pre-calculated percentage of context window used
`context_window.remaining_percentage`	Pre-calculated percentage of context window remaining
`context_window.current_usage`	Token counts from the last API call, described in context window fields
`exceeds_200k_tokens`	Whether the total token count (input, cache, and output tokens combined) from the most recent API response exceeds 200k. This is a fixed threshold regardless of actual context window size.
`fast_mode`	Whether fast mode is enabled for the session
`effort.level`	Current reasoning effort (`low`, `medium`, `high`, `xhigh`, or `max`). Reflects the live session value, including mid-session `/effort` changes. Ultracode is not a distinct level and reports as `xhigh`. Absent when the current model does not support the effort parameter
`thinking.enabled`	Whether extended thinking is enabled for the session
`rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage`	Percentage of the 5-hour or 7-day rate limit consumed, from 0 to 100
`rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at`	Unix epoch seconds when the 5-hour or 7-day rate limit window resets
`session_id`	Unique session identifier
`session_name`	Session name. Uses the custom name set with the `--name` flag or `/rename` when one exists, otherwise the AI-generated session title. The default display name, such as `my-app-3f`, doesn’t populate this field. Absent when the session has neither a custom name nor an AI-generated title
`prompt_id`	UUID identifying the user prompt currently being processed. Matches the `prompt.id` attribute on OpenTelemetry events. Absent until the first user input. Requires Claude Code v2.1.196 or later
`transcript_path`	Path to conversation transcript file
`version`	Claude Code version
`output_style.name`	Name of the current output style
`vim.mode`	Current vim mode (`NORMAL`, `INSERT`, `VISUAL`, or `VISUAL LINE`) when vim mode is enabled
`agent.name`	Agent name when running with the `--agent` flag or agent settings configured
`pr.number`, `pr.url`	Open pull request for the current branch. Mirrors the PR badge in the footer. In a repository with a GitLab remote, Claude Code fills these fields from the branch’s open merge request instead, so `pr.number` is the merge request number. Merge request data requires Claude Code v2.1.234 or later. Absent when not in a git repository, until a pull request or merge request is found, or once it merges or closes
`pr.review_state`	Review status of the open PR: `approved`, `pending`, `changes_requested`, or `draft`. May be independently absent even when `pr` is present
`pr.kind`	`mr` when `pr` describes a GitLab merge request. Absent for GitHub pull requests, so scripts written before this field keep working. For a merge request, Claude Code sets `review_state` to `approved` when GitLab reports it mergeable, `pending` for any other open state, and `draft` for a draft. Requires Claude Code v2.1.234 or later
`worktree.name`	Name of the active worktree. Present only during `--worktree` sessions
`worktree.path`	Absolute path to the worktree directory
`worktree.branch`	Git branch name for the worktree (for example, `"worktree-my-feature"`). Absent for hook-based worktrees
`worktree.original_cwd`	The directory Claude was in before entering the worktree
`worktree.original_branch`	Git branch checked out before entering the worktree. Absent for hook-based worktrees

Full JSON schema

Your status line command receives this JSON structure via stdin:

{
  "cwd": "/current/working/directory",
  "session_id": "abc123...",
  "session_name": "my-session",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/path/to/transcript.jsonl",
  "model": {
    "id": "claude-opus-5",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/current/working/directory",
    "project_dir": "/original/project/directory",
    "added_dirs": [],
    "git_worktree": "feature-xyz",
    "repo": {
      "host": "github.com",
      "owner": "anthropics",
      "name": "claude-code"
    }
  },
  "version": "2.1.90",
  "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": 15500,
    "total_output_tokens": 1200,
    "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,
  "fast_mode": false,
  "effort": {
    "level": "high"
  },
  "thinking": {
    "enabled": true
  },
  "rate_limits": {
    "five_hour": {
      "used_percentage": 23.5,
      "resets_at": 1738425600
    },
    "seven_day": {
      "used_percentage": 41.2,
      "resets_at": 1738857600
    }
  },
  "vim": {
    "mode": "NORMAL"
  },
  "agent": {
    "name": "security-reviewer"
  },
  "pr": {
    "number": 1234,
    "url": "https://github.com/anthropics/claude-code/pull/1234",
    "review_state": "pending"
  },
  "worktree": {
    "name": "my-feature",
    "path": "/path/to/.claude/worktrees/my-feature",
    "branch": "worktree-my-feature",
    "original_cwd": "/path/to/project",
    "original_branch": "main"
  }
}

Fields that may be absent (not present in JSON):

session_name: appears when a custom name has been set with --name or /rename, or once an AI-generated session title exists. The default display name, such as my-app-3f, doesn’t populate it
prompt_id: appears only after the first user input
workspace.git_worktree: appears only when the current directory is inside a linked git worktree
workspace.repo: appears only inside a git repository with an origin remote configured
effort: appears only when the current model supports the reasoning effort parameter
vim: appears only when vim mode is enabled
agent: appears only when running with the --agent flag or agent settings configured
pr: appears only while an open PR or GitLab merge request is found for the current branch, and is removed once it merges or closes. pr.review_state and pr.kind may be independently absent
worktree: appears only during --worktree sessions. When present, branch and original_branch may also be absent for hook-based worktrees
rate_limits: appears only for Claude.ai subscribers (Pro/Max) after the first API response in the session. Each window (five_hour, seven_day) may be independently absent. Use jq -r '.rate_limits.five_hour.used_percentage // empty' to handle absence gracefully.

Fields that may be null:

context_window.current_usage: null before the first API call in a session, and again after /compact until the next API call repopulates it
context_window.used_percentage, context_window.remaining_percentage: may be null early in the session

Handle missing fields with conditional access and null values with fallback defaults in your scripts.

Context window fields

The context_window object describes the live context window from the most recent API response.

Combined totals (total_input_tokens, total_output_tokens): tokens currently in the context window. total_input_tokens is the sum of input_tokens, cache_creation_input_tokens, and cache_read_input_tokens; total_output_tokens is the output tokens from the most recent response. Both are 0 before the first API response.
Per-component usage (current_usage): the same token counts broken out by category. Use this when you need cache hits separate from fresh input.

The

Settings and permissions

Environments

Model and responses

Interface

Set up a status line

Use the /statusline command

Manually configure a status line

Disable the status line

Build a status line step by step

How status lines work

Available data

Context window fields

​Set up a status line

​Use the /statusline command

​Manually configure a status line

​Disable the status line

​Build a status line step by step

​How status lines work

​Available data

​Context window fields

Set up a status line

Use the /statusline command

Manually configure a status line

Disable the status line

Build a status line step by step

How status lines work

Available data

Context window fields