Bee

Website · Releases

Bee is a persistent workspace your coding agents extend, built on the Wippy runtime. Claude Code, Codex, Antigravity, Grok, Muse and OpenCode run as sessions with their own live terminal windows, next to a shell, your applications and Needs you, where every decision waits for you. Agents drive other agents and build applications that you and they both use, and bees on all your machines join one hive.

Important

Bee is alpha software. Contracts still change between releases.

Features

• Every coding agent in one workspace: Claude Code, Codex, Antigravity, Grok, Muse and OpenCode run as sessions with live terminal windows; close a window and the agent keeps working.
• Agents drive agents: a scoped MCP server lets any agent open other agents' sessions, send them work, wait for results and talk on durable threads.
• Bring your own MCP client: in the folder of a running Bee in this machine's hive (bee hive init), bee mcp connect --name "Terminal Claude" pairs a client through Needs you and prints Claude Code and Codex configuration once; Agents → MCP clients → Revoke cuts access.
• Apps built on demand: ask in plain words and an agent builds a real Wippy application: a terminal UI for you, tools for agents, its own SQLite database with migrations, and Lua tests it runs inside Bee.
• One approval, exact permissions: an app asks for only what it needs, such as a database, agent tools, one HTTP origin or one command in a folder; Needs you shows what it can do and what data it changes, and nothing is decided twice.
• Library: apps and drivers your agents made, versions other bees share and Hub packages in one place, with updates, history, going back and removing while keeping data.
• Bees on every machine: bee hive invite and bee hive join connect machines across LAN, Tailscale and WSL; displays open any bee's desktops and apps install across the hive with each bee's own approval.
• Agent-written drivers: agents can add support for another CLI agent as a driver you approve.
• Docs inside: agents read Bee's documentation offline and search the live Wippy docs before they guess.
• Local and in Docker: agents run natively or in Docker as your own user, with private homes and granted folders only.
• Durable: sessions, threads, approvals and apps survive restarts; a session resumes where it stopped.
• Single binary: Linux and macOS, amd64 and arm64, verified install with one command.

Install

Linux and macOS, amd64 and arm64:

curl -fsSL https://bee.wippy.ai/install.sh | sh

The installer requires curl, tar, and sha256sum or shasum. It takes the latest stable release, verifies its SHA-256 checksum and puts bee in ~/.local/bin. Add that directory to your shell's command search path if needed. To select a release, including an alpha version:

curl -fsSL https://bee.wippy.ai/install.sh | sh -s -- --version VERSION

Use

cd my-project
bee

Each folder runs its own Bee node with its own state. Agents starts an agent: N picks one, Enter opens it in a window, H runs it headless. Closing a window leaves the agent running; reopen it from Agents. X closes a session.

Open an agent directly:

bee claude
bee codex
bee agy
bee grok
bee muse
bee opencode

Desktop keys: Alt+Tab switches windows, Alt+F9 minimizes, F11 maximizes, Ctrl+W closes the focused app, Ctrl+Q leaves the desktop.

Command	What it does
bee	Open this folder's desktop
bee NAME	Open an app by its command name, such as bee claude
bee client	Display a running node's desktops
bee node	Run this folder's node without a display
bee hive init	Join every Bee node on this machine into one hive
bee hive invite	Print a token that joins another machine to this hive; it is single use and valid ten minutes to join, and a joined machine stays in the hive. Keep it running until the other machine joins
bee hive join TOKEN	Join this machine to the hive the token names; bees already running restart themselves into it
bee help	Show the commands
bee gov revert OWNER	Restore an installed application's previous version from the command line

Agents working together

Every agent reaches Bee through a scoped MCP server. With it, an agent opens other agents' sessions, sends them work, waits for or joins their results, and closes them. Permission prompts and approvals from every session land in Needs you.

Applications made by agents

Ask an agent for a tool and it builds a real Wippy application: a terminal window for you, tools other agents call, its own database with migrations, and Lua tests it runs inside Bee. An application asks for exactly what it needs, such as a database, agent tools, one HTTP origin or one exact command in a folder. Needs you shows one install question that names who made it, what it can do and what data it changes; approve it and the application opens from Start. Agents can also write drivers for other CLI agents the same way.

