Putting the Claude Code Status Line on a Desk Lamp

The Status Light ($45) is a matte black desk unit with three domed lenses, red at the top, amber in the middle, green at the bottom. Before anything else: it does not know what Claude Code is doing. It has no connection to Claude Code, no plugin and nothing watching your terminal. It changes colour because a command you configured told it to. This is about which command, and the status line is a tempting but partly wrong answer.

What is the Claude Code status line?

It is the line Claude Code draws at the bottom of the terminal, and you can replace it with your own. In your settings file you set statusLine to a type of command plus the path to a script. Claude Code then runs that script and shows the first line the script prints. The script is handed a JSON object on standard input describing the session as it currently stands: the working directory, the model's display name, the session identifier, cost and context figures. There is also a /statusline command inside Claude Code that will write a starter script for you if you describe what you want in it.

Can that same command change a lamp?

Yes, because it is a command, and a command can do anything a command can do. Your script can call whatever utility your light came with, then print its line as normal. Claude Code neither knows nor cares that a lamp changed while the script ran. No integration exists beyond the one you write.

The caveats are real, though. The status line is a display, not an event stream. It is run at session start and resume, and again when things change, such as a new assistant message or a mode toggle. Updates are debounced so that rapid changes are batched, and a script still running when a newer update arrives can be cancelled part way. So keep the script fast, make it safe to run twice in a row, and do not rely on it to catch a precise instant.

Which states can it honestly drive?

The status line tells you what is true now, not what just happened, and a lamp mostly wants transitions. That is what hooks are for. Claude Code can run a command at defined moments, including when a session starts and when it stops, and those two are exactly the pair a light needs. Point the start at red and the stop at green and you are done, without touching the status line at all.

The middle colour is the harder one. Amber should mean the agent has paused and wants a decision from you, and whether you can catch that moment depends on whether anything fires at it. There is a notification hook, which is the closest thing to the agent asking for you, so check what it actually fires on in your version before you wire amber to it. If nothing fires, be honest with yourself and run a two-colour light.

Our suggested convention is red for running, amber for waiting on you and green for finished, which matches the order of the lenses. Assign whatever mapping you like, then never change it, because the value of an ambient signal is that you read it without thinking.

Does this work on Windows?

The mechanism is identical, but the command has to be something your machine can run. On Windows that means a PowerShell script or a batch file with a Windows path, not a shell script. The trap is WSL: if Claude Code is running inside your Linux environment then your script runs there too, while the light is plugged into Windows, and the Linux side does not see USB devices unless you have deliberately attached them. Decide which side owns the light before you write anything.

What do I have to write?

Very little, and all of it once. A script that reads the JSON from standard input, works out which colour is right, runs the light's own command, then echoes the text you wanted in the terminal anyway. Add one line that resets the light when a shell starts, because the first time a run crashes you will leave it stuck on red and spend a while distrusting it.

For the same setup framed around the product rather than the config, see the agent status light for Claude Code.