Setup guide

Show your AI coding agents on the meter

Busy Meter can show how many of your AI coding-agent sessions are working, and nudge you when one is waiting for you. It works with Claude Code and Codex at the click of a button, and with other tools through their own hooks. Nothing is sent anywhere: the agents leave a small note on your PC and the app reads it.

What the meter shows #

• Stars = sessions working. One session working shows 1 star, two show 2, and so on up to 6 (six or more). When nothing is working, the agents show nothing and your other sources decide.
• A pulse on the light along the bottom = a session is waiting for you, for example to approve a command. See The waiting nudge.
• The panel's Listening to list shows, for example, AI agents · 2 working.

Your agents are one more source, so the busiest source still wins: during a meeting (4 stars), two working sessions don't show. To show agents as a different level (for example any work = Focus), change the AI coding agents rows in Settings › Levels. See Levels and looks.

To see both at once, set While another source is busier to Show agents on the light along the bottom: the stars show your meeting and the light along the bottom turns the AI color while any session works. See Stacking.

The waiting nudge #

When a session starts waiting for you, the light along the bottom pulses twice in the AI color (violet, #8A2BE2, unless you change it): two short pulses, then your level shows again. The setting Nudge when an agent is waiting has three choices:

• Repeat (default): pulses again every 30 seconds while a session is still waiting, for up to 5 minutes.
• Once: one nudge each time a session starts waiting.
• Off: no nudge.

Nudges are always at least 10 seconds apart, and there are never more than 10 in 5 minutes, even when sessions keep starting and stopping to wait.

Pick the AI color below it (it's greyed out while both the nudge and stacking are off). The nudge doesn't show while the meter flashes, while the camera is on (after its Flash too), while syncing is paused or while the meter is off, and the night schedule's dimming also dims the nudge. It doesn't change your level or count as a tap.

Count "finished, your turn" as waiting #

By default only a question or a permission prompt counts as waiting. Turn on Count "finished, your turn" as waiting to also be nudged when Claude Code or Codex finishes and it's your turn to type.

Turn it on #

1. Open Settings › Sources and turn on AI coding agents.
2. Click Connect next to Claude Code or Codex (or both).

That's all. To stop, click Disconnect, or turn the switch off.

Claude Code #

Connect adds Busy Meter's hooks to Claude Code's user settings (%USERPROFILE%\.claude\settings.json, or the folder in CLAUDE_CONFIG_DIR if you set it). Claude Code then tells the meter exactly when a session works, waits for you and ends. Start a new Claude Code session after connecting.

Without Connect, Busy Meter still watches Claude Code's session files: a session that wrote to its transcript in the last 3 minutes counts as working. The row says Watching session files · Connect for exact status. This needs no setup, but it can't tell when a session is waiting for you, so there's no nudge.

What the row can say:

Codex #

Connect adds Busy Meter's hooks to Codex's hooks.json (in %USERPROFILE%\.codex, or CODEX_HOME if you set it). It never edits Codex's config.toml, and an existing notify program is left alone.

Approve the hooks in Codex #

Codex runs new hooks only after you approve them. After Connect, the row says Open Codex and approve Busy Meter in /hooks:

1. Open Codex.
2. Type /hooks and approve Busy Meter's entries (they run bm-agent.exe … --from-busymeter).
3. Use Codex as usual. The row says Connected (hooks) once Codex reports for the first time.

After Disconnect, Codex may ask you to approve your own other hooks again in /hooks: Codex approves hooks by their place in the file, and removing Busy Meter's entries can move yours up.

Disconnect #

Disconnect takes out exactly the entries Busy Meter added; your own hooks and settings stay as they are. Turning AI coding agents off asks Also disconnect Claude Code and Codex?: choose Disconnect, or Keep connected if you'll turn it back on soon (the hooks then only leave notes nobody reads). Uninstalling Busy Meter also removes its hooks from both tools.

Other tools #

Any tool that can run a program from its hooks (Gemini CLI, Cursor and others) can tell the meter what it's doing with bm-agent.exe, which comes with Busy Meter (%LOCALAPPDATA%\BusyMeter\current\bm-agent.exe):

bm-agent.exe working --tool gemini --session <id>
bm-agent.exe waiting --tool gemini --session <id>
bm-agent.exe finished --tool gemini --session <id>
bm-agent.exe idle --tool gemini --session <id>
bm-agent.exe end --tool gemini --session <id>

• working: the session is busy. waiting: it needs you. finished: it's your turn (counts as waiting only with Count "finished, your turn" as waiting on). idle: nothing going on. end: the session is closed.
• --tool is a short name of your choice (letters, digits, ., _, -; up to 32). --session is optional; use the tool's session id if it has one, so several sessions count separately.
• bm-agent.exe prints nothing and always succeeds, so it can't break your tool's session.
• A session that says nothing for 10 minutes stops counting as working; one that waits for an hour stops counting as waiting. Send end when it closes.
• Leave --from-busymeter off these lines. Busy Meter only removes entries it wrote itself, so remove these yourself when you uninstall.

bm-agent.exe hook claude and bm-agent.exe hook codex read Claude Code's and Codex's own hook messages; they're what Connect sets up.

Privacy #

• Busy Meter reads only session ids, states (working, waiting, finished) and times. Never your prompts, code, transcripts, tool output or token counts.
• The notes live in %LOCALAPPDATA%\BusyMeter\agents on your PC. Nothing goes over the network.
• While a tool is connected, Busy Meter keeps one copy of that tool's settings file from before its last change, next to it (settings.json.busymeter-backup or hooks.json.busymeter-backup). Disconnect and uninstalling delete it.
• A problem report says which tools are connected, where their hooks are and how many sessions are in each state; nothing about what the sessions do.

By hand #

Use this when the app says it couldn't edit a tool's settings (for example, the file has comments in it, or it's a link to another file in a dotfiles setup). Each tool runs the small bm-agent.exe that comes with Busy Meter. It prints nothing and always succeeds, so it can't get in the way of your session. Its path is:

%LOCALAPPDATA%\BusyMeter\current\bm-agent.exe

Replace %LOCALAPPDATA% with the real folder, for example C:\Users\you\AppData\Local. Keep --from-busymeter on every line: it lets the app find and remove exactly these entries later.

Once the entries are in, the row says Connected (hooks) (Codex: after you approve them), and Disconnect removes them. But when the app sent you here because it couldn't edit the file (comments in it, or a link to another file), it can't remove them either: take them out yourself before you uninstall Busy Meter (Remove the hooks by hand).

Claude Code by hand #

Open %USERPROFILE%\.claude\settings.json (if you set CLAUDE_CONFIG_DIR, the settings.json in that folder). Add one entry like this for each of SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Notification, Stop and SessionEnd:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "C:\\Users\\you\\AppData\\Local\\BusyMeter\\current\\bm-agent.exe",
            "args": ["hook", "claude", "--from-busymeter"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

If the file already has a "hooks" section, add only the event entries inside it (and to an event that's already there, add the { "hooks": [ … ] } entry to its list). Don't add a second "hooks": Claude Code would quietly use only one of them and drop your own hooks. Use "timeout": 1 for SessionEnd. Then start a new Claude Code session.

Codex by hand #

Open %USERPROFILE%\.codex\hooks.json (if you set CODEX_HOME, the hooks.json in that folder; create the file if it isn't there). Add one entry like this for each of SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, Stop, Interrupt and SessionEnd:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:\\Users\\you\\AppData\\Local\\BusyMeter\\current\\bm-agent.exe\" hook codex --from-busymeter",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

As with Claude Code, if the file already has a "hooks" section, add only the event entries inside it. Use "timeout": 1 for SessionEnd and Interrupt. Codex runs the command through the Windows command prompt, so if the folder path has %, &, !, ^ or a similar character, use its short form instead (in a Command Prompt, dir /x in the parent folder shows it, for example C:\Users\ANNA~1). Then open Codex, type /hooks and approve them.

Remove the hooks by hand #

If Busy Meter was removed without its uninstaller (or a tool's settings were copied from another PC), Claude Code or Codex may show a hook error on every step, because bm-agent.exe isn't there any more. To clean up:

1. Open the tool's settings file: %USERPROFILE%\.claude\settings.json (Claude Code; or in CLAUDE_CONFIG_DIR) or %USERPROFILE%\.codex\hooks.json (Codex; or in CODEX_HOME).
2. Delete every hook entry that has --from-busymeter in it. If an event has nothing else left, delete the event too.
3. Delete settings.json.busymeter-backup or hooks.json.busymeter-backup next to it, if it's there.
4. Optionally delete the folder %LOCALAPPDATA%\BusyMeter\agents.

Troubleshooting #