Free refills
beady-eye
Run a few coding agents on beads and two things go wrong. You lose sight of the overall goals and of what each agent is doing. And an agent waiting on a merge, a build or your answer has to poll for it with a script you wrote by hand.
beady-eye draws your work as a tree, with the agent on each bead, and tells an agent when the bead it waits on moves.
- See all the work as a tree, in one project or across all of them. Each goal sits above the beads that serve it.
- See every agent live, beside the bead it is working on.
- Run one watcher that follows every tracker. It is the cheap way for an agent or a script to hear that a bead changed.
- Let an agent wait on your answer, your comment or another agent's work, and feed any script a line of JSON each time a bead changes.
- Let an agent wait on a pull request, an issue or a release without polling GitHub.
beady-eye does the waiting, so your agents do the work. The command is
bdi. It is open source, Apache-2.0, and Code For
Breakfast runs its own agent fleet on it.
~$ brew install codeforbreakfast/tap/bdi
The tree of work, and who is on it
See every order in the kitchen, and which cook has it. To see the cooks, you need herdr.
Agents and scripts wait on beads without polling
Order up. Nobody hovers at the hatch.
One watcher on each machine follows every tracker you name. To wait on a bead, an agent only has to name it. The agent may need a question answered, another agent's work finished or a pull request merged. It watches the bead for that and moves on. When the bead changes, beady-eye tells the agent what changed. Anything that can write to a bead can reach whoever watches it, and neither side needs to know the other exists. The bead is the address, and the tracker keeps the message after the listener has gone home. Here is what a listener can wait on.
How it works
One watcher on each machine. The word gets out two ways, and comes back one.
bd, as
they always have. bdi gates writes too. It reads GitHub,
the clock and other beads, closes the gates that wait on them, and
comments on the beads those gates hold back. The watcher sees the
tracker move and passes the word to whoever is waiting on that bead. A
person's answer goes back the same way, with bdi bd.
How to order
bdi shows you the work with no config. Getting it to tell your agents takes three more steps.
You need Linux or macOS, bd 1.1.0 or newer, and a tracker bd can open.
bdi is one Rust binary. herdr is
needed for the pane beside each bead, and the rest works without it. gh
lets bdi gates settle gates on GitHub, and Node runs the
Claude Code plugin.
-
Install bdi and run it. Homebrew has a built binary for macOS and Linux. The other routes are in the comments.
brew install codeforbreakfast/tap/bdi # or: cargo install beady-eye # or: herdr plugin install CodeForBreakfast/beady-eye # or: nix run github:CodeForBreakfast/beady-eye # then, in a repository beads tracks bdi -
Keep the watcher running.
bdi watchandbdi gatesrun under whatever supervises your processes. This is the systemd user unit for the watcher from docs/configuration.md, withExecStartpointed at where Homebrew puts bdi on Linux.which bdiprints yours. The same page has the unit forbdi gatesand a launchd agent for macOS.# ~/.config/systemd/user/bdi-watch.service [Unit] Description=beady-eye watcher [Service] ExecStart=/home/linuxbrew/.linuxbrew/bin/bdi watch Restart=on-failure [Install] WantedBy=default.target # then systemctl --user enable --now bdi-watch -
Let it tell your Claude Code sessions. Install the plugin, pinned to its release, and start each session with the plugin's channel allowed. The flag is Claude Code's, not beady-eye's. Channels are a research preview there, and Claude Code delivers a plugin's messages only to a session started with that plugin named: with
--channelsfor the plugins on Anthropic's own list, and with this flag for any other. A session started without it still has thewatchtools but is never told of a change. Claude Code wants the flag on every session, so put it in whatever starts yours.claude plugin marketplace add CodeForBreakfast/beady-eye#plugin-v0.3.0 claude plugin install beady-eye@beady-eye # start each session with the plugin's channel allowed claude --dangerously-load-development-channels plugin:beady-eye@beady-eye -
Give docs/agents.md to your agents. It tells each agent to write its session and its pane on the bead it works, and bdi draws the agent beside the bead from what it wrote. Fold its lines into whatever instructions your agents already follow.
The latest release has a binary for every platform. The README has the keys, the herdr key binding, Nix flakes, the config for several trackers, and what each listener is sent.
Cooked in the same kitchen
Code For Breakfast built this. It cooks for clients too.
Code For Breakfast Ltd is a UK software consultancy, based in York and working remote-first. The kitchen that made this ships well-tested software for clients, fast, and builds and operates real multi-agent AI systems.