Stargate Agent Monitor

What this is

Every live Claude Code session owns an arc of a 24-LED ring. Comets mean leave it alone; pulses mean it wants you. No wrapper script, no daemon, no USB tether — the ESP32 is the webhook endpoint.

Claude Code has a native "type": "http" hook that POSTs each event's JSON straight to a URL. The board runs a tiny MicroPython HTTP server on the LAN, reads only session_id and hook_event_name from each payload, keeps a session registry, and paints the ring at ~33 fps. Multiple machines can point at the same ring — session IDs are UUIDs, so they simply appear as more arcs.

The device then gets a home: a Stargate on an SGC-style dock. A round Waveshare ESP32-S3 AMOLED touchscreen is the gate's centre, the LED ring is the gate's illuminated inner track behind 24 individual windows over a frosted diffuser, and the whole gate floats above the pedestal so all 360° of LEDs stay visible — including 6 o'clock. Nine red chevrons, 39 glyphs, running-bond stonework on the pedestal. Fully parametric OpenSCAD, verified coupon-first.

What the ring says

Motion carries the same information as colour, independently — the ring stays readable in a glance too brief to register hue.

The simulation above is a direct port of ring.py's render loop (default vapor theme): same comet/pulse maths, same per-arc antiphase stagger, same one-dark-LED separator between sessions. Click a state to hold it; leave it alone and it walks a realistic day.

Themes

THEME in config.py picks a palette. Whatever the theme, one rule holds: states that want you are warm, states that don't are cool.

A dict overrides individual states, merged over classic: THEME = {"input": (255, 0, 200)}. An unknown theme name logs a warning and falls back — a typo in config should dim the lights, not take an unattended device's HTTP server down on boot.

With two sessions each gets half the ring; three, a third. Arcs are ordered by first-seen so an arc never jumps position while you're looking at it. Neighbouring arcs get a dark separator LED and are staggered in antiphase so two pink arcs don't breathe as one.

How it works

Events consumed

Background work vs. waiting on you

A session that spawns background agents stops emitting foreground events — from outside that looks identical to a session sitting idle. Two mechanisms stop the ring crying wolf:

• idle_prompt is not red. It means "quiet a while", which is exactly what background work looks like. Red is reserved for notifications that genuinely block.
• A recency window, not a counter. In the field SubagentStart was observed firing once against eleven SubagentStops. So any background event refreshes a BACKGROUND_HOLD_MS window (90 s); a stream of stops is itself evidence agents are running. Cleared on UserPromptSubmit. attention overrides the window entirely.

Known imperfection: if a turn's background work finishes and you don't reply, the arc stays violet for up to 90 s before falling back to pink.

Reliability & privacy

Endpoints

Materials

Two boards appear here on purpose. The Stargate is built around the Waveshare round-screen puck, which runs the console/ firmware and drives the ring from its rear header. The Keyestudio WROOM is only for the original ring-only build (MicroPython, repo root) and isn't needed for the Stargate.

Links go to New Zealand stock (Jaycar NZ and AliExpress). Any equivalent part works: match the spec column.

Electronics

Fasteners & small parts

Filament

Tools

• Bambu H2D (or any 0.4 mm FDM); AMS or a second nozzle for the two-colour front, otherwise the single-colour fallback STL
• Soldering iron with a heat-set insert tip; hex/Phillips driver for M2
• Calipers — every dimension in config.scad is marked CONFIRMED or PROVISIONAL, and provisional ones get measured before the next print
• 400–600 grit paper (diffuser frost), side cutters (filament pins), CA glue
• Software: OpenSCAD 2021.01 + BOSL2, Python 3 (trimesh, manifold3d for the mesh gates), Bambu Studio, esptool, mpremote

The Stargate

Layered front, centre out: screen → inner bezel → 24-window LED track over a continuous diffuser → glyph track → outer mechanical ring → nine chevrons. Behind it, a structural shell and a dish; below it, an SGC dock that carries the gate from underneath and behind so nothing crosses the ring.

Parts

Decisions that shaped it

The full ledger (22 numbered decisions, with the why) is enclosure/DESIGN.md. The ones that matter if you're modifying it:

