beekeeper keeps the Claude Code sessions that share one machine working together.
A dozen sessions on one workstation compete for the same things:
- RAM and swap: one OOM kill of the desktop scope ends every session.
- A handful of kind labs and shared installations.
- The one browser the Claude in Chrome extension drives.
- The merges into a repository that rolls an installation.
- The one GitHub budget every
ghanddevctlcall draws from.
beekeeper reads what is already on disk (the process table, the session records, the transcripts and the git checkouts) and keeps what must be shared in a small state directory. Every session and the supervisor use the same binary.
On top of that it runs a desk: a supervisor loop that fills the desk from a project board, starts workers on Claude Code, omp, agy or codex, gates every merge, and a guide session that walks the person through the decisions waiting on them.
Download the binary for your OS and architecture into a directory on your PATH:
dir=~/.local/bin # any directory on PATH
curl -fsSL -o "$dir/beekeeper" https://github.com/giantswarm/beekeeper/releases/latest/download/beekeeper-linux-amd64
chmod +x "$dir/beekeeper"Then look at what the install would do, and install it for your user:
beekeeper install --dry-run # every file, hook and service step; changes nothing
beekeeper installinstall adds beekeeper's hooks to Claude Code's settings and installs the supervisor loop
as a user service. beekeeper self-update keeps it current.
Releases are signed. Install shows how to verify a download, what the install changes and how to add the role plugin:
claude plugin marketplace add giantswarm/beekeeper
claude plugin install beekeeper@beekeeperThe session and machine views need Linux. Leases, holds and the budget work anywhere.
| Command | What it shows or does |
|---|---|
beekeeper status |
One line: who supervises, leases and holds, due notes and timers, busy agents. |
beekeeper sessions |
Every running session, what it works on and what it waits for. |
beekeeper capacity |
Busy and idle agents against the ceiling, and whether a new start has room. |
beekeeper ui |
A terminal screen over the machine, the sessions, the agents and the merges. |
beekeeper lease claim <resource> -p "<why>" |
Takes a shared lab, installation or the browser. |
Every command takes --json. beekeeper --help lists them all, and
Commands describes each one.
Start here:
- How beekeeper works: what it reads, what it keeps.
- Install: download, verify, hooks, updates and the role plugin.
- Commands: every command and the conventions they share.
- Configuration: every key, with a complete example.
Running a desk:
- The supervisor loop: filling the desk, outages, alerts.
- The merge gate: lanes, turns, releases and stuck merges.
- The guide and the desk: roles, relays and claims across desks.
- Agents and their turns: starting, waking, stopping and handing over.
- Worker sessions: headless and desktop turns, reviews, parking.
- omp, agy and codex agents: workers beyond Claude Code.
- Capacity, models and subscriptions: who starts on which model.
- Notifications and reports: desktop notifications, deliveries, the status reporter.
- Remote hosts and the central instance: SSH execution hosts and shared state.
- Disk: automatic reclamation and the disk floor.
Safety:
- Threat model: who reaches what, what leaves the machine.
- Secrets and GitHub Apps: credential work without reading a value.
- The agent sandbox and Folders, deletes and guards.
- Clusters: kube contexts, production writes, Teleport, upgrades.
- The browser:
beekeeper browse, consents, uploads and proofs.
Everything else, including design notes and proofs, is listed in the documentation index.
See CONTRIBUTING.md and Developing on beekeeper.
Document new behaviour in its docs/ page, not here. CI keeps this file under 150 lines and
every Markdown line in it and in docs/ under 200 characters
(check).