Library lists everything you can install: applications and drivers your agents made, versions other bees in your hive share, and Hub packages. It shows updates and history, goes back to an earlier version, and removes an application while keeping its data.

Bee updates

Settings → About checks the installed Bee pack against Hub. Library reviews and applies the update. Compatible Lua updates keep the running executable; a different runtime or a newer required native module reports needs a newer Bee binary. Install a newer binary with the installer when that happens.

Release packs use 0.2.0-alpha.N. Each GitHub release includes bee-<version>.wapp and its SHA-256 checksum, containing the same pack the release binaries embed. On a publishing machine with the pinned Wippy toolchain and an existing wippy auth login, run make hub-publish VERSION=<version> to verify and publish that asset to bee/bee.

Bees on every machine

bee hive invite          # on a machine whose bees should be shared
bee hive join TOKEN      # on the other machine

The token is single use and valid ten minutes to join; the joined machine stays in the hive and every bee on it joins on its own, across LAN, Tailscale and WSL. Displays open any bee's desktops, and an application one bee shares installs on another with that bee's own approval.

Documentation

Bee carries its documentation inside the binary, so agents read it offline through the docs MCP tool and can also search the live Wippy docs. The same pages are in src/corpus; start with the documentation map. For building applications, read application contracts, delivery and the terminal toolkit.

Repository ownership

Path	Owns
src/	Lua application and registry definitions; folders follow bee.<path> namespaces
tests/lua/	Suites under the source namespace they exercise, with bee.tests.<path> IDs; shared fixtures in support/
tests/fixtures/	External executables, composed resources and historical-ID fixtures
tests/runner/, tests/python/	Python test harness and its unit tests; measured budgets and shard costs in tests/runner/data/
native/	Go host integration, Hive handshake, hook posting and OS facts
build/	Pinned toolchains, packing, release and CI tooling
.github/	CI workflows and setup action
assets/	README artwork
tools/corpus.py	Embedded documentation generation and validation

src/app provides shared application clients and protocols; src/apps owns built-in Help, Library, Processes, Settings and Terminal applications. src/docs implements documentation readers and tools; src/corpus contains the authored and generated content they serve, and is not a registry namespace.

Source namespace (bee. prefix)	Owns
root, deps, env, security	Host composition, boot dependencies, environment resources and host policies
approvals, capability, resources, credentials	Approval decisions and inbox, capability vocabulary, resource grants and credential lifecycle
driver, harness, harness.permission.external	Provider adapters; agent launch, carrier, profiles and permissions; external permission answers
placement, git.worktree, process	Native/Docker placement, worktree lifecycle and shared process infrastructure
threads	Durable records, sessions, delivery, hooks and orchestration
gateway	Agent tools, external interfaces, authorization and publication
gov, hub	Governed activation and grants; package inspection, lifecycle and publication
hive, sync	Distributed routing, exposure, distribution and replica persistence
node, shell, ui	Application instances and workspace settings; desktop shell; shared terminal widgets
persist, values	SQL helpers and startup state compatibility; shared bounds, canonicalization, replies and clocks

Within a feature, app owns its UI, binding its entry adapters, service its orchestration, persist its storage, and migrations its historical schema steps. Applied migration IDs and persisted registry IDs remain stable when organizing files. The approval binding composes request, decision, effect, query, retention and lease owners through bee.approvals.binding:service. The gateway binding composes listener, admission, credential, surface, capability and hook intake owners through bee.gateway.binding:gateway. Their method entries retain the same IDs; internal libraries own the implementation and shared record types.

Root wippy.yaml, .wippy.yaml, wippy.lock and wippy.build.json describe the package, workspace, dependency lock and pinned build respectively. Makefile exposes build/test commands; install.sh installs releases. src/corpus/manifest.json and generated reference pages come from make agent-corpus-local. Build identity (src/env/identity/_index.yaml), fixture composition and copied fixture sources, wippy.build.local.json, .wippy/, .bee/ and dist/ are generated or local state, not authored code.

Build

Build on Linux or macOS with Git, Make, Python 3.10 or newer, Go, and a C/C++ compiler. The Go toolchain version is pinned in wippy.build.json; Go can fetch that version automatically. Install the Python dependencies, then build:

python3 -m venv .wippy/venv
. .wippy/venv/bin/activate
python3 -m pip install -r tests/requirements.txt
make tools
make build
./dist/bee

