Must-have modification to Claude Code statusline for effective context engineering.

README.md

Claude Code Context Window Monitor

Two-file setup that surfaces Claude Code's context window usage as a status line in your terminal and writes it to /tmp so the agent itself can read it.

Files

File	Location
~/.claude/settings.json	Claude Code settings — enables the status line
~/.claude/statusline-command.sh	Script that parses and renders context usage

What it does

For you: The status line shows context percentage used, remaining, current model, and working directory — color-coded by urgency (green → yellow → red).

For Claude: The script writes current context usage to /tmp/claude-context-percentage.txt on every update. This means the agent can read its own context state and act on it.

Why this matters

Claude Code's default autocompaction threshold kicks in late — by that point you're often in the "stupid zone": context rot has already degraded response quality, even if the session hasn't hit the hard limit.

This is particularly useful for autonomous runs, e.g. software implementation from specifications.

By giving the agent visibility into its own context usage, you can:

• Instruct Claude (via CLAUDE.md or system prompt) to autocompact earlier than the default threshold
• Have Claude warn you proactively before quality degrades
• Have Claude suggest starting a new session at a sensible cutoff
• Have Claude adjust verbosity as the window fills, conserving tokens

Setup

1. Copy statusline-command.sh to ~/.claude/statusline-command.sh
2. Make it executable: chmod +x ~/.claude/statusline-command.sh
3. Merge the statusLine block into your ~/.claude/settings.json
4. Update the path in settings.json if your username isn't captivus

Usage with CLAUDE.md

Add something like this to your CLAUDE.md:

## Context Management

Check /tmp/claude-context-percentage.txt to monitor context usage.
- Above 50%: be concise, avoid unnecessary elaboration
- Above 65%: suggest a compact or new session if the task allows
- Above 80%: strongly recommend compacting before continuing

Dependencies

• jq — for parsing the JSON status input
• Claude Code with status line support (recent versions)

settings.json

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

statusline-command.sh

#!/usr/bin/env bash
# Claude Code status line — context window usage monitor
# Displays context percentage and writes to /tmp so it can be read from within conversations

input=$(cat)

used=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
remaining=$(echo "$input" | jq -r '.context_window.remaining_percentage // empty')
model=$(echo "$input" | jq -r '.model.display_name // empty')
cwd=$(echo "$input" | jq -r '.workspace.current_dir // empty')

dir=$(basename "$cwd")

if [ -n "$used" ]; then
  used_int=$(printf '%.0f' "$used")
  remaining_int=$(printf '%.0f' "$remaining")

  # Write to file so Claude can read it from within the conversation
  echo "$used_int" > /tmp/claude-context-percentage.txt

  # Choose color based on usage level
  if [ "$used_int" -ge 85 ]; then
    color="\033[1;31m"   # bold red — critical
  elif [ "$used_int" -ge 65 ]; then
    color="\033[1;33m"   # bold yellow — warning
  else
    color="\033[1;32m"   # bold green — healthy
  fi
  reset="\033[0m"

  printf "${color}ctx: %d%% used (%d%% remaining)${reset}  %s  %s" \
    "$used_int" "$remaining_int" "$model" "$dir"
else
  printf "%s  %s" "$model" "$dir"
fi