Claude Code supports this through its status line, a row at the bottom of the terminal that shows whatever a script of yours prints. This post covers the status line I use every day: what it shows, how to install it safely, how it works, the design mistakes I made building it, and how to remove it again.

The finished status line. In the terminal it's one row; it's split in two here so the labels fit.

Shortcut: let Claude Code do it for you

Use Claude Code? Open the original post and click Copy Claude Code prompt. Paste it into Claude Code and it does the setup for you: it downloads the installer, tells you what it will change and asks before running it.

Not using Claude Code? Follow the steps below by hand.

What the status line shows

● main │ Session: 1fb4ade2 │ Opus 5.5 │ ctx ■■■□□□□□  32% │ 5h ■□□□□□□□   4% ↻03:20 │ wk ■■■■■□□□  65% │ Est. usage: $6.44

Each bar is 8 squares; the filled part is coloured and the rest stays dark grey (shown as □ above).

Not every value is equally fresh:

• Live, worked out on your machine: the git branch, the ↻ countdown (your clock compared with the reset time) and the animation.

• Updated when Claude Code gets a new response: the ctx, 5h and wk percentages and the cost. The script redraws every second, but these numbers only change when Claude Code itself receives new data.

• An estimate: Est. usage is computed by Claude Code at list price and resets to $0 when /clear starts a new session. It may differ from your actual bill, and on a Pro or Max plan it isn't a charge at all.

• Sometimes unavailable: if a field is missing, its segment is simply left out. Nothing is guessed.

Prerequisites and compatibility

• Claude Code with status line support. I built and tested this with Claude Code 2.1.292 on macOS (Apple Terminal).

• bash, plus jq or python3 (the installer uses one of them to edit your settings, and the script uses one to read Claude Code's data). Check with which jq python3.

• git (optional) for the branch segment.

• A terminal with 256-colour support. Almost every modern terminal has it.

• For the 5h and wk bars: a Claude.ai Pro or Max subscription. Claude Code only sends the 5-hour and weekly limits to Pro and Max subscribers, and only after the first API response in a session. With an API key, Amazon Bedrock or Google Vertex, those two segments don't appear; the rest still works.

It's written for macOS and Linux. I've only tested it on macOS. On Windows, Claude Code runs status line commands through Git Bash or PowerShell; this bash script may work under Git Bash, but I haven't tested it.

Optional: make the terminal nicer for prompts

This is separate from the status line, but it's the first thing I set up. Run this inside Claude Code:

/terminal-setup

What it does depends on your terminal:

If you accepted Claude Code's terminal setup prompt on first run, this has already been done. With Option as Meta, these shortcuts work:

Option+Enter for a new line, Option+Arrow to move by word.

In any terminal, Ctrl+J or typing \ then Enter also adds a new line, and Shift+Enter already works in Apple Terminal, iTerm2 and several others without setup.

Trade-off: with Option as Meta, Option no longer types characters like ©, € or ñ in Terminal. To undo it, untick Terminal → Settings → Profiles → Keyboard → "Use Option as Meta Key".

Install

The installer is a single bash file. Download it, read it, then run it:

curl -fsSL https://siddarammetri.in/blog/claude-code-status-line/install.sh \
  -o /tmp/statusline-install.sh
less /tmp/statusline-install.sh   # read it first (q to quit)
bash /tmp/statusline-install.sh

Read scripts before you run them. Don't pipe curl straight into bash, for this installer or any other. The file is short, and the top of it lists exactly what it changes.

It makes exactly these changes, and nothing else:

It doesn't touch your terminal, fonts or shell configuration.

A successful run looks like this (in your terminal the bars are coloured):

✓ Wrote /Users/you/.claude/statusline-command.sh
✓ Updated /Users/you/.claude/settings.json (backup: /Users/you/.claude/settings.json.bak-20261019-031500)

Preview with sample data:
● main │ Session: 1fb4ade2 │ Opus 5.5 │ ctx ■■■■■■■■  32% │ 5h ■■■■■■■■   4% ↻03:20 │ wk ■■■■■■■■  65% │ Est. usage: $6.44

Done. It appears at the bottom of Claude Code within a second (bars show after the first reply).
Undo: restore /Users/you/.claude/settings.json.bak-20261019-031500

The preview uses sample numbers, not your real usage.

Check that it worked

1. Confirm the setting is in place:

   jq .statusLine ~/.claude/settings.json
   

   You should see "type": "command", "command": "bash /Users/you/.claude/statusline-command.sh" and "refreshInterval": 1.

2. Start Claude Code (claude) and send any message. The branch, session and model appear straight away; the ctx, 5h, wk and cost segments appear after the first reply.

If the install fails

Configure and customize

The installer adds this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash /Users/you/.claude/statusline-command.sh",
    "refreshInterval": 1
  }
}

