README
¶
🐝 bee
bee coding agent harness. Pure Go, single static binary, requires Go 1.26+ to build.
# install (curl | sh)
curl -fsSL https://raw.githubusercontent.com/elhenro/bee/main/install.sh | sh
# or via go install
go install github.com/elhenro/bee/cmd/bee@latest
# or build to your local bin
go build -o ~/.local/bin/bee ./cmd/bee
# use
export OPENROUTER_API_KEY=<your-key>
bee
Why?
So far, I've used claude code, codex, hermes, opencode, openclaw and pi. Each one nails something. None of them felt configurable, minimal, or flexible enough for the way I actually work, and a few gaps kept biting me. bee is the harness that just does it.
Three gaps bee closes:
- Tiny-context friendly, tiny footprint. Caveman-compressed system prompt, three tools, top-k memory. Same harness scales from a 4k-context local Ollama up through small fine-tunes to million-token frontier models. Native omlx (Apple Silicon MLX server) and OpenRouter support out of the box. Shrinks itself when context gets tight.
- Skills are
bee <name>subcommands. Write a markdown file, get a command. No shell shims. No REPL incantations.bee criticize plan.mdjust works, from any directory, in any shell. - Skills are agent endpoints. A prompt, an external command, an MCP server, or an HTTP endpoint — all four are equally callable tools the model can invoke mid-task. Plug a personal-life agent in as a sub-agent (bundled
hermes.mdis a template — edit theexec:line). No IPC dance.
Quick demos
$ bee criticize plan.md # one binary, every skill a subcommand
$ bee run "lint cmd/" # headless, pipeable
$ bee swarm "migrate auth to jwt" # queen + workers
$ bee fan "audit internal/ for cleanup" # parallel fan-out
~/.bee/skills/*.md is your library. Add one, it shows up. First run seeds defaults. Edit one, it lives.
Config
~/.bee/config.toml, sane defaults, set an API key, change models.
Local models
bee runs against any OpenAI-compatible local server. Confirmed working:
- omlx (Apple Silicon MLX server,
localhost:8000/v1) with MLX-quantized coder models — strong tool-calling, low RAM footprint. - Ollama (
localhost:11434/v1) withllama3.1:8b,qwen2.5-coder:7b. - LM Studio (
localhost:1234/v1).
For sub-8k-context models, switch to the tiny profile. --profile is not a CLI flag — set it via env or ~/.bee/config.toml:
BEE_PROFILE=tiny bee run --provider omlx --model Qwen3.6-35B-A3B-4bit -- "..."
# or persist in ~/.bee/config.toml
profile = "tiny"
default_provider = "omlx"
default_model = "Qwen3.6-35B-A3B-4bit"
Caveman mode
Token-compression rules injected into the system prompt. On by default. caveman = "auto" resolves per profile: full on tiny and normal, lite on large.
Force a level regardless of profile:
bee --caveman full # global, any subcommand
bee run --caveman full -- "..." # one-off
# or set caveman = "full" in ~/.bee/config.toml
Disable:
bee --caveman off
# or set caveman = "off" in ~/.bee/config.toml
Explicit value beats profile.
Overnight loop: bee zzz
Hand bee an objective and a budget, walk away, wake up to a branch full of small individually-revertable commits. Each iteration runs one focused change and either commits or git reset --hard rolls back on failure — the working tree never stays dirty. A live TUI shows the iteration ledger (🐝 foraging · 🌼 committed · 🍃 noop · 🥀 reset · 💥 failed), token cost, and a sleeping bee at the bottom. Type to nudge the run mid-flight; /stop exits gracefully after the current iteration, /abort cancels immediately.
bee zzz "tighten error messages across internal/tools" --max-iterations 30
bee zzz --list # past runs
bee zzz --resume # pick up the most recent
bee zzz --worktree "..." # isolate in ~/.bee/zzz/worktrees/<id>
bee zzz --plain # disable the TUI (stdin steering still works)
bee zzz --max-consecutive-fails 5 # tolerance for transient agent stalls
bee zzz --hard-error-retries 5 # retries per iter on provider 5xx etc
bee zzz --notes-tail 5 # cap prior-iter sections echoed into prompts
bee zzz --gc --gc-worktrees # prune old runs and their worktrees
bee zzz --gc --gc-stale-running 168h # also reap runs stuck "running" >7d
Artifacts live in ~/.bee/zzz/runs/<id>/: notes.md per-iter summaries, events.jsonl raw timeline, meta.json run state, blocked-<iter>.patch for any iteration that emitted BLOCKED:. Inspired by gnhf.
Trust model. Commits land unsigned by default, use --sign to opt back in. Pre-commit hooks run unless --no-verify is set. Pushing (--push) is opt-in, and failures are recorded in meta.json so you can tell what reached the remote. --yes/--yolo auto-approves dangerous shell commands, so pair it with --worktree to contain the blast radius. The CLI prints a warning when --yes is used without --worktree.
Parallel agents: bee agents
Spawn many bees at once, each on its own git worktree. The overview reuses the chat input — every submitted message starts a fresh detached agent under ~/.bee/agents/worktrees/<id> on branch agents/<short>. Rows show initial prompt, elapsed, tokens up/down, last thought, locked model. j/k/arrows navigate, l/→/enter opens an agent fullscreen (existing session view), m retries a merge.
bee agents
When an agent ends its turn with DONE: <summary> the coordinator rebases its branch onto main and fast-forwards. Conflicts post a resolution prompt back to the agent via the inbox and flip its row to needs input; auto-retry every 10s or hit m to force a retry. Unmerged worktrees stay highlighted in red until they land.
/model <name> and /provider <name> set the model used for the next spawn (sticky until changed) — mix and match across agents. Killing bee agents does not kill the running children; relaunching reconstructs the overview from ~/.bee/sessions/bg/.
My setup / how I run this
Mac M3 Max (64 GB) -> omlx with an MLX-quantized coder model. Runs fast, handles small tasks reliably, doesn't choke on context. Good enough for day-to-day. Local, private, free once the hardware is paid for.
Platform support
- macOS / Linux — first-class. Static binaries published for
darwin/{amd64,arm64}andlinux/{amd64,arm64}. - Windows — best-effort. The native build runs; the sandbox layer is a stub that re-dispatches through WSL2. Run under WSL2 for production use.
ChatGPT-account provider (opt-in, use at own risk)
The chatgpt provider lets you drive bee with a ChatGPT Plus/Pro/Team subscription via the chatgpt.com Codex backend instead of paying per-token API billing. This reuses a public client_id that targets a first-party OpenAI surface. OpenAI's terms restrict that surface to their own clients — usage may be rate-limited per plan tier and the path can be revoked at any time. Treat this provider as experimental. Use OPENROUTER_API_KEY (or any other provider) for anything you don't want to lose access to. Run /login chatgpt to drive the PKCE flow; the command surfaces this same warning.
Credits
Caveman prompt-compression rules adapted from JuliusBrussee/caveman.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bee
command
`bee agents` subcommand — opens the parallel-agents overview.
|
`bee agents` subcommand — opens the parallel-agents overview. |
|
hltest
command
|
|
|
internal
|
|
|
agents
Package agents drives the "bee agents" parallel-agent mode.
|
Package agents drives the "bee agents" parallel-agent mode. |
|
approval
Package approval gates dangerous shell commands behind a user decision.
|
Package approval gates dangerous shell commands behind a user decision. |
|
ask
Package ask lets a tool pose a multiple-choice question to the user and block until they pick.
|
Package ask lets a tool pose a multiple-choice question to the user and block until they pick. |
|
auth
Package auth implements OAuth 2.0 PKCE flow scaffolding for bee.
|
Package auth implements OAuth 2.0 PKCE flow scaffolding for bee. |
|
bench
Package bench measures how a model+config combination behaves when driving bee through real coding tasks.
|
Package bench measures how a model+config combination behaves when driving bee through real coding tasks. |
|
bgreg
Package bgreg is the per-session status sidecar registry for background bees.
|
Package bgreg is the per-session status sidecar registry for background bees. |
|
caveman
Package caveman injects token-compression rules into the system prompt.
|
Package caveman injects token-compression rules into the system prompt. |
|
commands
Package commands implements a slash-command registry for the bee TUI.
|
Package commands implements a slash-command registry for the bee TUI. |
|
config
Package config holds the bee runtime configuration schema and loader.
|
Package config holds the bee runtime configuration schema and loader. |
|
cost
Package cost tracks per-turn token usage and dollar cost across providers.
|
Package cost tracks per-turn token usage and dollar cost across providers. |
|
goal
Package goal powers the "/goal" completion-condition feature: an agent loop that keeps running turns until a fast model judges a user-specified condition met.
|
Package goal powers the "/goal" completion-condition feature: an agent loop that keeps running turns until a fast model judges a user-specified condition met. |
|
hive
Background-task helpers.
|
Background-task helpers. |
|
jsonmode
Package jsonmode emits NDJSON events for bee's --json output mode.
|
Package jsonmode emits NDJSON events for bee's --json output mode. |
|
knowledge
Package knowledge implements bee's per-project on-disk knowledge store.
|
Package knowledge implements bee's per-project on-disk knowledge store. |
|
llm
claude.go is the native Anthropic Messages provider.
|
claude.go is the native Anthropic Messages provider. |
|
llm/mockprov
Package mockprov is a scripted, deterministic llm.Provider for tests.
|
Package mockprov is a scripted, deterministic llm.Provider for tests. |
|
llm/wire
anthropic_messages.go covers Anthropic's native Messages API (POST /v1/messages, SSE streaming).
|
anthropic_messages.go covers Anthropic's native Messages API (POST /v1/messages, SSE streaming). |
|
loop
Package loop also provides conversation compaction helpers.
|
Package loop also provides conversation compaction helpers. |
|
prompt
Package prompt builds the system prompt for a bee turn.
|
Package prompt builds the system prompt for a bee turn. |
|
safety
Package safety contains defense-in-depth guards for tool calls: secret redaction on tool output, and path / shell-command checks that refuse to read or mutate obviously sensitive targets even when the sandbox allows it.
|
Package safety contains defense-in-depth guards for tool calls: secret redaction on tool output, and path / shell-command checks that refuse to read or mutate obviously sensitive targets even when the sandbox allows it. |
|
sandbox
Package sandbox implements the two-axis sandbox model (Scope x ApprovalMode).
|
Package sandbox implements the two-axis sandbox model (Scope x ApprovalMode). |
|
sentinel
Package sentinel centralizes the loop-control markers an unattended bee agent uses to signal turn outcomes back to the orchestrator.
|
Package sentinel centralizes the loop-control markers an unattended bee agent uses to signal turn outcomes back to the orchestrator. |
|
session
Package session implements append-only JSONL rollouts plus parent-pointer tree reconstruction for bee sessions.
|
Package session implements append-only JSONL rollouts plus parent-pointer tree reconstruction for bee sessions. |
|
skills
Package skills defines skill types and the contract a skill executor satisfies.
|
Package skills defines skill types and the contract a skill executor satisfies. |
|
skills/bundled
Package bundled embeds default skills shipped with the bee binary.
|
Package bundled embeds default skills shipped with the bee binary. |
|
tools
Package tools defines the Tool interface and an in-memory registry.
|
Package tools defines the Tool interface and an in-memory registry. |
|
tools/apply_patch
Package apply_patch implements the unified-diff mutation tool.
|
Package apply_patch implements the unified-diff mutation tool. |
|
tools/ask_user
Package ask_user implements the ask_user tool: the model asks the user a multiple-choice question and blocks on the answer.
|
Package ask_user implements the ask_user tool: the model asks the user a multiple-choice question and blocks on the answer. |
|
tools/codegraph
Package codegraph wraps the external `codegraph` CLI as a bee tool.
|
Package codegraph wraps the external `codegraph` CLI as a bee tool. |
|
tools/edit_diff
Package edit_diff implements the edit_diff tool: literal find/replace.
|
Package edit_diff implements the edit_diff tool: literal find/replace. |
|
tools/escalate
Package escalate implements the escalate tool: the model's explicit exit door when it's stuck and a human should take over.
|
Package escalate implements the escalate tool: the model's explicit exit door when it's stuck and a human should take over. |
|
tools/find
Package find implements the find tool: recursive name-glob file search.
|
Package find implements the find tool: recursive name-glob file search. |
|
tools/godoc
Package godoc implements the godoc tool: query the local Go documentation for a package or symbol via `go doc -short`.
|
Package godoc implements the godoc tool: query the local Go documentation for a package or symbol via `go doc -short`. |
|
tools/grep
Package grep implements the grep tool: recursive regex search.
|
Package grep implements the grep tool: recursive regex search. |
|
tools/hashline_edit
Package hashline_edit implements LINE#ID-anchored file edits.
|
Package hashline_edit implements LINE#ID-anchored file edits. |
|
tools/knowledge_search
Package knowledge_search implements the knowledge_search tool: on-demand lookup of the bee knowledge store from inside an agent turn.
|
Package knowledge_search implements the knowledge_search tool: on-demand lookup of the bee knowledge store from inside an agent turn. |
|
tools/knowledge_write
Package knowledge_write implements the knowledge_write tool: store a record in bee's on-disk knowledge store.
|
Package knowledge_write implements the knowledge_write tool: store a record in bee's on-disk knowledge store. |
|
tools/ls
Package ls implements the ls tool: list a single directory (no recursion).
|
Package ls implements the ls tool: list a single directory (no recursion). |
|
tools/read
Package read implements the read tool: read file or list directory.
|
Package read implements the read tool: read file or list directory. |
|
tools/shell
Package shell implements the shell tool: bash -c execution with timeout and output truncation.
|
Package shell implements the shell tool: bash -c execution with timeout and output truncation. |
|
tools/tool_lookup
Package tool_lookup implements the tool_lookup tool: returns the full schema, description, and prompt snippet of any registered tool by name.
|
Package tool_lookup implements the tool_lookup tool: returns the full schema, description, and prompt snippet of any registered tool by name. |
|
tools/usertool
Package usertool registers user-defined shell-alias tools loaded from [[user_tools]] entries in ~/.bee/config.toml.
|
Package usertool registers user-defined shell-alias tools loaded from [[user_tools]] entries in ~/.bee/config.toml. |
|
tools/write
Package write implements the write tool: overwrite a file inside the workspace root.
|
Package write implements the write tool: overwrite a file inside the workspace root. |
|
tui
Package tui implements bee's interactive Bubbletea interface.
|
Package tui implements bee's interactive Bubbletea interface. |
|
types
Package types holds the agent-owned message and session model.
|
Package types holds the agent-owned message and session model. |
|
update
Package update probes GitHub for new commits on the bee main branch and applies updates by re-running install.sh in a subprocess.
|
Package update probes GitHub for new commits on the bee main branch and applies updates by re-running install.sh in a subprocess. |
|
worktree
Package worktree creates ephemeral `git worktree` checkouts so concurrent agent workers can each mutate files without racing on one shared tree.
|
Package worktree creates ephemeral `git worktree` checkouts so concurrent agent workers can each mutate files without racing on one shared tree. |
|
zzz
Package zzz drives an autonomous overnight loop: clean-git-check → engine.Run → if tree changed, ONE commit; on any failure, git reset --hard back to last known good.
|
Package zzz drives an autonomous overnight loop: clean-git-check → engine.Run → if tree changed, ONE commit; on any failure, git reset --hard back to last known good. |
|
zzz/tui
Package tui drives the bee-zzz live interface: animated sleeping bee at the footer, moon-phase iteration timeline, transcript pane, and a textarea for steering commands (/stop /abort /note <text>).
|
Package tui drives the bee-zzz live interface: animated sleeping bee at the footer, moon-phase iteration timeline, transcript pane, and a textarea for steering commands (/stop /abort /note <text>). |