James Duffy

Setting up a Claude Code status line to improve your productivity

// By •

I tend to have a lot of Claude Code sessions open at once: different projects, different tasks, sometimes half a dozen terminals running in parallel. After a while I would lose track of which chat was working in which directory. I would switch windows and have no idea if I was looking at the API repo, the frontend, or some script I started an hour ago.

Claude Code lets you wire up a custom status line: a shell script that runs on every render and prints whatever you want at the bottom of the terminal. Instead of writing the script by hand, I wrote a prompt describing exactly what I wanted and had Claude Code build it.

Claude Code terminal showing a custom status line with folder, model name, effort level, a green usage bar at 14%, and a green context bar at 8%

Left to right: folder, model, effort level, plan usage as a bar (the money bag means I’m on a dollar-based monthly budget rather than session rate limits), and context window usage as a second bar. Both bars go green to yellow to red as they fill up.

#The prompt

This is the prompt I used, if you want your own version:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Set up a custom Claude Code status line as a bash script at ~/.claude/scripts/statusline.sh, wired up via the statusLine key in ~/.claude/settings.json.

The status line should show these segments, in order, separated by |:

1. Current folder — from the stdin JSON's workspace.current_dir (fall back to pwd if missing), with $HOME shortened to ~.
2. Git branch — only shown if the folder is inside a git repo. Use git branch --show-current. Append * if the repo has uncommitted changes (git status --porcelain is non-empty). Omit this segment entirely outside a git repo.
3. Model name — from stdin JSON's model.display_name.
4. Effort level — from stdin JSON's effort.level (low/medium/high/xhigh/max), shown as Effort: <level>. Omit if the field is absent (not all models report it).
5. Plan usage — read it from stdin JSON's rate_limits first:
  - If rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage are present (percentages 0-100), show both as separate bars labeled 5h and 7d.
  - Otherwise, if rate_limits.spend_limit.used_percentage is present (accounts on a dollar-based budget instead of session rate limits), show it as one bar labeled with a money bag emoji (💰).
  - Only if rate_limits is missing entirely, fall back to a GET request to https://api.anthropic.com/api/oauth/usage. Auth: get the OAuth token from the macOS keychain (security find-generic-password -s 'Claude Code-credentials' -w, parse claudeAiOauth.accessToken from the JSON with jq), and send headers Authorization: Bearer <token>, anthropic-beta: oauth-2025-04-20, Content-Type: application/json. Use five_hour.utilization and seven_day.utilization, or spend.percent, the same way as above. Cache the response to a file (e.g. ~/.claude/cache/usage.json) and only refetch if the cached file is more than 60 seconds old — don't hit the API on every status line render.
6. Context window usage — from stdin JSON's context_window.used_percentage. Default to 0 if the field is missing (e.g. brand new chat with no usage yet — should show 0%, not disappear). Label it Context.

Bar rendering: each usage/context value should render as a 10-character block bar (█ for filled, ░ for empty, scaled to the percentage) followed by the percentage number, color-coded with ANSI escape codes:
- Usage/budget/5h/7d bars: green under 50%, yellow 50-80%, red above 80%.
- Context bar: green under 50%, yellow 50-70%, red above 70% (different thresholds — it fills up faster and matters sooner).

Implementation notes:
- Script reads the status line JSON from stdin (Claude Code pipes it in).
- Use jq for all JSON parsing.
- Every segment except the folder and the usage bar should degrade gracefully and just be omitted if its data isn't available, rather than erroring or showing empty labels.
- After building it, test it by piping synthetic JSON payloads into the script to verify all the thresholds and fallback cases.
- Wire it up in ~/.claude/settings.json with statusLine: {type: "command", command: "/absolute/path/to/statusline.sh", padding: 0} and restart Claude Code.

#Using it

Drop this into a Claude Code session, let it write the script and update your settings, then restart Claude Code to pick up the new status line.

A couple of things worth knowing before you run it:

  • Claude Code now passes your rate limit usage to the status line script directly, so on a Pro or Max plan the usage bars work without any extra API calls. The usage bars only show up after the first response in a session.
  • The https://api.anthropic.com/api/oauth/usage fallback isn’t a public API, it’s what the Claude Code CLI itself calls internally. Anthropic could change it without notice, which would just mean the usage bars stop showing up rather than the whole status line breaking.
  • The keychain lookup in that fallback only works on macOS. On Linux you would need to swap in wherever your OAuth credentials are actually stored.
  • You need jq installed (brew install jq).

Related Posts