← HumanNeeded

Quick start

About five minutes. You need the puck, a USB-C cable, and a Windows computer where you use Claude Code.

1Plug in the puck

  1. Connect the puck to your computer with a USB-C cable.
  2. Within a second or two the light sweeps through a rainbow. That means it's powered and ready.

There's nothing to install for the puck itself: Windows recognises it on its own. If you see no rainbow, see No light at all.

2Connect your agents

Each agent gets a small plugin that tells the puck when it's working, done, or needs you. Set up the ones you use.

Claude Code

The Claude desktop app's Code tab, the claude terminal, or the VS Code extension. One install covers all of them.

In the Claude desktop app:

  1. Open the Code tab and start a session on your computer (not a cloud session).
  2. Click + next to the prompt box and choose Add plugins. If the menu shows Plugins instead, choose Plugins, then Browse plugins.
  3. Add a marketplace, and paste this address when asked: 
    https://human-needed.com/claude/marketplace.json
  4. Select humanneeded in the plugin list and install it for your user account, so it works in every project.

Or ask Claude to install it. Paste this into a Claude Code session:

Install the HumanNeeded plugin for me by running: claude plugin install humanneeded --marketplace https://human-needed.com/claude/marketplace.json
If claude isn't on PATH, run the executable in the CLAUDE_CODE_EXECPATH environment variable instead.

Or run it yourself in a terminal:

claude plugin install humanneeded --marketplace https://human-needed.com/claude/marketplace.json

Then start a new session (sessions that were already open pick it up after a restart) and ask Claude to "test my puck". The light should show amber.

You can also ask Claude to change the puck: "make needs purple", "mute for an hour". Windows for now; macOS is coming. Prefer to look first? Download the plugin (.zip).

Codex (ChatGPT) Coming soon

The Codex app and CLI from OpenAI. The plugin will show working, done, and when Codex is waiting for your approval. Codex asks you once to trust the new hooks.

Cursor Coming soon

The plugin will show working and done. Cursor doesn't tell plugins when it's waiting for your approval, so there's no amber "needs you" light for Cursor.

3What the lights mean

Needs you Amber pulse, with a rising chime. An agent is waiting for your permission or an answer. Stays until you respond.
Done Green pulse for 3 seconds, with a soft chime. An agent finished its turn.
Working Slow blue breathing. At least one agent is busy.
Idle Faint warm white. Nothing is running.

With several sessions at once, the puck shows the most urgent one: needs you, then done, then working.

4Change settings

Change each state's colour, light pattern, brightness, how long it shows, and its sound.

  1. Open the settings page in Chrome or Edge on the computer the puck is plugged into.
  2. Click Edit settings and pick the puck (named HumanNeeded or KB2040) from the list.
  3. Make your changes. Each one is saved on the puck right away; use Preview to see it.
  4. Click Finish editing. While you edit, the puck can't hear your agents.

The settings page is also where you restart the puck and update its firmware. You can change settings by asking Claude too.

Open settings

Troubleshooting

No light at all when I plug it in
  • Try another USB-C cable. Many cables only charge and can't carry data; the puck needs a data cable.
  • Try another USB port, directly on the computer rather than through a hub.
The rainbow shows, but the light doesn't react to Claude
  • Start a new Claude session. Sessions that were open before the install don't use the plugin until they restart.
  • Close the settings page, or click Finish editing. While it's editing, agents can't reach the puck.
  • Close any other program that might be using the puck's port: a serial monitor, the Arduino IDE, or a second settings tab.
  • Ask Claude to "test my puck". If it says the puck wasn't found, unplug the puck, plug it back in, and try again.
  • Check the plugin is installed: run claude plugin list and look for humanneeded@humanneeded.
It stays amber after I've answered

The amber light clears when Claude carries on with its work. If it doesn't, send any message in that session, or ask Claude to "clear the puck".

The settings page can't find the puck
  • Use Chrome or Edge on a computer. Other browsers, and phones, can't talk to USB devices.
  • Close other programs that use the puck's port (see above), then click Edit settings again.
  • In the browser's list, pick the device named HumanNeeded or KB2040.
A firmware update didn't show the RPI-RP2 drive

Unplug the puck. Hold its BOOT button while you plug it back in, then let go. The RPI-RP2 drive appears; drag the firmware file onto it. Your settings are kept.

It's too bright, too loud, or I want silence

Turn down the overall brightness or volume on the settings page, or ask Claude to "mute the puck for an hour". Muting only silences sound; the light keeps working.

Remove the Claude plugin 
claude plugin uninstall humanneeded@humanneeded