rattleboard for ai agents
v0.9.1 · free · model context protocol
Your coding agent finishes a long task while you're across the room. The board tells you. Rattleboard is a split-flap message board with a built-in MCP server, so Claude Code, Cursor, Codex and friends can flip it to TESTS PASSED or NEED YOUR INPUT.
Agents are good at long tasks now. Upgrading a dependency, chasing a flaky test, migrating a schema: you hand it over and it works for a while. The awkward part is knowing when to come back. Check too early and you interrupt yourself; too late and the agent has sat waiting on a question for half an hour.
Rattleboard puts the answer somewhere you'll see it from the kitchen: a split-flap board on a spare laptop, a TV, or the corner of your own screen. Agents post to it as a tool call, and the flaps rattle round to the news.
One click to set up. Settings → Agents finds the agent apps on your computer and connects them, showing you the change first.
Two kinds of message. A status that goes away by itself (“BUILDING”), or a message that stays until you've seen it (“TESTS PASSED”).
Nothing leaves your computer. The key stays in your keychain, and agents can only put things on the board.
Each app also gets an optional Alert me when the agent finishes or needs input switch, and a Sends to choice for its default board.
You see a before/after of the app's settings file, and nothing changes until you click Confirm.
A timestamped copy of each file you already had is saved next to it, such as settings.json.rattleboard-backup-20261019-101500.
Comments, key order, indentation and trailing commas are kept, in VS Code, opencode and Gemini CLI's JSON-with-comments and in Codex's TOML.
Disconnect removes exactly what Connect added and nothing else. Connecting twice changes nothing, and if the file changed since the preview, nothing is written.
Claude Desktop's file is in ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows and ~/.config/Claude/ on Linux. VS Code's mcp.json is in its user settings folder. CODEX_HOME, CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME are honoured. Restart the agent app, or start a new session, after connecting.
priority: "alert"gets through a Focus or Do Not Disturb that holds pop-ups, if you let alerts through. The tool descriptions tell the model the board's size and the characters it can show; a message that doesn't fit is still sent, and the answer says it was cut off. Everything agents send appears once in Message History, labelled with the app, such as “Claude Code via MCP”.
Agents forget. Hooks don't. Turn on Alert me when the agent finishes or needs input (off by default) and Rattleboard adds the agent app's own hooks. The board then shows “Claude Code is done” or “Claude Code needs you” every time, with the project's name on the line below.
The hook runs --notify, which reads the key from your keychain, so the key never goes into a hook file. --seconds 20 makes it a status that goes away again, and --hook reads the hook's JSON for the project name and never fails the hook.
/Applications/Rattleboard.app/Contents/MacOS/rattleboard --notify "Claude Code is done" --color green --source "Claude Code" --hooknotify = ["/Applications/Rattleboard.app/Contents/MacOS/rattleboard", "--notify", "Codex is done", "--color", "green"]An agent can write to a board on another device: a TV, another computer, a Rattleboard Web container, or a real board on its Local or Cloud API.
The default. Save the other board in Settings → Boards and agents can send to it by name, a group, or all. It goes out the same way as Compose's Send.
# list_boards shows your saved boards and groups;
# send_message and send_layout take a board name:
send_message { "text": "DEPLOYED", "color": "green", "board": "Kitchen TV" }
# Settings → Agents → Sends to: a default board per agent app,
# written into its config as:
/Applications/Rattleboard.app/Contents/MacOS/rattleboard --mcp --target "Kitchen TV"For a server, or a computer not running Rattleboard. All six tools act on that board. The key comes from a board saved with that address, or RATTLEBOARD_KEY.
rattleboard --mcp --url http://192.168.1.20:7070
rattleboard --notify "Backup done" --url http://192.168.1.20:7070For agent apps that support remote MCP servers: POST /mcp with Authorization: Bearer <key>. Get the key with docker exec rattleboard rattleboard-web key.
# Claude Code
claude mcp add --transport http --scope user rattleboard http://<server>:7070/mcp --header "Authorization: Bearer <key>"Cursor, VS Code, opencode, Gemini CLI and Codex CLI snippets for the HTTP endpoint are in the README. Claude Desktop needs a public HTTPS address for remote servers, so use --mcp --url there instead.
Prefer to edit the files yourself? Add Rattleboard as a stdio MCP server. These use the macOS path; on Windows and Linux, use the path shown at the bottom of Settings → Agents. Rattleboard has to be running, with Settings → API server on.
claude mcp add --scope user rattleboard -- /Applications/Rattleboard.app/Contents/MacOS/rattleboard --mcp{
"mcpServers": {
"rattleboard": {
"type": "stdio",
"command": "/Applications/Rattleboard.app/Contents/MacOS/rattleboard",
"args": ["--mcp"]
}
}
}{ "mcp": { "rattleboard": { "type": "local", "command": ["/Applications/Rattleboard.app/Contents/MacOS/rattleboard", "--mcp"], "enabled": true } } }{ "mcpServers": { "rattleboard": { "command": "/Applications/Rattleboard.app/Contents/MacOS/rattleboard", "args": ["--mcp"] } } }{ "mcpServers": { "rattleboard": { "type": "stdio", "command": "/Applications/Rattleboard.app/Contents/MacOS/rattleboard", "args": ["--mcp"] } } }{ "servers": { "rattleboard": { "type": "stdio", "command": "/Applications/Rattleboard.app/Contents/MacOS/rattleboard", "args": ["--mcp"] } } }[mcp_servers.rattleboard]
command = "/Applications/Rattleboard.app/Contents/MacOS/rattleboard"
args = ["--mcp"]rattleboard --mcp talks only to the API server on 127.0.0.1. Agents don't need network access turned on. Other boards are reached through the app's Send, or with --url only when you set that up.
--mcp and --notify read the API key from the OS credential store each time. Settings → Agents never writes it into an agent's config, a hook or a skill, and it never appears in a tool's answer or a log.
The tools can show messages and read what the board shows. They can't change settings, sources, plugins or keys, and can't read your other boards' keys.
Every edit to an agent's files is previewed, backed up and reversible with Disconnect. No accounts, no analytics, no server of ours.
No. The desktop apps and Rattleboard Web are free and open source under the MIT licence. If it earns a spot on your wall, you can buy me a coffee.
macOS, Windows and Linux (Raspberry Pi included), plus Rattleboard Web in Docker on any server, NAS or Pi. On Windows and Linux, use the path shown at the bottom of Settings → Agents in place of the macOS path.
No. The one-click setup and the hooks read the key from your keychain each time. The exceptions are ones you choose: an HTTP connection to Rattleboard Web, which stores the key in that agent app's config, and the RATTLEBOARD_KEY environment variable for --url when the board isn't saved in Settings → Boards. Both are documented, and both can be avoided.
It shouldn't. The built-in skill tells agents to post only when something is worth looking up for, and to keep it short. Statuses go away on their own, and you decide what the agent is asked to post. Disconnect removes it all in one click.
Free and MIT licensed. Version 0.9.1. Install it, open Settings → Agents, and click Connect.