What a Claude Code statusline actually is
A statusline is a single line pinned to the bottom of Claude Code that updates as you work, similar to the status bar in an editor like VS Code. Instead of guessing which branch you are on or how much context is left in a long session, the statusline shows it to you continuously, without a command.
Claude Code lets you point it at your own script to generate that line. The script receives session information as input - things like the current model, the working directory, and cost so far - and returns plain text or ANSI-colored text that gets rendered at the bottom of the screen.
Why I bothered setting one up
The failure mode a statusline fixes is a specific one: you are three hours into a long build, the session has gone through a lot of back-and-forth, and you have quietly lost track of two things - how close you are to running out of context, and which git branch this is even happening on. Neither is catastrophic on its own. Together, on a client project, they cost real time when you catch them late.
- Context remaining - so I compact or wrap up before I hit a wall mid-task instead of after.
- Git branch - so I never make a client-project mistake because I forgot which worktree I was in.
- Running cost - so a long unattended session does not surprise me at the end of the day.
How to set up a custom statusline
- Write a small script (shell, Node, or Python all work) that reads the session JSON Claude Code passes it and prints the line you want.
- Point Claude Code's settings at that script as the statusline command.
- Keep the script fast - it reruns on an interval, so anything slow becomes a visible lag at the bottom of your terminal.
- Test it by running a real session and watching the line update as context and cost change, not just by eyeballing the script's output once.
What I actually put in mine
My statusline shows three things left to right: the git branch, a percentage for context remaining, and the running dollar cost of the session. I color the context percentage so it shifts as it drops, which is a small thing that turns 'check the context' from a decision into something I just see out of the corner of my eye.
Statusline fields worth adding, and why
| Field | Why it earns a spot |
|---|---|
| Git branch | Stops the mistake of running the wrong task against the wrong branch |
| Context remaining | Lets you compact or wrap up on your terms, not when Claude forces it |
| Session cost | Keeps a long unattended run from being a surprise number at the end |
| Current model | Useful if you switch models mid-project and want a constant reminder which one is active |
Set yours up this week
Pick the one thing you check manually most often in a session - branch, context, or cost - and write the smallest possible script that prints it. Wire that in as your statusline before you add anything else. Once you feel the difference of not having to ask, add the rest.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is a statusline in Claude Code?
It is a single customizable line pinned to the bottom of the Claude Code interface that updates continuously, showing whatever information your script returns - typically things like git branch, context remaining, active model, or session cost.
Do I need to code to set up a custom statusline?
You need a small script - shell, Node, or Python all work - that reads the session data Claude Code passes it and prints a line back. It does not need to be sophisticated; a few lines that check git and format a percentage is enough to start.
Will a statusline slow Claude Code down?
Only if the script itself is slow, since it reruns on an interval. Keep it to fast, cheap operations - reading local git state or session JSON - and it stays invisible.
What should my statusline show?
Whatever you currently check manually. Most builders start with git branch, context remaining, and cost, because those are the three things that quietly cause mistakes or surprises on a long session.
Last reviewed by Duncan Rogoff on August 6, 2026
