beekeeper

command module
v0.175.0-rc.427 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

beekeeper

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 gh and devctl call 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.

Install

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 install

install 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@beekeeper

The session and machine views need Linux. Leases, holds and the budget work anywhere.

First commands

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.

Documentation

Start here:

Running a desk:

Safety:

Everything else, including design notes and proofs, is listed in the documentation index.

Contributing

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).

Documentation

Overview

beekeeper keeps the Claude Code sessions sharing one machine working together: it shows what every session does, watches the machine, reads the GitHub budget they share and holds the shared resources one session at a time.

Directories

Path Synopsis
Package cmd is beekeeper's command line.
Package cmd is beekeeper's command line.
config
crd
Package crd embeds the CustomResourceDefinitions of beekeeper.giantswarm.io, generated by controller-gen from pkg/apis (make generate-crds).
Package crd embeds the CustomResourceDefinitions of beekeeper.giantswarm.io, generated by controller-gen from pkg/apis (make generate-crds).
contrib
systemd
Package systemd carries the systemd user units beekeeper ships, for beekeeper install to write.
Package systemd carries the systemd user units beekeeper ships, for beekeeper install to write.
docs
examples
Package examples carries the documented example configuration, from which beekeeper install writes a starter config.
Package examples carries the documented example configuration, from which beekeeper install writes a starter config.
internal
agy
Package agy manages Antigravity CLI (agy) agent sessions: their inbox, stream-json runner and PreInvocation hook for mid-turn message delivery.
Package agy manages Antigravity CLI (agy) agent sessions: their inbox, stream-json runner and PreInvocation hook for mid-turn message delivery.
agyhooks
Package agyhooks checks agy's hooks.json against the shape agy accepts.
Package agyhooks checks agy's hooks.json against the shape agy accepts.
alerts
Package alerts reads the alerts of the installations the sessions work on and turns two readings into NEW and RESOLVED lines.
Package alerts reads the alerts of the installations the sessions work on and turns two readings into NEW and RESOLVED lines.
apiread
Package apiread mints an audience-bound reader token without exposing it.
Package apiread mints an audience-bound reader token without exposing it.
board
Package board picks the next item of work from a GitHub project board: it reads the board's open items once, ranks them by the configured order and says for every item above the pick why it was skipped.
Package board picks the next item of work from a GitHub project board: it reads the board's open items once, ranks them by the configured order and says for every item above the pick why it was skipped.
brieflint
Package brieflint finds what makes a skill or a brief go stale: dates, waits on something to ship, notes on a release that fixed something, a role's run where the role's name belongs, and a shell example whose bare > a rerun under noclobber refuses.
Package brieflint finds what makes a skill or a brief go stale: dates, waits on something to ship, notes on a release that fixed something, a role's run where the role's name belongs, and a shell example whose bare > a rerun under noclobber refuses.
central
Package central is the local beekeeper's client of the central instance: beekeeper serve behind muster, called as the person through muster's call_tool.
Package central is the local beekeeper's client of the central instance: beekeeper serve behind muster, called as the person through muster's call_tool.
central/centraltest
Package centraltest gives a test a muster in front of a beekeeper serve: its call_tool forwards x_<server>_<tool> to the backend with the caller's bearer and wraps the result as muster does, its subscriptions/listen streams take the updates the test relays, and a muster binary that names its endpoint and prints a token.
Package centraltest gives a test a muster in front of a beekeeper serve: its call_tool forwards x_<server>_<tool> to the backend with the caller's bearer and wraps the result as muster does, its subscriptions/listen streams take the updates the test relays, and a muster binary that names its endpoint and prints a token.
claim
Package claim is a desk's claim of an issue as GitHub carries it: one marker comment per issue and desk, which every desk working the same repository reads, whatever its configuration, board or machine.
Package claim is a desk's claim of an issue as GitHub carries it: one marker comment per issue and desk, which every desk working the same repository reads, whatever its configuration, board or machine.
claim/claimtest
Package claimtest is a fake of the GitHub issue comments the claims live in, for the tests of the claim package and its callers.
Package claimtest is a fake of the GitHub issue comments the claims live in, for the tests of the claim package and its callers.
claude
Package claude finds the Claude Code sessions running on the machine and what they are doing, from what is on disk: the CLI processes (their environment names the desktop session), the record each CLI keeps of the session it runs, the desktop app's session records (title, branch), the transcripts (last activity, last words) and the git checkout each works in.
Package claude finds the Claude Code sessions running on the machine and what they are doing, from what is on disk: the CLI processes (their environment names the desktop session), the record each CLI keeps of the session it runs, the desktop app's session records (title, branch), the transcripts (last activity, last words) and the git checkout each works in.
config
Package config loads beekeeper's machine configuration: where its state lives, which shared resources sessions lease, the GitHub budget floor, the thresholds of the machine watch and which installations' alerts it reads.
Package config loads beekeeper's machine configuration: where its state lives, which shared resources sessions lease, the GitHub budget floor, the thresholds of the machine watch and which installations' alerts it reads.
diskprune
Package diskprune reclaims explicitly disposable disk data, keeping process references, recent data, symlinks and checkouts intact.
Package diskprune reclaims explicitly disposable disk data, keeping process references, recent data, symlinks and checkouts intact.
dockerprune
Package dockerprune keeps the Docker images and build cache of a lab machine under a size: the unused images created or tagged longest ago go first, the ones a kind lab's node holds a copy of last, and the build cache is pruned by Docker's own least-recently-used order.
Package dockerprune keeps the Docker images and build cache of a lab machine under a size: the unused images created or tagged longest ago go first, the ones a kind lab's node holds a copy of last, and the build cache is pruned by Docker's own least-recently-used order.
envtestassets
Package envtestassets provisions the control-plane binaries used by Go tests.
Package envtestassets provisions the control-plane binaries used by Go tests.
execution
Package execution manages owned harness processes on SSH execution hosts.
Package execution manages owned harness processes on SSH execution hosts.
fatal
Package fatal owns the persistent, machine-local outage queue.
Package fatal owns the persistent, machine-local outage queue.
feed
Package feed is the shape of beekeeper://feed: the events of the shared state, each with an id, in a versioned schema the agent views share.
Package feed is the shape of beekeeper://feed: the events of the shared state, each with an id, in a versioned schema the agent views share.
feedback
Package feedback reads the person's replies to the scheduled status reports in Slack: where a report was posted (its slack_send_message result), the replies in its thread (the Slack MCP server's slack_read_thread text) and whom a reply is for.
Package feedback reads the person's replies to the scheduled status reports in Slack: where a report was posted (its slack_send_message result), the replies in its thread (the Slack MCP server's slack_read_thread text) and whom a reply is for.
free
Package free finds what the machine can give back without touching running work and frees it on request: dead sessions' scratch in the tmpfs /tmp, orphaned go-build dirs, throwaway temp dirs and orphaned workers.
Package free finds what the machine can give back without touching running work and frees it on request: dead sessions' scratch in the tmpfs /tmp, orphaned go-build dirs, throwaway temp dirs and orphaned workers.
github
Package github reads the person's GitHub budget: the hourly REST core limit and the GraphQL limit every session, every gh call and the person's own developer portal login draw from, and the per-minute search limits.
Package github reads the person's GitHub budget: the hourly REST core limit and the GraphQL limit every session, every gh call and the person's own developer portal login draw from, and the per-minute search limits.
gocache
Package gocache keeps the Go build cache of the machine's user, which every session's builds share, under a size: the entries used least recently go first, as in Go's own trim, which drops only those unused for five days.
Package gocache keeps the Go build cache of the machine's user, which every session's builds share, under a size: the entries used least recently go first, as in Go's own trim, which drops only those unused for five days.
guard
Package guard keeps builds from taking the machine down.
Package guard keeps builds from taking the machine down.
hypr
Package hypr gives the shared Chrome window a drawn surface for a browse turn under Hyprland and puts it back after: Chrome draws nothing in a window the compositor does not show (on a workspace not shown, under a special workspace shown over its own, behind the front window of a monocle workspace), and a turn's draw checks, screenshots and clicks fail there.
Package hypr gives the shared Chrome window a drawn surface for a browse turn under Hyprland and puts it back after: Chrome draws nothing in a window the compositor does not show (on a workspace not shown, under a special workspace shown over its own, behind the front window of a monocle workspace), and a turn's draw checks, screenshots and clicks fail there.
identity
Package identity is who calls `beekeeper serve`: a person, from the Dex ID token muster forwards (or an installation exchanged), validated against the issuer's JWKS.
Package identity is who calls `beekeeper serve`: a person, from the Dex ID token muster forwards (or an installation exchanged), validated against the issuer's JWKS.
identity/identitytest
Package identitytest is a Dex stand-in for tests: an OIDC issuer that serves its discovery document and keys and signs ID tokens.
Package identitytest is a Dex stand-in for tests: an OIDC issuer that serves its discovery document and keys and signs ID tokens.
install
Package install puts beekeeper in place on a machine and takes it away again: the Claude Code hooks, the platform's standby service and memory guard, and a starter config.
Package install puts beekeeper in place on a machine and takes it away again: the Claude Code hooks, the platform's standby service and memory guard, and a starter config.
issuemonitor
Package issuemonitor keeps issue metadata separate from agent work.
Package issuemonitor keeps issue metadata separate from agent work.
knownhosts
Package knownhosts gives a run's commands a known_hosts file Go's SSH clients can read.
Package knownhosts gives a run's commands a known_hosts file Go's SSH clients can read.
lease
Package lease holds the machine's shared resources, one holder at a time: kind labs, shared installations, the browser.
Package lease holds the machine's shared resources, one holder at a time: kind labs, shared installations, the browser.
loopworkflow
Package loopworkflow is a scratch GitHub and Git origin that exercises a real beekeeper binary across the loop, parser and merge boundary: the integration tests drive every scenario, and a recovery controller's probe drives one on an idle desk.
Package loopworkflow is a scratch GitHub and Git origin that exercises a real beekeeper binary across the loop, parser and merge boundary: the integration tests drive every scenario, and a recovery controller's probe drives one on an idle desk.
machine
Package machine reads the numbers that decide whether the workstation survives the next hour: RAM and swap, memory pressure, the Claude Desktop cgroup, tmpfs and disk, build slots, kind clusters and the kernel's OOM kills.
Package machine reads the numbers that decide whether the workstation survives the next hour: RAM and swap, memory pressure, the Claude Desktop cgroup, tmpfs and disk, build slots, kind clusters and the kernel's OOM kills.
mailbox
Package mailbox is the central instance's message queue: a mailbox per person for the local agents that person federates, in the beekeeper database of the platform's Postgres.
Package mailbox is the central instance's message queue: a mailbox per person for the local agents that person federates, in the beekeeper database of the platform's Postgres.
mailbox/mailboxtest
Package mailboxtest gives a test a database of its own on the Postgres BEEKEEPER_TEST_DATABASE_URL names (docs/development.md starts one).
Package mailboxtest gives a test a database of its own on the Postgres BEEKEEPER_TEST_DATABASE_URL names (docs/development.md starts one).
merge
Package merge is the gate's logic on devctl pr merge: which lane a merge queues in, what holds it, whose turn it is, and when a lane's installation has rolled the previous merge.
Package merge is the gate's logic on devctl pr merge: which lane a merge queues in, what holds it, whose turn it is, and when a lane's installation has rolled the previous merge.
notify
Package notify sends the watch's events that need a person to the desktop notification service, once per event however many watches share the state directory: each event is claimed in notify.json under notify.lock, and only the watch whose claim is first sends it.
Package notify sends the watch's events that need a person to the desktop notification service, once per event however many watches share the state directory: each event is claimed in notify.json under notify.lock, and only the watch whose claim is first sends it.
omp
Package omp finds the omp (oh-my-pi) agents running on the machine and what they are doing, from what is on disk: the omp processes (their working directory, and for an agent beekeeper started its environment) and the session files omp writes under ~/.omp/agent/sessions, one JSON line per entry: a title line (rewritten in place), the session header (id, cwd), model changes, and messages of the roles user, assistant and toolResult.
Package omp finds the omp (oh-my-pi) agents running on the machine and what they are doing, from what is on disk: the omp processes (their working directory, and for an agent beekeeper started its environment) and the session files omp writes under ~/.omp/agent/sessions, one JSON line per entry: a title line (rewritten in place), the session header (id, cwd), model changes, and messages of the roles user, assistant and toolResult.
peer
Package peer sends a message to a running Claude session from the command line.
Package peer sends a message to a running Claude session from the command line.
perfsuite
Package perfsuite is beekeeper's performance test suite: fixed budgets for the CLI calls sessions run most, the supervisor loop's idle pass, concurrent calls on the state lock and the per-session footprint, measured on the real binary against a generated desk of realistic size with fake GitHub and harnesses.
Package perfsuite is beekeeper's performance test suite: fixed budgets for the CLI calls sessions run most, the supervisor loop's idle pass, concurrent calls on the state lock and the per-session footprint, measured on the real binary against a generated desk of realistic size with fake GitHub and harnesses.
platform
Package platform is the one place beekeeper reaches into the machine it runs on: memory, pressure, processes and OOM kills (Machine), detached units of work (Launcher), memory-capped runs (Capper), claude:// links (Opener), the person's input (Input), desktop notifications (Notifier), and the standby service and memory guard beekeeper install puts in place (Setup).
Package platform is the one place beekeeper reaches into the machine it runs on: memory, pressure, processes and OOM kills (Machine), detached units of work (Launcher), memory-capped runs (Capper), claude:// links (Opener), the person's input (Input), desktop notifications (Notifier), and the standby service and memory guard beekeeper install puts in place (Setup).
post
Package post checks a report before it is posted with the Slack connector, whose message is standard Markdown it converts for Slack: that every pull request or issue it mentions is a link to that pull request or issue in its own repository, and that its times are the person's.
Package post checks a report before it is posted with the Slack connector, whose message is standard Markdown it converts for Slack: that every pull request or issue it mentions is a link to that pull request or issue in its own repository, and that its times are the person's.
proc
Package proc reads the Linux process table from /proc once and answers the questions beekeeper asks of it: who is whose parent, which session a process belongs to, how long it has run.
Package proc reads the Linux process table from /proc once and answers the questions beekeeper asks of it: who is whose parent, which session a process belongs to, how long it has run.
proof
Package proof hosts a proof image in its GitHub repository so an issue or pull request thread can show it: one commit on the repository's images-only branch through the Git data API, made with the gh CLI's own login, and a Markdown image line pinned to that commit.
Package proof hosts a proof image in its GitHub repository so an issue or pull request thread can show it: one commit on the repository's images-only branch through the Git data API, made with the gh CLI's own login, and a Markdown image line pinned to that commit.
remotebuild
Package remotebuild runs read-only build commands in reusable, worktree-owned builder Jobs.
Package remotebuild runs read-only build commands in reusable, worktree-owned builder Jobs.
runrecord
Package runrecord formats and reads the run.start / run.end / run.fallback events every beekeeper run writes to the event log, local and remote alike: one record shape, so `beekeeper log --verb run.` and `beekeeper run stats` count builds, their minutes and their failures whichever slot they ran in.
Package runrecord formats and reads the run.start / run.end / run.fallback events every beekeeper run writes to the event log, local and remote alike: one record shape, so `beekeeper log --verb run.` and `beekeeper run stats` count builds, their minutes and their failures whichever slot they ran in.
sandbox
Package sandbox is the agent sandbox: the policy beekeeper renders into Claude Code's managed settings, which Anthropic's sandbox runtime enforces on every command of every session on the machine, and the allow lists beekeeper's PreToolUse hook holds the harness's own file tools to.
Package sandbox is the agent sandbox: the policy beekeeper renders into Claude Code's managed settings, which Anthropic's sandbox runtime enforces on every command of every session on the machine, and the allow lists beekeeper's PreToolUse hook holds the harness's own file tools to.
secret
Package secret is beekeeper secret: the credential operations beekeeper runs in its own process so that no agent reads a value.
Package secret is beekeeper secret: the credential operations beekeeper runs in its own process so that no agent reads a value.
secret/secrettest
Package secrettest is a fake sops and op for the tests of beekeeper secret: its "encryption" is base64 under a sops metadata block, so a test sees a plaintext value on disk as one and secret takes the file for a sops file, and its vault is a map.
Package secrettest is a fake sops and op for the tests of beekeeper secret: its "encryption" is base64 under a sops metadata block, so a test sees a plaintext value on disk as one and secret takes the file for a sops file, and its vault is a map.
sim
Package sim models the desk's flow of an issue from its start to its release as the supervisor loop is meant to run it, simulates that model, measures the real flow from the event log and compares the two: where the real system is slower than the model, what the log names as the cause, and which single change would gain the most released issues per day.
Package sim models the desk's flow of an issue from its start to its release as the supervisor loop is meant to run it, simulates that model, measures the real flow from the event log and compares the two: where the real system is slower than the model, what the log names as the cause, and which single change would gain the most released issues per day.
sink
Package sink dispatches a configured GitHub workflow on selected events (config.Sink): workflow_dispatch with the inputs verb, subject and time, nothing else.
Package sink dispatches a configured GitHub workflow on selected events (config.Sink): workflow_dispatch with the inputs verb, subject and time, nothing else.
sshagent
Package sshagent selects a local SSH agent location for child sessions.
Package sshagent selects a local SSH agent location for child sessions.
state
Package state is beekeeper's shared memory on the machine: the supervisor and its relay, grants, holds, registered agents, notes, timers and session records, one JSON document read and rewritten under an exclusive file lock, plus an append-only event log of every change and of every build run.
Package state is beekeeper's shared memory on the machine: the supervisor and its relay, grants, holds, registered agents, notes, timers and session records, one JSON document read and rewritten under an exclusive file lock, plus an append-only event log of every change and of every build run.
state/kube
Package kube is the Kubernetes store of `beekeeper serve`: the shared state of the Giant Swarm installations as custom resources of beekeeper.giantswarm.io instead of one document under a file lock.
Package kube is the Kubernetes store of `beekeeper serve`: the shared state of the Giant Swarm installations as custom resources of beekeeper.giantswarm.io instead of one document under a file lock.
superloop
Package superloop is the supervisor's fixed procedure as a pure function: beekeeper's events, the roster and the tracked pull requests in, the transitions to take out.
Package superloop is the supervisor's fixed procedure as a pure function: beekeeper's events, the roster and the tracked pull requests in, the transitions to take out.
takeover
Package takeover hands a Claude Code session's permission requests to the person's screen while the screen has taken the session over, and back to the session's own window when it has not.
Package takeover hands a Claude Code session's permission requests to the person's screen while the screen has taken the session over, and back to the session's own window when it has not.
teleport
Package teleport keeps the desk's Teleport login: it reads the active profile's expiry from tsh and renews the login in a staging home, which replaces the profile directory in one exchange once the new login has succeeded.
Package teleport keeps the desk's Teleport login: it reads the active profile's expiry from tsh and renews the login in a staging home, which replaces the profile directory in one exchange once the new login has succeeded.
testenv
Package testenv isolates test binaries from the desk that starts them.
Package testenv isolates test binaries from the desk that starts them.
transcripts
Package transcripts collects, redacts, indexes and searches session transcripts across harnesses (claude, agy, codex, omp) and execution hosts.
Package transcripts collects, redacts, indexes and searches session transcripts across harnesses (claude, agy, codex, omp) and execution hosts.
tui
Package tui is beekeeper's screen for the person: one window over the live state of the machine beekeeper keeps — the sessions and what each is on, the machine's memory and build slots, the leases, holds and merge lanes, the supervisor and guide, the agents, notes and timers, the GitHub budget, the installations' alerts and the event log.
Package tui is beekeeper's screen for the person: one window over the live state of the machine beekeeper keeps — the sessions and what each is on, the machine's memory and build slots, the leases, holds and merge lanes, the supervisor and guide, the agents, notes and timers, the GitHub budget, the installations' alerts and the event log.
update
Package update replaces the running beekeeper with the latest signed release.
Package update replaces the running beekeeper with the latest signed release.
upgrade
Package upgrade detects the release upgrades running on an installation's Cluster API clusters and keeps the automatic holds that stop the installation's merges and lease claims while they run.
Package upgrade detects the release upgrades running on an installation's Cluster API clusters and keeps the automatic holds that stop the installation's merges and lease claims while they run.
worktreeowner
Package worktreeowner reserves worktree paths for the sessions creating them.
Package worktreeowner reserves worktree paths for the sessions creating them.
worktrees
Package worktrees finds the linked git worktrees under the configured roots and tells a finished one (its pull request merged or closed) from one that still holds work.
Package worktrees finds the linked git worktrees under the configured roots and tells a finished one (its pull request merged or closed) from one that still holds work.
pkg
apis/beekeeper/v1alpha1
Package v1alpha1 is the beekeeper.giantswarm.io API: the shared coordination state `beekeeper serve` keeps for the Giant Swarm installations.
Package v1alpha1 is the beekeeper.giantswarm.io API: the shared coordination state `beekeeper serve` keeps for the Giant Swarm installations.
project
Package project carries the build identity of the beekeeper binary: its version, git commit and build time.
Package project carries the build identity of the beekeeper binary: its version, git commit and build time.
Package plugin carries the Claude Code plugin beekeeper ships, the role skills, for the commands that hand them to sessions themselves.
Package plugin carries the Claude Code plugin beekeeper ships, the role skills, for the commands that hand them to sessions themselves.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL