Skip to content

Latest commit

 

History

History
131 lines (90 loc) · 5.54 KB

troubleshooting.md

File metadata and controls

131 lines (90 loc) · 5.54 KB

Troubleshooting

← back to the README

Most problems are one of four things. The Device pane and the log will tell you which.

Nothing lights at all

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 keys light but never change

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.

A session appears but stays one colour

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.

Pressing a key does nothing

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.

Automation will not grant

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.

Jumping to a chat in cmux does nothing

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 at Contents/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 over ssh from 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.

Colours land on the wrong keys

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 board goes dark by itself

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.

Updates are not offered

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.

Where to look

~/Library/Logs/OpenBoard/app.log

Every 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.

Starting over

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/OpenBoard

Your 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