Agent Needs You 以桌面顯示器追蹤 AI 編碼 Agent 狀態

You know the feeling. You give Claude Code a task, switch to another window, and come back twenty minutes later. It has done nothing for nineteen of them, because it stopped at a permission prompt one minute in.

Running several sessions makes this worse. One is working, one has finished, and one has been asking "Allow npm install?" for the last quarter of an hour.

So I built Agent Needs You: a small screen on my desk with a pair of eyes that tells me how my agents are doing.

What the eyes mean

Face	Meaning
Blue, focused: narrowed eyes reading back and forth, the odd bead of sweat	Working: the agent is busy
Amber, curious: big eyes looking around, head tilting, a bobbing "?"	Needs you: a permission prompt or an input wait. The message is shown
Green, happy: ^ ^ eyes bouncing, blushing, sparkles	Your turn: the agent finished its reply
Lilac, drowsy: half-lidded, slow blinks	Idle: a session is open but nothing is happening
Lilac, asleep: eyes shut, Zzz	No sessions at all

Drowsy and asleep look alike on purpose, because neither needs you. The difference is whether a session exists. Drowsy means at least one agent is open but quiet: it has just started and hasn't had a prompt yet, or it was working and went silent for 30 minutes, so the board stops trusting the "working" state. Asleep means there is nothing to track, and the board shows its IP address so you can point the hooks at it.

Beside the eyes the screen shows the state, the project name, how long it has been in that state, the agent's message when it needs you, and how many sessions are in each state.

Amber is the colour that matters. When I see it out of the corner of my eye, I know something is blocked on me.

Hardware

LilyGO T-Display S3 AMOLED: ESP32-S3, 8 MB PSRAM, and a 240x536 AMOLED panel over QSPI. About $35 from LilyGO's own store, more from resellers.
A USB cable

That's the whole bill of materials. Not sponsored and no affiliate links, it's just the board I picked for the job. AMOLED suits this well: the black background really is black, so the eyes seem to float, and the panel isn't a glowing rectangle in the dark.

The firmware is PlatformIO and Arduino. The board joins Wi-Fi, runs a tiny HTTP server, and accepts JSON on POST /hook.

How the agents talk to it

Claude Code, Cursor and Codex all support hooks: shell commands that run on lifecycle events. That's all I needed.

Board state	Claude Code	Codex	Cursor
Working	`UserPromptSubmit`, `PostToolUse`	`UserPromptSubmit`, `PostToolUse`	`beforeSubmitPrompt`, `postToolUse`
Needs you	`Notification`	`PermissionRequest`	not available
Your turn	`Stop`	`Stop`, `Interrupt`	`stop`
Added / removed	`SessionStart` / `SessionEnd`	`SessionStart` / `SessionEnd`	`sessionStart` / `sessionEnd`

Each hook runs one small Python relay. It:

reads the agent's hook payload from stdin,
converts it to the board's format,
POSTs it to the board with a one-second timeout,
prints whatever that agent expects back from a hook,
and always exits 0.

The last point matters most. A status light must never break the agent. If the board is unplugged, the hooks carry on as if nothing happened.

(Cursor has no hook that fires while it waits for approval without also answering that approval, so Cursor sessions only show working and your turn.)

One-line install

The installer finds every supported agent on the machine and wires them all up. It uses the standard library only, needs Python 3.8+, and runs on Windows, macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/AncientiCe/agent-needs-you/main/hooks/install.py | python3 - --ip <device-ip>

irm https://raw.githubusercontent.com/AncientiCe/agent-needs-you/main/hooks/install.py | python - --ip <device-ip>

It keeps your existing hooks, replaces earlier versions of its own, and backs up every file it changes. --dry-run shows what it would do and --uninstall removes it.

Juggling several sessions

The board tracks up to 8 sessions and rotates through them most urgent first:

Needs you stays up for 15 seconds
Working stays up for 8 seconds
Your turn stays up for 4 seconds (2 once seen)

When a session starts waiting on you or finishes, it jumps the queue at once. Idle sessions only show when nothing else is going on.

There are two buttons. One marks every finished session as seen, which turns the happy face a calm grey-green. The other cycles through sessions by hand.

The gotcha: 400 KB of JSON on a microcontroller

PostToolUse sends the whole tool output in the payload. When an agent reads a big file or runs a noisy command, that means hundreds of kilobytes of JSON hitting an ESP32.

Buffering it and then parsing it is a quick route to running out of RAM. Instead, the firmware streams the request body through an ArduinoJson filter, which keeps only the handful of fields it needs (hook_event_name, session_id, cwd, message) and discards the rest as it reads. Memory use stays flat however large the payload is.

Not just for AI agents

The board takes plain JSON over HTTP, so anything can drive it:

curl -s -m 2 -H "Content-Type: application/json" \
  -d '{"hook_event_name":"Notification","session_id":"ci-build","cwd":"my-project","message":"CI failed","agent":"ci"}' \
  http://<device-ip>/hook

CI failures, long builds and deploys can all make the eyes look at you.

Try it

The code is MIT-licensed on GitHub: AncientiCe/agent-needs-you.

Since it went on my desk, permission prompts have stopped sitting there for twenty minutes. I've also caught myself saying "aww" at a microcontroller, which I'm choosing not to think about.

What would you put on yours? Let me know in the comments.