Your agents, on your keyboard.

Agent Lights turns the side LEDs on a NuPhy Air75 V3 into a live agent status display—over Bluetooth.

Blue breathes while an agent works. Amber asks for your attention. Green means the turn is done. Keep coding without opening another window just to check.

Original illustration based on the Raycast edition, with enlarged light callouts. Physical Bluetooth lighting and animations have been verified on one Air75 V3 ANSI Raycast edition.

PRs and contributions welcome. Help add agent integrations, improve the Mac app, or test another matching Air75 V3. Get started · Report a bug or compatibility result

What it does

• Five tasks per side, with dark gaps: local work on the left, an optional remote machine on the right. Positions stay stable while tasks are visible.
• Firmware-driven animation: breathing blue, pulsing amber/red, steady green. The Mac sends short status leases, not animation frames.
• A native Mac menu-bar app: see task names, pause/resume, reconnect, acknowledge errors, change gap brightness, and start at login.
• Multiple tools: Codex, T3 foreground sessions, native Grok CLI hooks, and a small event interface for other agents.
• Automatic recovery: the app supervises the controller and Bluetooth helper. If control stops, temporary overlays expire and the keyboard's normal lighting returns.
• Local collection, optional SSH: no hosted service, account, analytics, or API key for Agent Lights. The keyboard receives colors and patterns, never task text.

Light	Meaning
🔵 Breathing blue	Working
🟠 Pulsing amber	Needs input or approval
🟢 Steady green	Turn completed; shown for 30 seconds
🔴 Pulsing red	Error; stays until acknowledged
🟣 Breathing purple	State is uncertain or stale

Have your agent set it up

This is an experimental, agent-first developer project. There is a working setup script; there is no one-click firmware installer. Your agent can inspect your environment and guide the few hardware steps.

git clone https://github.com/arrowarcher1/air75v3-agents.git
cd air75v3-agents

Then give your coding agent this prompt:

Set up Agent Lights from this repository on my Mac. Read AGENTS.md and SETUP.md first. Check my keyboard model, Python and Swift tools, installed agent clients, and Bluetooth pairing. Start with read-only checks. Prepare and test the configuration for my machine. Before any firmware flash, show me the exact image hash, compatibility checks, and recovery plan and ask for approval. Use local tracking first; ask which SSH host to use only if I want remote tracking. Finish by checking a real task and explain any unverified behavior.

Start here: setup guide · agent context · firmware and recovery

Already have the tested firmware and a paired keyboard? On macOS with Python 3.11+ and Apple Command Line Tools:

python3 scripts/setup.py --keyboard 'Air75 V3-1' --dry-run
python3 scripts/setup.py --keyboard 'Air75 V3-1' --start-at-login

Use the exact name shown in macOS Bluetooth settings. Setup builds locally, installs the menu app for your user, and opens it. Accept macOS's normal Bluetooth prompt. It does not flash firmware. A paired stock keyboard does not expose the custom service this project needs.

Compatibility and current limits

Component	Current scope
Keyboard	Air75 V3 ANSI, exact stock 1.0.16.6 input. One Raycast edition unit physically tested.
Other NuPhy models, ISO, HE, V1/V2	Unsupported. Do not flash this image.
Desktop host	macOS; tested on Apple silicon/macOS 26. Source builds target macOS 13+. Intel/older macOS hardware remains unverified.
Connection	Bluetooth for everyday status; USB is required for the initial firmware change. Fresh pairing may be needed after adding the service.
Remote collector	Optional existing SSH connection and Python 3.11+. Tested against a Linux peer.
Codex app / CLI	Read-only task metadata and bounded lifecycle event tails.
T3 Code	Foreground sessions across providers, including Codex and Grok. Background/fleet liveness still needs T3's authenticated live API.
Grok CLI	Optional native hooks, separate from T3 support. Existing sessions need a hook reload.
Other tools	Explicit lifecycle events or a command wrapper; not automatic detection of every running process.

The firmware source reproduces the exact tested image from a hash-checked vendor input. NuPhy's firmware and WCH SDK headers are downloaded separately, not redistributed here. Flashing is an explicit, model-specific operation with recovery considerations. Read FIRMWARE.md first.

Physical sleep/wake, long-term battery impact, and broad hardware compatibility still need community testing. A source being readable is not proof that every background agent is alive. Validation and limits spells out what has actually been checked.

Add another agent

The status protocol is intentionally small. With Agent Lights running:

python3 status/statusctl.py emit --source myagent --id task-1 --state working --turn-id turn-1
python3 status/statusctl.py emit --source myagent --id task-1 --state done --turn-id turn-1

Working/waiting events require periodic renewal. See integrations for native Grok hooks, wrapper behavior, remote setup, and stale-state handling.

Build and contribute

python3 scripts/check.py           # Python + native C checks; no hardware access
python3 scripts/check.py --native  # Also build/self-test the macOS app and BLE helper

Good first contributions:

• Test on another matching Air75 V3 ANSI and report the exact hardware/firmware versions.
• Add lifecycle adapters for another CLI, with tests for cancellation, stale state, and duplicate tasks.
• Connect T3's authenticated background/fleet liveness API.
• Validate sleep/wake, reconnect behavior, and battery impact.
• Improve task labels and menu usability.

Contributing · architecture/protocol · troubleshooting · roadmap

If you try it, open a compatibility report with what worked and what did not. A second verified keyboard matters more than a speculative support claim.

Credits

The original wired lighting patch design comes from Paul Annesley's kbvu, with its MIT notice retained. Protocol research also benefited from nuphy-leds and nuphykit. BLE interface definitions were checked against WCH's CH583 SDK.

Original project code is MIT licensed. See NOTICE.md for third-party boundaries. This is an independent community project, unaffiliated with NuPhy, Raycast, OpenAI, T3, or xAI.