AgentKey

Agentic Engineering Hardware, like Codex Micro-style companion devices, is becoming one of the new workhorses of modern software workflows (or most probably not ^^). Some Stack Overflow users may still have one of these Key V2 macropads around, and this repo is a way to repurpose it into a useful agent-era tool, especially now that Stack Overflow itself feels basically dead for many day-to-day workflows.

DISCLAIMER: this project is mostly generated with AI and should be reviewed carefully before any use. Seriously this is at best a PoC

Why this project exists

AgentKey connects VS Code agent lifecycle events to physical LED feedback on The Key V2 macropad. The goal is to make agent state visible at a glance (idle, active, busy, error) without looking at the chat panel all the time. It also turns the three keys into a small agent control device: the left Stack Overflow key is mapped to VS Code push-to-talk (Cmd+I), the middle key confirms the current chat action, and the right key jumps to the next chat edit (or enters bootloader on hold). It combines:

• custom QMK firmware support (Raw HID)
• a local Node daemon for device communication
• VS Code hooks for event-driven LED updates

Requirements

• macOS (tested on Apple Silicon)
• Node.js 20+ (Node 18+ works if fetch is available)
• npm
• QMK installed and initialized (see https://docs.qmk.fm/newbs_getting_started)
• QMK CLI and a local QMK firmware checkout
• dfu-programmer (for ATmega32U4 flashing)
• VS Code with Agent Hooks enabled (Preview feature)
• VS Code Speech extension installed (required for Voice Mode in VS Code)
• The Key V2 flashed with the agentkey keymap overlay from this repo

Setup

Install host dependencies:

npm install

Install flashing dependency on macOS:

brew install dfu-programmer

Set your QMK checkout path:

export QMK_HOME=~/src/qmk_firmware

Build and flash:

./scripts/build-qmk-keymap.sh
./scripts/flash-the-key-v2.sh

Run daemon:

npm run daemon

Board facts

• Board: drop/thekey/v2
• MCU: ATmega32U4
• Bootloader: ATm32U4DFU / DFU
• QMK support: yes
• LED hardware: built-in RGB LEDs

Bootloader entry

The Key V2 can enter bootloader mode in any of these ways:

1. Hold the left-most Stack Overflow key while plugging in the USB cable.
2. Press the physical reset button while plugging in USB.
3. Press a key mapped to QK_BOOT.

In bootloader mode, macOS should show ATm32U4DFU instead of The Key v2.

Build and flash

Use QMK CLI for the main development flow.

export QMK_HOME=~/src/qmk_firmware
./scripts/build-qmk-keymap.sh

To flash while the board is already in bootloader mode:

./scripts/flash-the-key-v2.sh

The helper scripts install the local agentkey keymap overlay into your QMK tree, compile drop/thekey/v2:agentkey, and then flash the resulting hex with dfu-programmer.

Use prebuilt firmware from GitHub Releases

If you do not want to build locally, download drop_thekey_v2_agentkey.hex from the latest GitHub Release assets.

1. Enter bootloader mode (see Bootloader entry above).
2. Download the release artifact drop_thekey_v2_agentkey.hex.
3. Flash it with dfu-programmer:

dfu-programmer atmega32u4 erase
dfu-programmer atmega32u4 flash ./drop_thekey_v2_agentkey.hex
dfu-programmer atmega32u4 reset

After reset, unplug/replug if needed and the board should enumerate again as The Key V2.

If you want the legacy make-based flow, QMK also supports:

make drop/thekey/v2:agentkey:flash

QMK overlay

The firmware overlay lives under firmware/qmk-overlay/keyboards/drop/thekey/v2/keymaps/agentkey.

It adds:

• RAW_ENABLE = yes for QMK Raw HID
• chat-focused key actions (Cmd+I, chat-confirm macro, next-chat-edit shortcut)
• right-most key tap for next chat edit and hold for bootloader
• a raw_hid_receive() handler that accepts host LED commands

build-qmk-keymap.sh automatically installs this overlay into your local QMK tree before compile.

If you only want to copy the overlay without compiling, run:

export QMK_HOME=~/src/qmk_firmware
mkdir -p "$QMK_HOME/keyboards/drop/thekey/v2/keymaps/agentkey"
cp firmware/qmk-overlay/keyboards/drop/thekey/v2/keymaps/agentkey/* "$QMK_HOME/keyboards/drop/thekey/v2/keymaps/agentkey/"

Local daemon

Start the daemon with:

npm run daemon

Then set an LED preset with:

./scripts/set-led-state.sh active

You can also send a custom color:

./scripts/set-led-state.sh custom '#00c853' 0.8

The daemon targets the QMK Raw HID interface on usage page 0xFF60 and usage ID 0x61.

VS Code hooks

The simplest VS Code integration is a workspace hook that posts LED state updates to the local daemon on agent lifecycle events.

The hook configuration lives in .github/hooks/agentkey.json and calls scripts/agent-hook.js.

Event mapping:

• SessionStart -> active
• UserPromptSubmit -> busy
• PreToolUse -> busy
• PostToolUse -> active
• SubagentStart -> busy
• SubagentStop -> active
• Stop -> idle

To use it:

npm run daemon

Then open VS Code hooks configuration or just keep the workspace hook file in place. VS Code should load .github/hooks/*.json automatically.

If you want to test the hook script directly, you can pipe a small event payload into it:

printf '{"hook_event_name":"SessionStart"}' | node ./scripts/agent-hook.js