# Agent Status Hardware: one light and one e-ink display for every agent session, driven by hooks

> Wire the hooks Claude Code, Codex and Hermes already have, plus a rules block for Grok Bot, to one small bridge on your machine. It turns agent events into one state for all sessions and drives a terminal, a USB busylight, a blink(1), an ESP32 LED, a 2.13 inch e-ink panel or a Home Assistant light. Waiting for you is a red blink nothing can cover, a session with no news turns amber, and the light never approves anything.

- URL: https://paperchasewebb.ai/bots/marketplace/items/agent-status-hardware-lights-and-e-ink-via-hooks/
- Type: Bot template
- Category: Vibe coding
- By: PaperChaseWebb
- Works with: Claude Code, Codex, Grok Bot, Hermes (named in the listing); Hooks for Claude Code, Codex and Hermes, a rules block for Grok Bot; tested against a simulated light, fake device tools, a mock Home Assistant and a virtual serial port, not on real hardware
- Price: $14 USD
- Difficulty: Intermediate
- Setup time: 30 min
- Time to result: A working terminal light in about ten minutes, a device in about half an hour
- Format: Markdown (.md) file, agent-status-hardware-lights-and-e-ink-via-hooks.md
- Version: 1.0, updated 2026-10-28
- License: Use on your own machines and on installs you do for clients and teams. Do not resell or republish the pack itself.

## What you end up with

You see at a glance when any agent session needs you, a crashed session stops looking busy, and flashing a board, opening the bridge to your network or using a Home Assistant token each wait for your written yes.

## What you get

- 19 sections in one .md file
- Hook files for Claude Code, Codex and Hermes, and a rules block for Grok Bot
- status_bridge.py: one state for all sessions, six states with waiting first, stale decay, a local read-only endpoint, standard library only
- Seven adapters: terminal, simulated light, e-ink frame, busylight-for-humans, blink(1), ESP32 serial and Home Assistant, each with plain notes on what was tested
- MicroPython firmware for an ESP32 LED and a Raspberry Pi script for a Waveshare 2.13 inch e-ink panel
- Owner approvals in approvals.csv for firmware flashing, network exposure and Home Assistant tokens
- status_check.py: fifteen read-only checks, with a fixture builder and the expected output
- Four test scripts: selftest, hooks, adapters and firmware
- Ten prompts and a failure table
- A look at ten status lights, displays and tools people are using, with sources

## Who it is for

People who run long or parallel agent sessions in other windows and want one honest signal for when an agent needs them, on a light or a display they control.

## Tools needed

- Claude Code, Codex or Hermes: runs the status hooks on its own events; the hooks write one metadata line and exit 0
- Grok Bot: has no hooks, so a rules block has it report working, waiting, done and error with one command on the same machine
- Python 3: runs the bridge, the adapters, the tests and the read-only checker; standard library only
- A light or a display (optional): a USB busylight, a blink(1), an ESP32 with LEDs, a Waveshare 2.13 inch e-ink panel or a Home Assistant light; a terminal window works with no hardware
- You need: Claude Code, Codex, Hermes or Grok Bot on the same machine as the bridge
- You need: Python 3.9 or newer
- You need: busylight-for-humans or blink1-tool for USB lights (optional)
- You need: MicroPython on an ESP32, or a Raspberry Pi with the Waveshare library (optional)

Cost to run: The pack is the only purchase. No hardware is included; a terminal window needs none.

## How it works

1. **Test the bridge.** Save status_bridge.py into ~/.agent-status with the example config, set owner to your name and run selftest. Expected: 16 ok, 0 failures, including a waiting session that stays red while another finishes.
2. **Test the check.** Save the scripts, run make_fixture.py and run status_check.py on the two fixture folders. Expected: 15 findings on seeded, 0 on fixed; exit 2 on a missing folder.
3. **Connect your harness.** Merge the hook file for Claude Code, Codex or Hermes, or paste the Grok Bot rules block, then start serve with the terminal adapter. Expected: A prompt turns the terminal light green, a permission prompt turns it red and blinking.
4. **Add a device.** Pick the adapter for your light or panel from section 8 and add it to the config. Record an approval first if it needs a flash, the network or a token. Expected: The device follows the terminal light, and status_check.py prints no findings.

