A Claude Code statusline is a thin strip of terminal real estate that can save you from mid-task context compaction — if you make it show the right number. When the tool decides to compact on its own, it silently replaces the conversation summary, often discarding details you still need. By colouring the context-remaining percentage directly in the statusline, you get a visual cue to run /compact yourself, before the surprise.

What a Claude Code statusline can show you

The configured command receives full session state as JSON on stdin after every assistant message. The first line it prints becomes the statusline. Claude Code respects ANSI escape codes, so colour and formatting are yours to control.

Fields piped in include:

• model.display_name
• workspace.current_dir
• context_window.remaining_percentage
• cost.total_cost_usd
• session.git_branch (if tracked)
• session.lines_added / session.lines_removed
• session.rate_limit_remaining (a percentage of your weekly quota)

A smart statusline grabs only the signals that change behaviour: context left, session cost, active branch, and perhaps the rate-limit indicator when it’s actually worth worrying about.

Set up a Claude Code statusline that warns before auto-compact

Start with a single-file Node script — no dependencies, ~80 lines. The version we ship at techpotions’ claude-code-statusline colours the context segment amber below 35 % and red below 15 %, making it impossible to miss that you’re about to hit auto-compact territory.

1. Save the script

Drop statusline.js into ~/.claude/:

#!/usr/bin/env node
// statusline.js — minimal context-warning statusline

const PARTS = [];

/* helpers – ANSI colours */
const bold   = (s) => `\x1b[1m${s}\x1b[22m`;
const yellow = (s) => `\x1b[33m${s}\x1b[39m`;
const red    = (s) => `\x1b[31m${s}\x1b[39m`;

let data = '';
process.stdin.on('data', chunk => { data += chunk; });
process.stdin.on('end', () => {
  const s = JSON.parse(data);
  const pct = s.context_window?.remaining_percentage ?? 100;

  // model & directory
  PARTS.push(bold(s.model?.display_name ?? '?'));
  PARTS.push(s.workspace?.current_dir ?? '');

  // git branch
  if (s.session?.git_branch) PARTS.push(s.session.git_branch);

  // context – coloured
  let contextStr = `ctx ${Math.round(pct)}%`;
  if (pct < 15) contextStr = red(contextStr);
  else if (pct < 35) contextStr = yellow(contextStr);
  PARTS.push(contextStr);

  // session cost
  const cost = s.cost?.total_cost_usd ?? 0;
  PARTS.push(`$${cost.toFixed(2)}`);

  // rate limit – only when above 70 % (5 % usage is noise)
  const rate = s.session?.rate_limit_remaining;
  if (rate != null && rate >= 70) {
    PARTS.push(`limit ${Math.round(rate)}%`);
  }

  process.stdout.write(PARTS.join(' \u2502 ') + '\n');
});

2. Wire it into ~/.claude/settings.json

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

Windows users: the tilde doesn’t expand inside Claude Code’s config — use the full path, e.g. node C:/Users/you/.claude/statusline.js.

How the context-warning threshold works

The script reads context_window.remaining_percentage — the exact number Claude Code uses to decide when to auto-compact. By wrapping it in colours you get an at-a-glance fuel gauge:

You never need to guess. When the segment turns red, you either wrap the task or invoke /compact on your own terms. That keeps your summary intact and your reasoning chain unbroken.

Customising the statusline for your workflow

Because Claude Code simply runs a command, you can extend the script with anything that helps your flow:

• Show changed files to spot unintended edits.
• Add a sleep-based dot timer to see how long the agent has been running.
• Run a git status check and flag a dirty tree in the statusline.
• Track API cost and compare it against your LLM API pricing calculator to catch runaway sessions.

If you want to hook into the message lifecycle itself (trigger scripts before/after each assistant turn), Claude Code hooks offer that extra layer. Our Claude Code hooks product provides pre-built recipes that fire on every response or file write, perfect for linting or clearing cache at the right time.

FAQ

Can I customise the Claude Code statusline without a slow third-party tool?

Yes — Claude Code lets you replace the default statusline with any command. Set statusLine.type to "command" and supply the script path, then the first line printed becomes your statusline (ANSI codes respected).

How do I make the statusline warn me before an automatic compaction?

Set a script that reads context_window.remaining_percentage from the session JSON on stdin, and colour it amber under 35 % and red under 15 %. That visual nudge tells you to issue /compact before Claude Code does it automatically mid-task.

Where do I configure a custom statusline in Claude Code?

The statusLine field sits in ~/.claude/settings.json. On Windows the tilde does not expand, so use the full path like C:/Users/you/.claude/statusline.js.