Skip to content
techpotions
techpotions

A statusline worth glancing at.

Model, directory, git branch, context remaining with amber and red thresholds, session cost, lines touched. One dependency-free Node file and a four-line settings entry. The context number alone will change how you run long sessions.

Download free1 script · zero dependencies · MIT
What you get

One line, the right numbers.

⏺ Opus · my-app · ⎇ feat/checkout · ctx 62% · $1.84 · +156/-23

The segments, left to right: current model, project directory, git branch, context remaining (teal, then amber under 35%, red under 15%), session cost so far, and lines added/removed. A weekly rate-limit segment appears only when you are past 70% of a Pro/Max window, because before that it is noise.

How to

Install in ninety seconds.

Drop statusline.js anywhere (convention: ~/.claude/), then add the entry to your settings:

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/statusline.js"
  }
}

Restart Claude Code, and the line appears under the input box. On Windows use the full path (node C:/Users/you/.claude/statusline.js). Node is guaranteed present because Claude Code itself runs on it.

Reference

How the statusline contract works.

After every assistant message, Claude Code executes your command and pipes the session state as one JSON object on stdin. The first line your script prints becomes the statusline; ANSI colors are respected.

// What Claude Code pipes to your script after every message:
{
  "model": { "display_name": "Opus" },
  "workspace": { "current_dir": "/repo" },
  "context_window": {
    "used_percentage": 38,
    "remaining_percentage": 62
  },
  "cost": {
    "total_cost_usd": 1.84,
    "total_lines_added": 156,
    "total_lines_removed": 23
  }
  // ...plus session ids, vim mode, rate limits, open PR, and more
}

That contract means a statusline can be anything: a script that shows your ticket number, your deploy status, your test pass rate. Ours sticks to the numbers that change decisions mid-session, and the README documents the full stdin schema for when you want more.

Download free1 script · zero dependencies · MIT
FAQ

Common questions.

  • 01How do I set up a statusline in Claude Code?

    Add a statusLine entry to ~/.claude/settings.json with type "command" and the command to run, e.g. node ~/.claude/statusline.js. Claude Code runs it after every assistant message, pipes session state as JSON on stdin, and displays the first line your script prints. This pack is exactly that script plus the config snippet.

  • 02What information can the statusline show?

    The stdin JSON carries the model name, current directory, project directory, context window usage (used and remaining percentages), session cost in USD, lines added and removed, API duration, vim mode, the open PR if any, and rate-limit usage on Pro/Max plans. Our script shows the useful subset and is trivially editable: the segments are consecutive parts.push() calls.

  • 03Why show context remaining rather than tokens used?

    Because remaining percentage is the number you act on. Under 35% it is time to finish the current task cleanly; under 15% you want /compact before auto-compaction picks its own moment. The script colors it amber and red at exactly those thresholds.

  • 04Does it slow anything down?

    No. The script is dependency-free Node that parses one JSON object and prints one line; it runs in a few milliseconds after each message, off the critical path. The only subprocess is a single fast git call for the branch name, capped with a timeout.

  • 05Can I use colors and custom segments?

    Yes. ANSI escape codes work, which is how the context percentage changes color. Add any segment you like: read a field from the stdin JSON (the full schema is documented in the README) and push another string. It is about 80 lines of plain code, made to be edited.

More free Claude Code downloads

Like tools that respect your attention?

We sweat this kind of detail in everything we ship: products, agent setups, client builds. If your team is adopting Claude Code and wants the whole environment tuned like this, that is what we do. techpotions is a small studio; you talk to the people who build.

Start a project