refreshInterval re-runs the script every N seconds in addition to Claude Code's normal updates. One second keeps the countdown and animation moving. On my Mac one run takes about 0.1 seconds; raise the number if you'd rather it ran less often, or remove the line to update only on events.

Everything else lives in ~/.claude/statusline-command.sh:

Your changes show up the next time the script runs. The installer overwrites the script, so re-running it replaces your edits (the previous version is backed up first).

How it works

Claude Code supplies the data; the script decides how it looks.

The status line is an official Claude Code feature:

1. Claude Code runs your command and passes the session's details to it as JSON on stdin.

2. Your script prints one line of text (more lines are allowed; ANSI colours are fine).

3. Claude Code shows that output at the bottom of the terminal.

It runs locally and doesn't use API tokens. Claude Code re-runs it when a session starts, when a new assistant message arrives, after /compact, when the permission mode changes, when a refreshInterval timer elapses, and when a usage window reaches its reset time. Updates are batched over about 300 ms.

The fields this script reads look like this (trimmed; Claude Code sends more):

{
  "session_id": "1fb4ade2-…",
  "model": { "display_name": "Opus 5.5" },
  "workspace": { "current_dir": "/Users/you/project" },
  "cost": { "total_cost_usd": 6.44 },
  "context_window": { "used_percentage": 32 },
  "rate_limits": {
    "five_hour": { "used_percentage": 4, "resets_at": 1792371600 },
    "seven_day": { "used_percentage": 65, "resets_at": 1792890000 }
  }
}

resets_at is a Unix timestamp in seconds. A few fields come and go, and the script handles each one:

• The 5-hour and weekly rate_limits are only sent to Pro and Max subscribers, only after the first response, and each window can be missing on its own. Claude Code drops a window once its reset time passes, so a bar can briefly disappear right after a reset.

• context_window.used_percentage can be empty early in a session.

• The script reads every field with a fallback, so a missing field means a missing segment rather than an error.

Design decisions (and mistakes)

Colours that mean something

One colour for everything tells you nothing. Each bar changes colour at four points:

Each bar is coloured on its own, so a green context bar can sit next to a yellow weekly bar.

The bar character matters more than you'd think

My first version used full blocks (█), which were far too chunky. The thin line ━ disappeared. Then I tried the lower ¾ block ▆, and it looked wrong without me knowing why: the bars seemed to sit lower than the text.

That's exactly what was happening. Block characters are anchored to the bottom of the character cell, so ▆ hangs below the baseline. A square ■ is centred in the cell and lines up with the letters.

Same font, same size: the block sits low, the square lines up with the text.

I found this by rendering each candidate next to text in the same font and comparing them, rather than guessing. And one rule I'd keep: don't change your terminal font to make a status line look right. Change the characters instead.

Numbers that don't make the line jump

4% is narrower than 19%, so everything after it shifted sideways whenever a value crossed 10%. Padding every number to three characters (printf '%3s') keeps every separator in a fixed place.

Animation with one frame per second

A shell script can't animate on its own, but with refreshInterval: 1 each run is a frame. The script uses the current second (date +%s) to move a lighter "shine" square along each bar, pulse the leading square so even a one-square bar visibly moves, blink the whole bar from 95%, and pulse the ● dot.

Troubleshooting and limitations

Claude Code's built-in commands are still useful for anything the line doesn't show:

Known limitations:

• The 5h and wk bars need a Pro or Max plan; the spend-limit data a Claude apps gateway can send isn't shown.

• Tested only on macOS with Apple Terminal. Linux should behave the same; Windows is untested.

• How ■ looks depends on your font.

Uninstall and recovery

There's no uninstall script, so here are the manual steps.

Easiest: run /statusline remove it inside Claude Code, which removes the statusLine setting for you. Then delete the script with rm ~/.claude/statusline-command.sh.

Or remove it by hand, keeping every other setting:

jq 'del(.statusLine)' ~/.claude/settings.json > /tmp/claude-settings.json \
  && mv /tmp/claude-settings.json ~/.claude/settings.json
rm ~/.claude/statusline-command.sh

Or restore your settings from the installer's backup:

ls ~/.claude/settings.json.bak-*            # pick the one from before the install
cp ~/.claude/settings.json.bak-<date-time> ~/.claude/settings.json

