Why use a script instead of the /statusline command?

The /statusline command asks Claude to write the script for you, which works well. A fixed script is useful when you want the same line on several machines, want to read exactly what runs on every update, or don't want to spend a prompt on it.

How often does the status line update?

Claude Code runs the script when a session starts, after each new assistant message, after /compact, and when the permission or vim mode changes, debounced at 300 ms. Set refreshInterval to also re-run it every N seconds, which helps while background work runs and the main session is quiet.

Does the status line cost tokens?

No. Claude Code runs the command locally and shows what it prints. Nothing is sent to the model.

Can the status line show how far along a task is?

Yes, if the agent reports its progress somewhere the script can read. Claude Code's JSON describes the session (model, context, cost, git), not the work. With Taskhold, the agent reports steps and progress through MCP, and a status line script can fetch the task in progress from the REST API and print its bar and running step. The docs page "Show the current task in the Claude Code status line" has the script.

Claude Code status line generator

Claude Code's status line is a shell command: Claude Code pipes session data to it as JSON and shows whatever it prints. Tick what you want below, check the preview, and copy two things: the script and one setting. The script reads only fields Claude Code documents, and our tests run the generated scripts with bash and jq.

By Jake Marsh. Field list checked against Claude Code's status line docs on 2026-10-26. Runs in your browser.

What to show

Colors Two lines (where you are, then usage)Re-run everyseconds

Preview with sample session data

[Opus] | api-server | main | ####------ 42% | $1.23

1. The script

Save as ~/.claude/statusline.sh, then run chmod +x ~/.claude/statusline.sh. Needs bash and jq.

#!/usr/bin/env bash
# Claude Code status line. Generated at taskhold.com/tools/claude-code-statusline
# Reads the session JSON Claude Code sends on stdin. Needs jq (brew install jq / apt install jq).
input=$(cat)
{ read -r MODEL; read -r DIR; read -r PCT; read -r COST; } < <(echo "$input" | jq -r '(.model.display_name // ""), (.workspace.current_dir // .cwd // ""), (.context_window.used_percentage // 0 | floor), (.cost.total_cost_usd // 0)')
SEG_model="\033[36m[$MODEL]\033[0m"
SEG_dir="${DIR##*/}"
BRANCH=$(git -C "${DIR:-.}" branch --show-current 2>/dev/null)
[ -n "$BRANCH" ] && SEG_branch="\033[32m$BRANCH\033[0m"
FILLED=$(( PCT / 10 )); [ "$FILLED" -gt 10 ] && FILLED=10
printf -v BAR '%*s' "$FILLED" ''; BAR=${BAR// /#}
printf -v PAD '%*s' "$(( 10 - FILLED ))" ''; PAD=${PAD// /-}
if [ "$PCT" -ge 80 ]; then CC="\033[31m"; elif [ "$PCT" -ge 50 ]; then CC="\033[33m"; else CC="\033[32m"; fi
SEG_context="${CC}${BAR}\033[0m${PAD} ${PCT}%"
SEG_cost=$(printf '$%.2f' "$COST")
SEP="\033[2m | \033[0m"
join() { local out="" s; for s in "$@"; do [ -n "$s" ] || continue; if [ -n "$out" ]; then out="$out$SEP$s"; else out="$s"; fi; done; printf '%b\n' "$out"; }
join "$SEG_model" "$SEG_dir" "$SEG_branch" "$SEG_context" "$SEG_cost"

2. The setting

Add to ~/.claude/settings.json (merge with what's there). Claude Code picks it up when you save.

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

How the status line works

Claude Code reads a statusLine object from your settings with type: "command" and a command to run. On each update it sends the session as JSON on stdin: the model, the working directory, context window use, estimated cost and duration, lines changed, rate limits on Pro and Max plans, the open pull request and more. Each line your script prints becomes a row, and ANSI color codes work in terminals that support them.

Some fields can be missing: rate limits appear only on Pro and Max plans, the PR only while one is open, the worktree only inside a linked worktree. The script skips a segment when its field is empty.
The context percentage counts input tokens only, so it matches what Claude Code shows elsewhere.
The cost is an estimate at list price and can differ from your bill.
Claude Code captures the output, so a script that needs the terminal width should read COLUMNS rather than call tput.

Showing task progress in the status line

Everything in that JSON is about the session, not the task. On its own it can show that Claude has used 42% of its context and $1.23, but not that it is on step 3 of 5 of a migration, or that it stopped twenty minutes ago to ask you something.

For that, the agent has to report its own progress somewhere the script can read. In Taskhold, an agent breaks a task into steps with taskhold_plan and reports progress with taskhold_progress. A status line script can then ask the Taskhold API for the task in progress and print its bar and the running step next to the segments above: Show the current task in the Claude Code status line has the script and the settings block. The same progress shows on the live board, on a laptop or a phone, for every agent you run. How to see what your coding agent is doing covers the other options, including the ones built into Claude Code.

Questions

Why use a script instead of the /statusline command?: The /statusline command asks Claude to write the script for you, which works well. A fixed script is useful when you want the same line on several machines, want to read exactly what runs on every update, or don't want to spend a prompt on it.
How often does the status line update?: Claude Code runs the script when a session starts, after each new assistant message, after /compact, and when the permission or vim mode changes, debounced at 300 ms. Set refreshInterval to also re-run it every N seconds, which helps while background work runs and the main session is quiet.
Does the status line cost tokens?: No. Claude Code runs the command locally and shows what it prints. Nothing is sent to the model.
Can the status line show how far along a task is?: Yes, if the agent reports its progress somewhere the script can read. Claude Code's JSON describes the session (model, context, cost, git), not the work. With Taskhold, the agent reports steps and progress through MCP, and a status line script can fetch the task in progress from the REST API and print its bar and running step. The docs page "Show the current task in the Claude Code status line" has the script.

See the task, not just the session.

Taskhold gives Claude Code, Cursor, Codex and other MCP clients one task list with steps, progress bars and blocked questions you answer from a live board. $12 a month or $120 a year per person, 7-day trial with a card.

Start my 7-day trial Taskhold for Claude Code