claude-code-context-meter

Status: Archived / No longer needed. When this project was built, Claude Code had no built-in context usage indicator, so I wrote this as a way to learn how to share features through a natural-language prompt spec rather than shipping code. The official Claude Code desktop UI now displays context usage natively, making this hook redundant. The repo is kept as a reference for the prompt-driven installation pattern.

A prompt-driven context window usage indicator for Claude Code. Shows how much of the context window has been consumed at the end of every response — so you know when to /compact or start a new session before hitting the wall.

What It Looks Like

Every Claude response ends with a usage line:

---

**ctx 42%**

When usage gets high, actionable guidance appears automatically:

---

**ctx 78%** · Decision point: /compact to continue · new session for clean context

---

**ctx 93%** · Urgent: /compact now or save progress and start a new session

Three tiers (mutually exclusive):

Usage	Behavior
< 75%	Percentage only
75–89%	Decision point reminder
≥ 90%	Urgent action prompt

How It Works

This project is a specification document, not a code package. You feed the spec to Claude Code, and it autonomously installs the feature:

1. A UserPromptSubmit hook fires every time you send a message
2. The hook reads the session transcript to get token usage data
3. It injects a <system-reminder> that tells Claude to append the usage line
4. Claude includes the **ctx N%** line at the end of its response

The hook calculates usage from input_tokens + cache_read_input_tokens + cache_creation_input_tokens, with the context window size determined by the model in use (1M for extended context models, 200K for standard).

Installation

1. Open a Claude Code session
2. Paste the contents of ctx-usage-prompt-spec.md as your message
3. Claude will handle the rest — creating the hook script, registering it in settings.json, and verifying the installation

That's it. The **ctx N%** line will appear starting from your next message.

Uninstallation

See the Uninstallation section in the spec document.

What's in This Repo

File	Description
ctx-usage-prompt-spec.md	The full specification — feed this to Claude Code to install
README.md	You are here
LICENSE	MIT

There is no implementation code in this repo. The spec is designed to be language-agnostic — Claude chooses the implementation language based on what's available on your system.

Why a Prompt Spec?

Claude Code can install features from a natural-language specification. This project explores that pattern: instead of shipping code that users pip install or npm install, you ship a spec that Claude implements on the spot, tailored to the user's environment.

Requirements

• Claude Code (desktop app, web app, or CLI)
• A model with tool use capability (Claude Opus, Sonnet, or Haiku)

License

MIT