• Gate floats; the dock never crosses the ring. Carried from below (two cradle lugs) and behind (two pillars). Buttresses, tabs, sockets and a rear spine were all designed, rendered, and deleted once they crowded the 4/8 o'clock chevrons or turned out vestigial.
• Puck clocked USB-down. The screen image rotates in software, so the port drops invisibly into the base; the side buttons land at 11 & 1 behind the bezel with wall reliefs, no access slot.
• Crush ribs, not a retainer plate. Bezel↔floor already captures the puck; three ribs kill the 0.7 mm rattle. Nothing bears on glass.
• Leads exit sideways at 3 o'clock (the header side, shortest loop) — the brief's "15 mm below" was radial, not a droop. This shifts the firmware's LED origin by 6 firmware.
• Registration by lip-in-groove + one off-grid pin. The front plate's 4-fold screw pattern doesn't lock rotation on its own; a Ø2 filament pin at 95° does. The cover's own asymmetric screw set already does.
• Everything decorative is recessed (flat-print rule) and every relief cut is scoped inside its own part's difference() — after a flank relief silently gutted the cradle floor from 2.71 to 0.70 mm without any gate noticing.
• Donor STLs are reference only. The 220 mm German lamp model informed the look; every millimetre here is parametric and printable at 110 mm.

Printing

Files come out of enclosure/render.ps1 into enclosure/print/ (git-ignored, regenerated every run — nothing hand-edited). Regenerate rather than trusting a stale STL:

# one-time
winget install --id OpenSCAD.OpenSCAD
git clone --depth 1 https://github.com/BelfrySCAD/BOSL2.git enclosure/libs/BOSL2
# every time — checks .echo for ERROR, exports binary STL, counts shells, runs the mesh gates
cd enclosure; ./render.ps1

Settings

Print list & orientation

Assembly

Screws and pins only — no glue in any load path; the gate lifts off the base with two screws. Build the gate stack front-to-back on the bench, then seat it on the dock.

Where the inserts go

