Most problems are one of four things. The Device pane and the log will tell you which.
The pad is on the wrong layer. Per-key status renders only on Layer 1. Writes on other layers succeed and simply do not appear, which makes this the most confusing failure available — everything looks fine and nothing happens.
Input Monitoring is not granted, or was granted without restarting. macOS reads it at
launch. Settings → Device will say denied; grant it and restart OpenBoard.
The pad is asleep. Over Bluetooth, disconnecting is normal rather than exceptional. Press any key on the pad to wake it.
The hooks are not wired. Without them the pad connects, the board draws, and nothing ever reports — which looks like the app working and the sessions being broken.
Settings → Device shows an orange panel with a Repair hooks button when this is the case. After wiring them, open a new Claude Code session: hooks are read when a session starts, so anything already running keeps going without them.
Same cause, narrower. That session started before the hooks existed. OpenBoard finds running sessions by walking the process table, so it gets a key immediately — but nothing inside it is reporting. Restart that session.
Accessibility is not granted. The board still lights correctly; only the keys that do something stop working. It needs a restart after granting.
The chat could not be confirmed. Where OpenBoard cannot tell which session is in front of you, it refuses to answer a prompt rather than sending ⏎ at whatever is there. In VS Code this happens when two chats' names match for the first 25 characters, because the window title is the only signal available.
If setup says "macOS has a refusal on record", someone answered No to that dialog once. macOS never asks again. Turn OpenBoard on under System Settings → Privacy & Security → Automation.
QuickTime Player and iTerm2 showing when needed is not a problem. Each is used only by an optional feature — fun mode for QuickTime, jumping to a chat hosted in iTerm2 — and macOS asks the first time that feature actually runs.
Jumping to a chat in iTerm2 does nothing, or a raise fails with -1743. That is a
refused Apple event: grant Automation for iTerm2 under System Settings → Privacy &
Security → Automation, the same way as for Terminal. If iTerm2 was already running when
you granted it, quit and reopen iTerm2 once — the grant does not always take effect for a
target app that is already open. The iTerm2 row only appears in Settings if iTerm2 is
installed.
cmux needs no permission, so a refusal is not the cause. Check the app log
(~/Library/Logs/OpenBoard/app.log) for the cmux: line — it names the slot, the surface
and the session's title:
cmux: 3:87144→surface:12 “Refactor the parser”
- No
cmux:line at all — cmux is not running, or its CLI is not where OpenBoard looks: inside the running app's bundle atContents/Resources/bin/cmux. reachable, no session on the board is in it— cmux answered, and none of the sessions holding a key is in one of its surfaces. A session started oversshfrom a cmux tab runs on the other machine and is not reachable this way.- A line naming the wrong surface — the session moved to another tab and the board has not re-read it yet; it corrects itself within a few seconds.
If cmux is configured with a socket password, OpenBoard cannot talk to it and the rows stay unreachable. Nothing else on the board is affected.
The key order has not been confirmed, and your pad reports a different order from the one every pad so far has. Settings → Device → Recalibrate. It paints six colours and asks whether they are in that order.
The ChatGPT app is repainting the LEDs. Codex drives the same hardware on its own schedule. Either set Codex to Custom assignments and give it a subset of keys, or accept periodic repaint. The two never interleave writes mid-message.
An older copy of OpenBoard is still running. The Device pane says "something else has it open" when this happens. Quit the other one.
You built it yourself. A self-signed build cannot verify the update feed's signature,
so the controls are hidden rather than offered and broken. git pull and rebuild.
The check is off. Settings → Device → Version.
~/Library/Logs/OpenBoard/app.logEvery diagnosis has started here. It records what the app saw at launch — permissions, device state, hooks — and every paint since.
It contains session names, which are Claude Code's own summaries of what you are working on, along with working-directory paths. It never leaves your machine, but it is worth knowing before pasting it into an issue.
Setup can be re-run at any time from the menu bar popover or Settings → Device. To make the app forget everything and behave like a fresh install:
rm -rf ~/Library/Application\ Support/OpenBoardYour permissions and hooks are not in there — those are macOS's and Claude Code's respectively — so this resets colours, the pad name and the key order only.
Next: What it does · Setting up · Settings