Start here

Installing it

Three lines with Homebrew, or a disk image, then open the app: its welcome window connects your agents. One step for Codex that nobody can do for you.

LampBoard needs macOS 14 or later.

There is no Dock icon. The panel is the app.

With Homebrew

brew tap marmyx77/tap
brew trust marmyx77/tap
brew install --cask lampboard
open -a LampBoard

The second line is not ceremony. Since Homebrew 6, a cask from a third-party tap is refused until the tap is trusted, and the refusal names neither the cask nor a reason you can act on. Without it the install ends at Refusing to load cask from untrusted tap.

Or the disk image

Download it from the releases page, open it, drag the app to Applications, and open it.

macOS asks once, and everything waits until you answer. A downloaded app raises the downloaded from the Internet dialog at its first launch, possibly while you are still looking at the terminal. Click Open. Until you do, the panel does not appear and every lampboard command hangs against a server that never bound its port, with nothing on screen to say why.

Connecting your agents

The first launch opens the welcome window, and its first button is Connect Claude Code, or Connect Claude Code and Codex where Codex is installed. That is the whole of the setup. Connect… in Settings › Claude Code & Codex does the same later, and Disconnect… there undoes it, after asking.

Connecting writes a few entries into each agent's own configuration: ~/.claude/settings.json for Claude Code, and ~/.codex/hooks.json if you have Codex. Existing entries are kept, and a dated backup of each file is written first. Those entries are how the panel learns that a turn started, finished, blocked or died. Without them the column stays empty.

Most of them are native HTTP hooks: Claude Code posts to the panel directly, with no process started at all. Three still run a small script, and each exception was measured rather than assumed — SessionStart is never delivered as an HTTP hook, SessionEnd is the only event that prints a failed hook on your screen, and Stop carries the repository and branch, which a native hook cannot because it can only send what was already written into the file.

Claude Code 2.1.63 or later for the native form. That is the release that added the http hook type. The panel reads which Claude Code you have and, on an older one, keeps every event on the script and says so; lampboard status shows the version it found. A version it cannot read is taken as current, because Claude Code updates itself.

After an update, nothing. The panel brings its own entries up to date when it starts — on this Mac and on every machine you have added, including entries written under the project's previous name — and touches only an installation addressed to itself. Sessions already open keep the configuration they started with until they restart; nothing breaks in the meantime.

One step only for Codex, and only you can do it. Open Codex, run /hooks, and approve the entry. Codex will not run a hook it has not been told to trust, and it says nothing when it declines. The file is correct, the events never fire, and there is no error anywhere to explain it.

Setting up many Macs from a script

The terminal step is no longer part of the install. It stays for a script that prepares many Macs at once, where nobody is there to press a button:

/Applications/LampBoard.app/Contents/MacOS/lampboard install-hooks

It answers 0 when everything that could be installed was, 1 when nothing worked, and 2 when one agent was set up and another failed, because a script that half-installed should not be told it is finished. A fleet manager can deploy the signed installer package from https://github.com/marmyx77/lampboard/releases/latest/download/LampBoard.pkg; it carries no install scripts, so each person connects on their own first launch.

Sessions already open

Sessions that were running before you connected pick up the new configuration only when they restart. They still appear in the column, because the panel also reads which sessions exist, but their colour will not change until they are restarted.