Connecting things to NestBox

Everything talks to the device the same way: one small JSON message, POST http://<device>/v1/event. GET / on the device is the API reference (also in docs/api.md).

Coding agents

Nothing on the device is specific to one agent. It serves a guide for agents at GET /agents (also /llms.txt): what the device is, its address, which events to send when (working with a short status, helpers, needs_you, done, error, stop), and the rules (privacy, never block on the device, the device may be off).

Ask an agent to "Read http://<device>.local/agents and connect yourself to my NestBox." The guide describes the events; the agent configures its own hooks. The menu bar app's "Teach a Coding Agent…" copies that request.

Agents find the device at the first line of ~/.nestbox/device (written by the Mac app), $NESTBOX_URL if set, or http://nestbox.local.

Claude Code

claude-code/ is a ready-made adapter. Its hooks.json runs nestbox hook, which turns each hook payload into a plain event on the Mac (companion/mac/cli/claude_code.cpp).

Codex

Codex runs the notify program from ~/.codex/config.toml at the end of each turn. A done per turn:

notify = ["sh", "-c", "curl -s -m 2 -d '{\"source\":\"codex\",\"event\":\"done\",\"color\":\"green\"}' \"$(head -1 ~/.nestbox/device 2>/dev/null || echo http://nestbox.local)/v1/event\" >/dev/null 2>&1 &"]

Anything else

Calendars, music, builds, Home Assistant, phone shortcuts: anything that can send an HTTP request. {"source":"calendar","status":"standup in 5 min","color":"cyan","for":300} puts a line in the status bar for five minutes.