Busy Meter Guide

Setup guide

Use the meter with an AI assistant

You can ask an AI assistant to set your meter ("show Do not disturb for the next hour") or to start one of the ready-made recipes ("start a 25-minute focus timer"). The assistant talks to the Busy Meter app through External connections, never straight to the meter. That way your camera, Teams, calendar and level map keep working, and you approve the assistant once in the tray.

What you need #

Claude Desktop #

Claude Desktop rewrites its settings file while it runs, so a change made while it's open can be lost. Do this with Claude Desktop fully quit:

  1. Quit Claude Desktop: close its window, then right-click its icon next to the clock and choose Quit. Closing the window alone leaves it running.

  2. Press Win + R, paste %APPDATA%\Claude\claude_desktop_config.json and press Enter. If Windows asks which app to use, pick Notepad. If the file doesn't exist, create it in Notepad and save it with that name in %APPDATA%\Claude\.

  3. If the file is empty, paste all of this. If it already has an mcpServers section, add only the "busymeter": {…} part inside it, with a comma after the entry before it:

    {
  "mcpServers": {
    "busymeter": {
      "command": "busymeter-mcp"
    }
  }
}

  4. Save, then start Claude Desktop. In a new chat, the tools menu lists busymeter.

  5. Ask: "What is my busy meter showing?" The Allow prompt opens in the Busy Meter tray; click Allow.

Claude Code #

Run once in a terminal:

claude mcp add --scope user busymeter -- busymeter-mcp

Restart Claude Code, then ask it to set your meter. Claude Code can also use the busymeter command directly (busymeter level 4 --for 10m; for longer the command keeps running and renews the level), which goes through the app the same way.

Other assistants #

Keep your assistant on the right path #

An assistant that doesn't have the Busy Meter tools may try to be helpful in the wrong way: send commands straight to the meter over its USB port or its Wi-Fi address, or ask you to close the Busy Meter app because "the USB port is busy". Say no. The port is busy because the app is using it, which is how it should be. Going around the app:

To keep any assistant on track, paste this into its custom instructions (Claude Code: your CLAUDE.md; Claude Desktop or other apps: their custom or project instructions):

Busy Meter: to read or change my Busy Meter status light, use only the busymeter MCP tools,
or the `busymeter` command (busymeter level 0-6|flash --for 10m, busymeter clear, busymeter status).
Never talk to the meter directly: no serial/COM port, no HTTP or WebSocket to its IP address,
no WLED presets, and never ask me to quit the Busy Meter app to free the USB port.
If the tools fail, tell me the error and how to fix it (usually: turn on
Settings > Sources > External connections in the Busy Meter app, or install the tools
with: pip install --user "busymeter[mcp]").

The Busy Meter tools already tell assistants the same thing, and so does thebusymeter.com/llms.txt, the page assistants read about Busy Meter.

The first time #

The first time the assistant connects, the tray shows "A program on this PC is asking to connect". Check the name and the program, then click Allow (the button works after a second). The assistant can ask, but only you can allow it. Switch it off or Revoke it at any time under Settings › Sources › External connections.

Recipes the assistant starts (focus timer, stream status, game state, vibe meter) each ask for their own Allow the first time. If a recipe is stopped before you answer, its prompt closes by itself. A recipe only starts when you sign in to Windows if you (or the assistant, when you ask) turn that on.

Things to try #

A level from the assistant lasts as long as it asks (default 10 minutes; then the meter goes back to your other sources) and goes through Settings › Levels, where the assistant has its own group you can remap.

Good to know #