Keeping it honest

When something is wrong

Four commands that say which link in the chain broke, instead of leaving you staring at an unlit lamp.

The column is empty

First, is it connected? The empty panel says so itself: «No lamps yet», with Connect Claude Code, when it is not. Settings › Claude Code & Codex shows Connected or a Connect… button. A session that was already open when you connected changes colour only after it restarts.

lampboard selftest

It checks, in order: the server opens its port, a signal crosses HTTP, it gets decoded, the current folder resolves to a workspace, Accessibility is granted, Automation for System Events is granted, and the hooks are registered. It names the link that broke.

The count looks wrong

lampboard status

Reports how many sessions have a live process, how many deserve a lamp, and how many resolve to a recognised workspace. The last number is how many sessions you should see; grouped by project, there will be fewer rows. Rows at rest for twelve hours are folded into the Resting line at the foot.

lampboard sessions

Shows the column as the running app sees it. If status counts rows that sessions does not list, the problem sits between reading the filesystem and the state machine. If both list them and the panel is empty, it is in the drawing.

A click does nothing, or lands in the wrong window

lampboard focus <workspace>
lampboard focus <workspace> --dry-run

It reproduces the click and prints the window titles it read from System Events, with an arrow on the one it chose. If the read comes back empty you see it at once, instead of inferring it from a click that does nothing. The dry run diagnoses without moving any windows.

If focus says it can see no editor window at all, that does not mean the project is closed. It means macOS is not letting the app read other applications' windows, and the most frequent cause is a locked screen, which restricts that access while still letting simple questions through. The two cases have different remedies, so the app tells them apart.

The first thing to check is not the permission

It is how long the app has been running. A new build does not replace a process already running, and a build that is an hour old is indistinguishable from a revoked permission.

pkill -x lampboard; open -a LampBoard

A row that will not go away

When the project holds several conversations, open it and right-click the stale conversation's own line. If the session behind it is genuinely gone, use Remove this row. If a live process is still holding it, End this session… will offer to end it, and it will name what it is about to end. See the row menu.

Otherwise, or to start the column over, Clear the list is in Settings › About & help. It asks first, and each live session comes back with its next signal.

Writing it down

LAMPBOARD_DEBUG=1

With that set, the app writes ~/.lampboard/debug.log.