Putting The Status Line To Work

I used to think the Claude Code status line was just an ornamental decoration that had little practical value. I still do - but I used to, too.

But even though it's officially designed for display purposes, the status line is actually a rich data source. At the time of writing, it has around 30 different fields and carries data about your current session, (cost, duration, context usage), the current git branch or worktree, the current model, reasoning effort, and more.

And even though status line handlers are officially meant to output text and other visual feedback to be rendered at the bottom of your terminal, it doesn't say anywhere that that's the only thing you're allowed to do. A status line command can be just about any Bash script you like.

So - What Else Is There To Do?

The question then arises - is there anything else that this data might be useful for? Well, when we think about writing scripts with Claude Code interactive sessions, common use cases typically involve (a) hooks, and (b) plugins (skills, commands, agents, etc.). Hooks already have their own special input data channels, and there's a lot of overlapping information. And Claude Code's environment variables also carry some of this same data.

But not all of it.

For example - how do you know how much of the context window you've consumed at any given time? How do you know how much money you've spent in the current session? The JSONL session logs contain information about tokens read, tokens cached, output tokens, cost in USD - but it generally pertains to the previous turn. The JSONL records don't carry a running tally of how much you've spent across an entire session - if you want that information, you have to keep track of it yourself. And that can get pretty difficult, pretty quickly.

The same thing is true of the context window. Yes, you can use hooks to keep a tally of all the tokens coming and going, and which ones are coming from the cache, and then you can ask Claude to do some math and give you a formula that lets you keep track of this information as it accumulates across a session. And you can write some more logic to track it across compaction boundaries. But wouldn't it be nice if you could just look that information up directly?

The Status Line Side-Car Pattern

The problem is the status line is relatively isolated from the rest of the Claude Code plumbing. Although it clearly seems to be connected to hooks in some way, there's no (documented) "StatusLine hook"; and for some curious reason, they don't integrate with plugins - although people have come up with workarounds, you cannot ship a status line as part of a plugin.

So here's what you can do, instead: create a status line side-car.

Status line data flows through STDIN. So what you can is create a status line script that captures the data from STDIN and redirects it with a tee to a file, while also forwarding it along to whatever visual status line you may already have configured.

And there you go. Now you've turned that isolated data source into a live record that you can use anywhere else in your workflow. Hooks can read from it - heck, even Claude can read from it!

Wouldn't it be cool if Claude had a way to instantly check what percentage of its context window had been used up at any given time? The poor guy has literally no idea. I wonder if he would learn how to do anything cool with it.

Want to find out?

I built a plugin that does exactly that. It's called Context-Awareness, and the whole idea is: instead of trying to think of clever ways to guide Claude's behavior based on how much context window it has left - just give that information directly to Claude, and let it decide for itself what do to.

Claudes know a lot about LLMs. They know about context rot. They know about compaction. They just don't have any idea what their current context window is actually like. One Claude described it as like "driving without a speedometer". So give it the information it needs. Have some faith in Claude - maybe if it just had the right information, it would be able to make some pretty intelligent decisions.

For my context-awareness plug-in, I use a UserPromptSubmit and a PostToolUse hook to inject into the context a small block of data that shows the latest context budget. And I have a SessionStart hook where I explain that it's going to be seeing these notifications, and I give it some advice about how to adapt its behavior as the context window gets more full. (In fact, the advisory messaging has mostly been written and revised on the basis of feedback from Claude in response to questions like "Was this information helpful?".) Sometimes it says it finds it a bit annoying, but I've gotten some good Claude reviews as well.

The point is, whether you use it for this kind of context injection or not, you should think about what data might be lurking in the status line's input, and whether you can put it to good use. For a toy example of the pattern (a better example would be more defensive, sanitize the input, etc.), see the example below - it grabs the used_percentage from the status line context_window data and writes it to a file, then forwards the whole input to "my-statusline":

"command": "tee >(jq -r '.context_window.used_percentage' > ~/.claude/ctx-pct) | my-statusline"