## Sample prompt: Connect Claude Code (Claude Code)

```
Show me the hooks block you would merge into my ~/.claude/settings.json from hooks/claude-settings.json, as a diff against what is there now.
Do not write it until I say yes.
```

Prompt 2 of 10. Your settings file is yours to change.

## Sample prompt: Plan a flash (Grok Bot, Claude Code, Codex, Hermes)

```
Show me the sha256 of the firmware file and the approvals.csv row I would need to flash it to the port I name, then stop.
I will add the row and run the command myself.
```

Prompt 9 of 10. The agent never writes approvals.

## Free preview of agent-status-hardware-lights-and-e-ink-via-hooks.md

````markdown
# Agent Status Hardware: one light and one e-ink display for every agent session, driven by hooks

Version 1.0, 2026-10-28. By PaperChaseWebb. Works with Claude Code, Codex and Hermes through their hooks, and with Grok Bot through a rules block. Plain Markdown, hook files for each harness, a bridge script, firmware for an ESP32 light and a Raspberry Pi e-ink panel, and a read-only checker, all Python 3 with no outside packages for the bridge. Tested as described in section 12: everything ran on Linux with Python 3.13 against a simulated light, fake device tools, a mock Home Assistant and a virtual serial port. No real light, panel or board was connected for this release, and the hook files were not loaded inside the harnesses. Both are marked where they matter. No hardware is included.

You start an agent, switch to another window, and come back twenty minutes later to find it has been waiting for a yes since minute two. With two or three sessions open it gets worse: one finishes, you check that one, and the one that is blocked sits there. A status light fixes this, if it is honest. It has to tell you "needs you" louder than anything else, it has to stop claiming "working" when the agent has crashed, and it must never become a way to approve things without reading them.

This pack wires the hooks each harness already has to one small bridge on your machine. Every hook writes one line of metadata (agent, event, a hashed session id, the folder name) to a local log. The bridge r
````

## Worth knowing

- No real light, e-ink panel, ESP32 board or Home Assistant was connected for this release. The adapters were tested against fake tools, a mock server and a virtual serial port, and the real busylight-for-humans 1.0.3 was run with no light attached.
- The hook files were run with sample payloads in the documented shapes, not loaded inside Claude Code, Codex or Hermes. Open /hooks after installing and trigger one permission prompt to see the light change.
- Grok Bot has no hooks; its rules block works only when it runs commands on the same machine as the bridge.
- On 2026-10-28, selftest gave 16 ok, the hook test 35 ok, the adapter test 15 ok, the firmware test 7 ok, all with 0 failures; status_check.py reported the fifteen expected findings on the seeded fixture and 0 on the fixed one, with file hashes unchanged and exit 2 on a missing folder. Run the tests on your own machine first.

## Questions

**Do I need to buy hardware?** No. The terminal adapter needs none, and the bridge works the same way with it. If you buy a light later, section 8 lists what the adapters drive and what was tested.

**Can I approve from the light?** No, on purpose. A button cannot show you the command it approves, and anyone can press it. The light tells you to look; you answer at the keyboard. The bridge refuses a config that sets device buttons to approve.

**Does anything leave my machine?** Not by default. The bridge listens on 127.0.0.1 and the hooks write a local log of metadata only. Opening it to your network or using Home Assistant needs a row in approvals.csv with your name.

**How is this different from Agents That Use a Computer?** That pack covers approval gates and status signals for agents that drive a browser or desktop. This one is the hook-driven light and display for any agent session.

## How to buy

$14 one time at https://paperchasewebb.ai/bots/marketplace/items/agent-status-hardware-lights-and-e-ink-via-hooks/. Stripe checkout, then an instant download page; the download link is also in your emailed receipt.

Seller: PaperChaseWebb Inc., mgmt@paperchasewebb.com