All posts

The Claude Code Status Line: Setup, Examples & Ideas (2026)

·Terminal Candy ·7 min read

claude codestatus linecustomizationguide

The status line is the one strip of Claude Code's interface that's fully yours. It sits at the bottom of the session, it updates as you work, and Claude Code will render whatever your script prints there — your git branch, the model you're on, your working directory, a cost ticker, or a tiny ASCII pet. Most people never touch it. Setting it up takes about two minutes, and it's the fastest way to make an agent session feel like your cockpit instead of a stock demo. Here's the full setup, some working examples, and a few ideas worth stealing.

What the status line actually is

Claude Code renders a single line of text at the bottom of the terminal UI and refreshes it as the session changes. The content comes from a command you provide: Claude Code runs it, passes session context as JSON on stdin, and displays the first line of whatever it prints. ANSI color codes are respected, which matters more than it sounds — it's the difference between a gray afterthought and something that looks designed.

Because it's just a script, there are no widgets to learn and no plugin API. If you can print a line from bash (or Python, or anything else), you can build a status line.

The two-minute setup

The easy path: run /statusline inside Claude Code and describe what you want — it writes the script and wires the setting for you. That's genuinely the fastest route, and you can hand-edit the result afterward.

The manual path is two pieces. First, point your settings at a command in ~/.claude/settings.json:

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

Then make the script. The JSON on stdin includes the model, the workspace, and more — jq is the natural tool for picking it apart:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
branch=$(git branch --show-current 2>/dev/null)
echo "$model · $dir${branch:+ · $branch}"

chmod +x ~/.claude/statusline.sh, restart the session, and you have a live readout: model, project, branch.

What's actually worth showing

Screen real estate is one line, so ruthlessness pays. The things people keep after the novelty wears off:

  • Git branch — the single highest-value item. Agents switch branches, and you want to notice.
  • Model name — when you move between models for different tasks, a glance beats a guess.
  • Working directory — if you run several sessions across projects, this is what keeps them straight.
  • A color accent that matches your theme — one well-chosen ANSI color ties the whole window together. Our themes guide pairs well here.

And the fun tier: session cost tickers, pomodoro timers, weather, a progress bar that fills as the context window fills. One line of personality is the point — this is the same instinct we wrote about in Vibe Coding: Why Your Terminal's Aesthetic Actually Matters.

Make it legible, then make it pretty

Two practical notes. First, your status line inherits the terminal's font — glyphs like , and `` need a patched font, and the nerd font guide covers the good ones. Second, colors: bold plus one accent reads better than a rainbow. Test against your actual background — a status line tuned on a dark theme can vanish on a light one.

# an amber accent, bold model name
printf '\033[1m%s\033[0m \033[38;5;214m%s\033[0m\n' "$model" "$branch"

The status line is one line — the window is the rest

Once the bottom of your session looks intentional, the stock window around it starts to look like the unfinished part. That's the territory Terminal Candy is built for (full disclosure — it's ours): a native macOS terminal where the entire window is a skin — a retro monitor, a handheld, a themed frame — with your shell and Claude Code running inside, plus alerts when the agent finishes or needs input while you're in another app. A custom status line inside a skinned window is about as far from a stock terminal as it gets; the community gallery is full of starting points, free to download and try.

The two-minute checklist

  1. Run /statusline in Claude Code, or wire statusLine in ~/.claude/settings.json to a script.
  2. Start with model + directory + git branch. Add nothing else yet.
  3. Add one ANSI accent color that matches your terminal theme.
  4. If glyphs show as boxes, install a nerd font.
  5. Live with it for a week, then add the fun stuff.

It's a small customization with an outsized effect: every glance at the bottom of the screen reminds you the setup is yours.

Keep reading