How to Show Agent State Outside the Terminal

The Status Light ($45) is three domed lenses on a matte black desk unit, red at the top, amber in the middle, green at the bottom. It knows nothing about Claude Code, Codex CLI, Cursor or anything else, and it never will. It lights up because something you wrote told it to. This article is about that something: the four ways to get a state out of a terminal and onto an object, and what each one can honestly see.

What are the four ways?

• Wrap the command. A shell function that sets the light, runs the agent, then sets it again based on the exit code. Works with every tool that exists, because it requires nothing from the tool. Gets you running, finished and failed.
• Use a hook, if the tool has one. Claude Code will run a command you nominate at defined points, including session start and session stop, and there is a notification hook too. Other tools may have an equivalent under another name. If yours does not, use the wrapper.
• Piggyback a status line. Where a tool re-renders a status line by running a command, that command can change a light on its way past. It works, but it is a display refresh, so it is debounced and can be cancelled mid-run.
• Watch the output. Pipe the session through something that matches a pattern, or tail a log the tool writes. The most portable and by far the most fragile: the day a prompt is reworded, your rule stops matching and you do not find out.

Which of these can catch waiting on you?

This is the state worth paying for and the hardest to get. A wrapper cannot see it at all, because from the outside a run that is waiting looks exactly like a run that is working. Watching output can catch it, badly, by matching on the wording of a prompt. A hook can catch it properly, but only if your tool emits something at the moment it pauses. Some do, some do not, and no piece of hardware can invent an event that was never sent.

So check before you spend anything. If your tool gives you nothing at that moment, you own a two-colour light, and a two-colour light is still useful. Just buy it knowing that.

What should the colours mean?

Our suggestion is red for running, amber for waiting on your input, green for finished, which reads down the unit in the order the lenses sit. You can assign any mapping you want. The only rule that matters is that you settle it once and then leave it alone, because the entire value of an ambient signal is that you stop interpreting it and start just knowing.

Add a reset. The first time a run dies badly the light will stay red and you will spend a day quietly distrusting it. One line at the start of a shell session fixes that permanently.

What if I run several agents at once?

Then one lamp has to average them, and averaging is a decision. The usual answer is worst state wins: if any agent is waiting on you, the light goes amber, because that is the one costing you time. If you would rather see them separately, the Desk Terminal ($79) is a miniature computer with a small colour screen and can show words rather than a colour, and the Agent Pet ($45) shows states as expressions on a square face. Both have exactly the same requirement: you supply the signal.

How much work is this really?

A short script and a shell function, written once, then edited twice over the following week when you find the cases you missed. If that sounds like a fair trade for never alt-tabbing to check on a run again, it is a good buy. If you are not going to write it, do not buy the light, and we would rather say so here than have you discover it on your desk.

If you are still working out whether you want an ambient indicator at all, start with how do I know when my AI agent is done.