How to make a Claude Code statusline.

What a Claude Code statusline actually is

Claude Code can show a customizable bar at the bottom of the terminal. Its documentation calls it the statusline; many developers search for it as a status line or a status bar. All three names mean the same feature.

It is not a widget with fixed options. It is a command you configure. Claude Code starts that command, writes the current session as JSON to its standard input, reads what it prints on standard output, and draws the result. Anything a shell script can work out (a git branch, a context budget, a cost estimate) can go on the line.

The whole contract: session JSON goes in, styled text comes out. Everything in between is your script.

The command runs locally on your machine, so running it spends no API tokens. Claude Code does not call it constantly; it refreshes after each assistant message and on a few other events (details below).

Three ways to make one

Pick by how much control you want and how much you enjoy shell quoting. They all end up as the same thing: a script plus a statusLine entry in settings.

Build one visually in six steps

1. Open the builder and pick a starting point

   Open the Claude Code statusline builder. Start from a blank canvas or fork a template such as Minimal, Verbose Dev, Two-Line Cockpit or Powerline. The screenshots below use Verbose Dev.

2. Add elements from the Elements drawer

   The drawer at the bottom of the canvas groups elements into Identity, Git, Context, Session, Rate limits, Text and Layout. Click one to add it, or drag it onto the canvas. Drag chips left or right to reorder them.

   

3. Style each element in the Inspector

   Click a chip and the Inspector opens on the right. Content controls what is shown (precision, prefix, suffix, max length). Appearance sets foreground and background color. Decorations toggles bold, italic, dim and underline, and Visibility hides an element until a condition is true.

   

4. Check the live preview

   The terminal frame under the canvas re-renders on every change, using the same interpreter that generates the installed script. Open Edit mock data to try a fresh session, a deep one near the context limit, or a folder without git.

5. Install with one command

   Click Install in Claude Code, choose macOS, Linux or Windows, copy the command and run it in a terminal.

   

6. Optional: save or publish it

   Publish adds the design to the community gallery under your name so others can preview and fork it. Published designs cannot be edited or removed, so use Export JSON first if you want a copy.

   

What the installer does, and how to check it

The generated command downloads a self-contained installer and runs it. You can read it first: the dialog's Inspect exactly what runs link shows it, and the same script is served at a plain URL if you would rather download it and run it yourself.

# macOS and Linux
curl -fsSL https://statusline-community.zoniixyt.workers.dev/i/<design-id>.sh | bash

# Windows (PowerShell)
irm https://statusline-community.zoniixyt.workers.dev/i/<design-id>.ps1 | iex

• Writes your statusline script to ~/.claude/statusline.sh (statusline.ps1 on Windows).
• Saves a timestamped backup of ~/.claude/settings.json next to it before changing anything.
• Merges the statusLine entry into the JSON structurally, so every other key (model, permissions, MCP servers) survives.
• Points command at the script's absolute path.

Claude Code reloads settings when the file changes, so the new line normally appears on your next interaction. The installer still tells you to restart Claude Code, which is the safe fallback if nothing shows up. To remove the statusline, delete the statusLine key from your settings (or ask Claude Code to remove it with /statusline).

Statusline examples to steal from

Every line below is rendered live in your browser by the same engine that produces the installed script. These are real ANSI colors from mock session data, not screenshots. Switch the design and the session to watch colors react to context, cost and git state.

The community gallery has more designs, each with a live preview and a one-command install. Fork any of them into the builder and change what you don't like.

Add one thing at a time

Once the basics work, add the pieces you actually glance at during a long session. Each guide has a live preview and the element settings that matter.

• Git branch: Show which branch you are on, with a dirty marker.
• Context and token usage: A bar or percentage that changes color as the window fills.
• Session cost: The running dollar cost, at the precision you choose.
• Model name: Always know which model is answering.
• Session duration: Elapsed time, human-readable or HH:MM:SS.
• Rate limits: 5-hour and 7-day usage for Pro and Max plans.

Write one by hand

You do not need the builder to make a statusline. You need a script that reads JSON on stdin and prints text. This bash version uses jq and shows the model, the folder, and how full the context window is.

#!/usr/bin/env bash
# Read the session JSON Claude Code sends on stdin.
input=$(cat)

model=$(echo "$input" | jq -r '.model.display_name // "Claude"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // "."')
used=$(echo "$input" | jq -r '.context_window.used_percentage // 0')

# Bold model, plain folder name, dim context percentage.
printf '\033[1m%s\033[0m  %s  \033[2m%.0f%% ctx\033[0m\n' "$model" "${dir##*/}" "$used"

Make it executable and test it with sample JSON before Claude Code ever runs it. It should print the bold model name, my-project, and a dim 47% ctx. Running it with no piped input just waits for stdin.

chmod +x ~/.claude/statusline.sh
echo '{"model":{"display_name":"Fable 5.1"},"workspace":{"current_dir":"/Users/dev/my-project"},"context_window":{"used_percentage":47.2}}' | ~/.claude/statusline.sh

Then point Claude Code at it. Back up ~/.claude/settings.json and merge this entry into it, keeping your other settings.

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

Optional keys on statusLine: padding adds horizontal padding, and refreshInterval re-runs the command on a timer (in seconds, minimum 1), which suits clocks or anything that changes between messages. Print several lines and each becomes its own row.

The hardest part of doing this by hand is the escape codes. Try them here: toggle a style or pick a color and the generated sequence updates underneath.

The JSON Claude Code sends your script

Every run receives one JSON object on stdin. Pick a field to see a realistic value and the jq expression that reads it, then switch the session to watch the values change.

This is a subset. Claude Code adds fields over time, so check the official statusline documentation for the full current list.

When the statusline refreshes

Claude Code re-runs your command when something worth showing has changed:

• After each new assistant message, and after /compact.
• When the permission mode changes or vim mode is toggled.
• When the command in your settings changes.
• On a timer, if you set refreshInterval.
• When a rate-limit window resets or the prompt cache expires.

Updates are debounced by roughly 300 ms, and a run still in flight is cancelled when a newer update starts. Keep the script fast, and cache anything slow such as a network call. Claude Code notifications share the row, so a very long line can get truncated.

Windows: Git Bash or PowerShell

On Windows, Claude Code runs the statusline command through Git Bash when it is installed and PowerShell otherwise. Use forward slashes in the command path; ~ works too.

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}

The easy route is the builder's Windows tab: it writes a PowerShell script and the matching settings entry for you with irm … | iex, and keeps the rest of your settings intact.

Troubleshooting a blank or broken statusline

Frequently asked questions

Keep reading

• The /statusline command: What Claude Code's built-in command writes, and when to skip it.
• Community designs: Live previews you can install or fork.
• Show context usage: A bar that warns before you hit the limit.
• Show the git branch: Branch name plus a dirty marker.

Make yours in about five minutes.

Start from a template or a blank canvas, watch the preview update as you go, and install with one command.

Open the Claude Code statusline builder