make tools builds the pinned runtime, native modules and builder once per platform and build configuration, then links the verified tools from ~/.cache/bee-tools/<key>/ into .wippy/bin. make tools-key prints that key. Cached tools also work from a source archive. make build lints and packs the application, records its checksum and compiles dist/bee. Build identity records Git HEAD, or unknown in a source archive. make install builds and installs the binary in ~/.local/bin, keeping the previous binary as bee.prev.

make runtime-pin RUNTIME_VERSION=<commit> changes the runtime pin and its native Go requirement. make native-pin NATIVE_VERSION=<commit> selects a published commit containing Bee's native packages. For a local runtime checkout, use make tools RUNTIME_SOURCE=<path> and pass the same Make variable to subsequent build commands.

Test

The complete verification gate runs on Linux and requires Docker for the container-placement suites. The process guard uses Linux /proc and subreaper support. Fixture agents use isolated homes and fake provider values.

make lint
make test-python
make check SHARDS=8

make lint checks repository hygiene, the documentation corpus, application source and fixture composition. After documentation edits, regenerate with make agent-corpus-local. make check runs lint, fixture lint, Python runner and build tests, boot checks and all Lua suites, then prints one status line with timing and load. Without an explicit SHARDS value it uses up to four shards, depending on available CPUs. make test TESTS=<substring> selects Lua entries by ID; make test-shard SHARDS=8 SHARD=<1..8> runs one partition of the eight-shard plan.

make hygiene scans tracked working-tree files and reports file:line findings for editorial comments, commented Lua statements, private references and file size limits (65,536 bytes for Lua/Python/Go source; 1,000,000 bytes otherwise). Only assets/bee.gif is exempt from the general file limit. Oversized approval files have explicit source-size entries with reason approvals lane in flight until that lane completes; no other source-size exceptions are accepted. Domain exceptions in build/hygiene_allowlist.json require a literal path, exact comment or line, and a one-line reason; unused entries fail the check. Lua comment statements are parsed without execution in one batch by a Go helper using the toolchain's pinned github.com/wippyai/go-lua parser. make tools and make hygiene build the helper from native/. The existing CI lint stage runs this same check through make ci-lint.

The Lua suites live in tests/lua/, the packaged harness in tests/runner/, and all Python unit tests in tests/python/. make test-python discovers every Python unit test, including build and release contracts. Runner measurements live in tests/runner/data/. python3 -m tests.runner.compose creates a copy of the application with test-only seams. Each shard has its own state, fixture executables, databases, home and gateway port. The harness pulls required digest-pinned Docker images before starting suite deadlines and records that preparation time separately. Launch suites separate admission, profiles, credentials, provider configuration, recovery, sessions and agent specification boundaries; launch_fixture.lua owns their shared host setup. Hub inspection loads its published package snapshot from tests/fixtures/hub/root_pack.json.gz; composition expands the data into an ignored Lua library, preserving independence from the live registry. Each entry checks for leaked actors, owned OS children, registry entries, durable work, subscriptions and demand owners. Run go test ./... in native/ when changing Go code.

GitHub CI checks pushes to main, pull requests and manual dispatches. It prepares the application once, runs lint and release-build contract checks, boot checks and eight Lua shards on Linux, and combines their results in the Check gate. Platform jobs warm native build caches when required. macOS jobs compile and verify release targets; they do not run the Linux process guard.

python3 -m tests.runner.run --update-durations records entry body and hygiene costs. python3 -m tests.runner.budgets <passing results.json> refreshes measured budgets within the existing deadline limits.

Release

The release workflow runs for v* tags and requires successful main-branch CI on the exact tagged commit. It uses CI's prepared application and pinned platform caches, stamps the version, and builds Linux and macOS binaries for amd64 and arm64. A manual dispatch with dry_run enabled validates the same build and packaging path without publishing.

Each release includes binary tarballs and SHA-256 checksums, plus bee-<version>.wapp and its checksum. The workflow verifies that every binary embeds the same release pack before publishing. To publish that release pack to Hub, use make hub-publish VERSION=<version> with the pinned toolchain and an existing wippy auth login; it verifies and publishes the downloaded asset.

License

Bee code and artwork are MIT. Wippy is MPL-2.0; dependencies keep their own licenses.