Restoring a backup also undoes any other settings changes you've made since, so the first option is usually better. If you had a status line script before, the installer kept it as ~/.claude/statusline-command.sh.bak-<date-time>; rename it back to bring it back. Once you're happy, you can delete the .bak- files.

FAQ

Does it make extra API requests or use tokens? No. The script only reads the data Claude Code passes to it and runs git locally. Claude Code states that the status line doesn't consume API tokens.

Does it work with an API key, Bedrock or Vertex? Mostly. The branch, session, model, context bar and estimated cost work. The 5h and wk bars don't appear, because Claude Code only sends plan-limit data to Pro and Max subscribers.

How often does it refresh? The script runs every second (refreshInterval: 1), and Claude Code also re-runs it after events such as each reply or a usage window resetting. The countdown and animation change every second; the usage and cost numbers change only when Claude Code receives new data.

What happens when data is unavailable? That segment is left out. The script never fills in or estimates a value.

How do I change the colours or bars? Edit ~/.claude/statusline-command.sh: BAR_WIDTH, the level() thresholds and colours, and the ■ character in bar(). See Configure and customize.

How do I turn it off? Run /statusline remove it, or delete the statusLine entry from ~/.claude/settings.json (see Uninstall and recovery). Claude Code goes back to its default bottom bar.

Wrap-up

• Claude Code sends the data; a short bash script decides how it looks.

• refreshInterval: 1 keeps the countdown and animation live, while usage numbers update with each response.

• Pick characters that line up with your text, keep numbers fixed-width, and colour by meaning.

The full script is inside the installer, so you can read it before running anything. The official status line documentation lists every field Claude Code sends if you want to add your own segments. More posts are on my blog.

Originally published on siddarammetri.in.

Everything here is copy-and-paste. If you'd rather hand the whole job to an AI agent, there's a Claude Code shortcut just below.

Shortcut: let Claude Code do it for you

Use Claude Code? Open the original post and click Copy Claude Code prompt. Paste it into Claude Code with your folder link, and it runs every step below for you: it installs rclone, checks the folder, downloads it, verifies every file and unzips it, with a progress update every minute.

Not using Claude Code? Follow the steps below by hand.

Why not just click Download?

When you download a folder from the Drive website, Google first re-packs it into zip files of about 2 GB each. With a folder of zips you end up with zips inside zips. Worse, if your connection drops at 87%, that part starts again from zero, and there's no easy way to check that everything arrived intact.

rclone talks to the Drive API directly:

• File by file. You get the same files that are on Drive, with no re-zipping.

• Resumable. Run the same command again and it skips everything already downloaded.

• Verifiable. rclone check compares every file with Drive after the download.

• Parallel. It downloads several files at once. I averaged about 33 MB/s.

What you need

• A Mac with Homebrew. Linux and Windows work too; only the install command differs.

• Access to the Drive folder in your browser.

• Enough free disk space, roughly 2–3× the folder size if you'll unzip it. Check with:

df -h ~

Step 1: Install rclone

brew install rclone
rclone version

It's an 86 MB install, and that's all you need locally.

Step 2: Create your own Google OAuth client (recommended)

rclone has a built-in Google login that works out of the box. Everyone uses it, though, so Google often rate-limits it, which shows up as 403 rateLimitExceeded errors and slow speeds. Your own client avoids that. It's free, takes about 10 minutes, and you only do it once.

Sign in with the Google account that can see the folder, then follow these links in order:

1. Create a project: console.cloud.google.com/projectcreate. Name it something like rclone-download, click Create, and make sure it's selected in the top bar.

2. Enable the Google Drive API: console.cloud.google.com/apis/library/drive.googleapis.com, then click Enable.

3. Set up the consent screen: console.cloud.google.com/auth/overview, then Get started. Enter an app name (rclone) and your email.

   • On a company Google Workspace account, choose Internal. That's the simplest option.

   • On a personal account, choose External, then add your own email as a test user under Audience.

4. Create the client: console.cloud.google.com/auth/clients/create. Set the type to Desktop app and the name to rclone, then click Create. Copy the Client ID and Client secret.

If your company blocks creating Google Cloud projects, skip this step and leave the client ID and secret blank in step 3. rclone's built-in login still works, just more slowly.

Step 3: Connect rclone to Google Drive

A single command creates the connection (rclone calls it a remote) and opens your browser to sign in:

rclone config create gdrive drive \
  client_id=YOUR_CLIENT_ID.apps.googleusercontent.com \
  client_secret=YOUR_CLIENT_SECRET \
  scope=drive.readonly

Sign in, then click Allow. If Google warns that it "hasn't verified this app", click Continue. It's your own app.

Use scope=drive.readonly if you only need to download. rclone then can't change or delete anything in your Drive, even by accident. Use scope=drive only if you also plan to upload.

Prefer menus? Run rclone config, choose n for a new remote, name it gdrive, pick drive, paste the ID and secret, and accept the defaults.

Step 4: Look before you download

Take the folder ID from the Drive link, which is the part after /folders/:

https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz012345
                                       └──────────── folder ID ────────────┘

Then check what's inside without downloading anything:

FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz012345

rclone size gdrive: --drive-root-folder-id $FOLDER_ID   # file count + total size
rclone lsf  gdrive: --drive-root-folder-id $FOLDER_ID   # top-level contents

This step paid off. A second link I had been sent contained the first folder as a subfolder, with the same Drive ID. Spotting that here saved downloading the same 21 GB twice.

Step 5: Download

mkdir -p ~/Downloads/drive-data

caffeinate -i rclone copy gdrive: ~/Downloads/drive-data \
  --drive-root-folder-id $FOLDER_ID \
  --transfers 4 -P

If it stops partway because of Wi-Fi, sleep or a closed lid, run exactly the same command again. Finished files are skipped.

To keep a log file and run it in the background instead, swap -P for:

--stats 30s --stats-one-line --log-file ~/Downloads/drive-data.log --log-level INFO

Step 6: Verify every file

rclone check gdrive: ~/Downloads/drive-data \
  --drive-root-folder-id $FOLDER_ID --one-way

You want to see 0 differences found. This compares sizes and checksums with Drive. It doesn't download anything again.

Step 7: Unzip without overwriting anything

If the folder is full of zips and some of those projects already exist on your laptop, don't unzip straight over them. My rule was simple: never overwrite. If a folder already exists, the copy from Drive gets a -backup suffix instead.

#!/bin/bash
# Unzip every zip in SRC into DEST. Never overwrites: clashes become name-backup, name-backup-2, ...
SRC=~/Downloads/drive-data
DEST=~/Documents/Restored
mkdir -p "$DEST"

free_path() {           # first unused path: name, name-backup, name-backup-2, ...
  local p="$1/$2" i=2
  [ -e "$p" ] || { echo "$p"; return; }
  p="$1/$2-backup"
  while [ -e "$p" ]; do p="$1/$2-backup-$i"; i=$((i+1)); done
  echo "$p"
}

for zip in "$SRC"/*.zip; do
  tmp=$(mktemp -d)
  unzip -q "$zip" -x '__MACOSX/*' -d "$tmp" || ditto -x -k "$zip" "$tmp"
  for item in "$tmp"/*; do
    target=$(free_path "$DEST" "$(basename "$item")")
    mv "$item" "$target"
    echo "$(basename "$zip") -> $target" >> "$DEST/_restore-log.txt"
  done
  rmdir "$tmp"
done

Save it as restore.sh, set SRC and DEST, and run bash restore.sh. Keep the zips until you've opened a few projects and confirmed they look right. Then delete them to get the space back.

Restored a JavaScript project? Backups almost never include node_modules, so the first npm run dev fails with next: command not found. Run npm install (or bun install) once in each project.

Troubleshooting

Clean up when you're done

Once the download is finished, remove access you no longer need:

1. Delete the Cloud project: console.cloud.google.com/iam-admin/settings, select the project, then Shut down. This removes the client ID and secret too. Google keeps the project for 30 days, then deletes it.

2. Revoke rclone's access: myaccount.google.com/connections, then your app, then Delete all connections.

3. Delete the saved login on your Mac:

rclone config delete gdrive

rclone itself can stay installed. It's small, and next time you only need step 3 again.

A note for work accounts

On a company Google Workspace account, all of this is visible to your admins if they look. The Cloud project, the app you authorised and each file download are logged against your account, with the time and your IP address. Your Mac's name and the folder you saved to are not recorded. Downloading your own work files to your work laptop is ordinary activity, but if your company has rules about third-party apps, check them first.

Wrap-up

• rclone + your own OAuth client turns a fragile 21 GB browser download into one reliable command.

• Look first (rclone size, rclone lsf), verify after (rclone check), and never overwrite when you unzip.

• Clean up the access when you're done.

Or skip the typing: click Copy Claude Code prompt on the original post, paste it into Claude Code with your link, and watch it work through each step.

Originally published on siddarammetri.in.