All fourteen heat-sets are the same part — M2 insert in a Ø3.2 × 5 mm boss — but they live in four groups on three faces, and each group takes a different screw. The maps below stand a colour-coded marker on every hole (rendered from the same config.scad constants the parts use, so they can't drift); the filament pins are marked too since they go in at the same stage.

• A
  Front-plate inserts ×4 — gate_rear front face, r 49 @ 45/135/225/315°. Take 4× M2 × 8 pan-head down through gate_front's counterbores.set from the front face · screws come from the front · 4.0 mm plate under the head + 4 into the insert
• B
  Rear-cover inserts ×4 — gate_rear back face, r 40 @ 30/150/225/315° (v2 angles; asymmetric on purpose). Take 4× M2 × 10 countersunk through rear_cover.set from the back face · screws come from behind · 1.8 floor + 4.2 cover cavity + 4 into the insert
• C
  Pillar-retention inserts ×2 — gate_rear back face, r 45 @ 245/295°, just outboard of the lower B pair. Take 2× M2 × 20 pan-head driven from behind through each rear pillar and the cover's pass-through — the gate's only retention.set from the back face · at the pillar angles 245/295°, 20° from the relocated B holes · 10 pillar + 0.25 gap + 1.8 floor + 4.2 cavity + 3.75 into the insert
• D
  Bottom-cover inserts ×4 — base_main, up into the 5 mm shelf around the cavity at (±50, ±22) mm. Take 4× M2 × 6 pan-head up through base_bottom.set from underneath, base upside down · 2 mm plate + 4 into the insert
• P
  Filament pins (Ø2, glued) — 1 registration pin in gate_rear's front face @ 95° r 52 (3 mm deep); 18 chevron pins on gate_front's outer ring, two per chevron at r 52 + 53 (2.5 mm deep).CA glue · not load-bearing

Screw lengths — derived from the CAD stack-ups

Every boss is 5 mm deep, so a screw can carry at most 5 mm of thread past the mating face; these lengths aim for ~4 mm and are all within 1 mm of bottoming out — don't go up a size. Pan-head lengths are under-head; countersunk is overall. Derived from config.scad, not yet measured on printed parts confirm.

Inserts: 14× brass M2 heat-set, OD 3.2, length 3–4 mm (the 5 mm boss leaves 1 mm under a 4 mm insert). Shopping list: 4× M2×8 pan · 4× M2×10 CSK · 2× M2×20 pan · 4× M2×6 pan. If you only have one pan length in the drawer, M2×8 works for A and can be cut down for D; C and B have no substitute.

A A A A P

B B B B C C

A A A A P P P P P P P P P

D D D D

1. Prep the printed parts

   Deburr the pockets. Frost one face of the diffuser with 400–600 grit until it's evenly matte. Snip 19 pins from 1.75 mm filament: 18 × ~2.5 mm (chevrons), 1 × ~3 mm (registration).

   Set all 14 M2 heat-set inserts per the maps above: A ×4 in gate_rear's front face, B ×4 + C ×2 in its back face, D ×4 in base_main's cavity shelf. Keep the iron square — the bosses are 5 mm deep.

   an M2 screw runs in and out of each insert three times without stripping (that's what coupon A proved)

2. Pin the chevrons

   A drop of CA in each of the 18 pin holes on gate_front's outer ring, pins in, then the nine chevrons over their pin pairs at 40° pitch — one dead at 6 o'clock, on the dock's centreline (v2 clocking, 2026-08-20). Each chevron body bridges the two front-plate screw holes sitting 5° either side of it, so fit chevrons after the front plate is screwed down if you'd rather keep the screws reachable (see step 8).

3. Registration pin

   Glue the 3 mm pin into the Ø2 blind hole in gate_rear's front face at 95° (r 52, deliberately off the 10° groove grid). It mates with the hole at 85° on the back of gate_front and is the only thing stopping the front plate going on 90° out.

4. Seat the screen puck

   Drop the Waveshare puck into gate_rear's Ø51.5 pocket USB-C toward 6 o'clock (the tunnel). Its side buttons should land in the two wall reliefs at 11 and 1 o'clock — if it won't go home, you're a few degrees off. Press the case rim until it sits on the three crush ribs (~0.2 mm preload).

   puck doesn't rattle; a strip of paper slides under the bezel — glass untouched

5. USB-C extension

   Plug the right-angle male end into the puck; the cable drops straight down the 16 × 10 tunnel at 6 o'clock — the gate's only rim opening. Leave the female end hanging for now.

6. LED ring + leads

   Lay the 24-LED ring in the annular pocket (OD 74 / ID 58 / 4.3 deep). It should drop in and rotate freely (coupon C). Clock it so its flying leads exit through the 14 mm through-slot at the viewer's 3 o'clock, header side; the leads loop across the open back face into the header cavity. Wire 5V, GND and Din to the puck's rear 8-pin header (or to the WROOM if you're running the shipped firmware), with the 330 Ω spliced into the Din lead at the ring end and the 1N5822 in the 5 V lead, stripe toward the ring — wiring.

   Firmware note. With the leads at 3 o'clock, LED index 0 is 6 LEDs away from where the shipped firmware assumes it — a one-constant fix in ring.py, still open firmware.

7. Diffuser

   Frosted face out, on top of the ring. It sits 0.2 mm proud of the pocket on purpose — the front plate preloads it, so nothing rattles and no light leaks between windows.

8. Front plate on

   Line the 85° hole up with the registration pin, seat gate_front, and drive the 4× M2 × 8 pan-heads at 45/135/225/315° into the front-face inserts. Snug, not torqued — the mullions between windows are 0.6 mm+ lines, not structure.

   every LED sits behind its own window; power the ring and look for bleed between windows

9. Rear cover

   Tuck the lead loop and header cavity tidy. Offer up rear_cover: its 1.3 mm lip drops into the recessed groove on gate_rear's back — it only seats where the lip's gap lines up with the USB tunnel arc, so if it rocks, rotate it. On v2 covers each screw runs inside an internal guide boss, so the tip arrives at the insert mouth by itself instead of being fished across the cavity. 4× M2 × 10 countersunk at 30/150/225/315° (v2 angles — v1 prints have 250/290, which the pillars pinch) — the shank crosses the cover's own cavity before it reaches the insert. The gate stack is now one 26 mm drum.

   cover sits flush, no rock, lifts out cleanly before screwing (coupon D)

10. Cable through the dock

    Feed the extension's female end down through the platform drop slot into base_main's cavity and out the 16 × 14 × 12 rear-wall port. There's no panel socket — the port is a plain through-hole; the female end lives just inside or just proud of the wall, whichever your cable prefers.

11. Seat the gate

    Lower the stack so its Ø110 rim beds into the two cradle lugs (±30° off bottom, 0.25 mm running clearance) with its back flush against the two rear pillars. Drive the 2× M2 × 20 from behind, straight through each pillar and the cover's pass-through, into gate_rear's back-face inserts — on v2 covers the tip runs inside a guide boss for the cavity crossing. Shear load only — nothing side-drives.

    from a normal seated position all 24 windows are visible, including 6 o'clock; the base does not tip under a firm touchscreen press

12. Close the base

    Cables inside, base_bottom on with 4× M2 × 6, rubber feet in their recesses. Plug in at the rear port. On boot the puck (or WROOM) prints ring: listening on http://<ip>:80/hook; the ring shows one dim cyan pixel creeping round — idle.

Service: two screws free the gate from the dock; four free the cover for the header; four free the front for the ring or puck. Nothing needs to be cut or unglued except a chevron.

Setup

0Wiring — ring to the Keyestudio ESP32

Three wires. The board is a Keyestudio ESP32-WROOM-32E (Jaycar XC3800); the ring is the Jaycar XC4385.

In-line components

Power budget: BRIGHTNESS = 24 ≈ 150 mA whole ring, fine on USB; full white would be ~1.4 A. The diode's ~0.4 V drop dims the ring a whisker — invisible at this brightness. For the enclosure build the same three wires go to the Waveshare puck's rear 8-pin header instead — pin choice belongs to the firmware port firmware.

1Flash MicroPython

esptool --port /dev/ttyUSB0 erase-flash
esptool --port /dev/ttyUSB0 -b 460800 write-flash 0x1000 ESP32_GENERIC-*.bin

2Configure

cp config.example.py config.py
$EDITOR config.py        # WiFi creds; set a STATIC IP — the hook URL is a fixed string

config.py is git-ignored. Key knobs: LED_PIN = 13, LED_COUNT = 24, BRIGHTNESS = 24, THEME = "vapor", BACKGROUND_HOLD_MS = 90_000, WORKING_TTL_MS = 1 h, SESSION_TTL_MS = 4 h, optional TOKEN.

3Deploy & find it

./deploy.sh /dev/ttyUSB0
mpremote connect /dev/ttyUSB0      # press RST → "ring: listening on http://<ip>:80/hook"

4Wire the hooks — on every machine that runs Claude Code

./install-hooks.sh 192.168.1.200   # merges 9 hooks into ~/.claude/settings.json, timestamped backup first
./install-hooks.sh --remove        # undo

Safe to re-run — it replaces this ring's hooks rather than stacking duplicates, so a changed IP is just another run. Manual alternative: merge hooks/settings.snippet.json yourself.

5Verify without Claude

curl -s http://<ip>/                                   # sessions as JSON
curl -sX POST http://<ip>/hook -H 'Content-Type: application/json' \
  -d '{"session_id":"test-1","hook_event_name":"Stop"}'   # one pink arc starts pulsing
curl -sX POST http://<ip>/clear                            # forget everything

Verification gates

Renders lie. Every real defect on this build was invisible to renders, assertions and manifold checks — so the pipeline grew a gate for each one it missed.

Lessons carried forward (from enclosure/README.md): fit-check dynamically, not drop-in; thickness-sensitive features need a thickness assert because boolean gates don't measure walls; any gate that treats empty output as PASS must first grep for ERROR; allow-list boxes make gates blind — use semantic rules; a hull of a flat footprint against a tilted top cannot have planar ends, so widen the deck instead of modelling a twist.

The build, on the desk

Printed, assembled, and running — 2026-08-20. The ring is live on the LAN at 192.168.1.200 and the puck's round screen shows the session count, waiting/working split, and a LIGHTS toggle.

Field findings → v2 fixes (reprinted: the build in the video runs on them)

All four passed the full pipeline (manifold, shells, interference, seating, overhang, mutation-tested asserts). All five went into the v2 reprint, which is the build running in the video. (Findings 1–3 are field findings from the assembled build; 4 is a usability improvement made at the same time.)

Status & open items

Where things live