bee

module
v0.0.0-...-66492b7 Latest Latest
Warning

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

 Go to latest Published: May 17, 2026 License: MIT

README

🐝 bee

CI Go Reference Go Report Release

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?

Three wedges incumbents miss:

  1. 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.
  2. Skills are bee <name> subcommands. Write a markdown file, get a command. No shell shims. No REPL incantations. bee criticize plan.md just works, from any directory, in any shell.
  3. 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.md is a template — edit the exec: 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) with llama3.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.

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} and linux/{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.

Screenshots

bee run bee skill bee hyperplan

License

MIT.

Directories

Path Synopsis
cmd
bee command
Background-task spawner.
 Background-task spawner.
hltest command
internal
approval
Package approval gates dangerous shell commands behind a user decision.
 Package approval gates dangerous shell commands behind a user decision.
auth
Package auth implements OAuth 2.0 PKCE flow scaffolding for bee.
 Package auth implements OAuth 2.0 PKCE flow scaffolding for bee.
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.
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).
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/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/find
Package find implements the find tool: recursive name-glob file search.
 Package find implements the find tool: recursive name-glob file search.
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/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.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.