Beavers

Overview

Beavers is an engineering teammate that lives in Slack. Mention it in a thread and it answers questions about your repositories using read-only GitHub tools — or, only when a change is explicitly asked for, it hands a structured work order to a coding agent running inside a fresh disposable sandbox, then verifies the outcome with those same read-only tools before replying.

The whole design rests on one split. The agent you talk to can read everything and write nothing. The agent that writes code never talks to you, never runs twice in one request, and never outlives its sandbox. Read-only is structural, not a policy — the GitHub HTTP client has no post, patch, or delete method at all, so the only way to write anything is to cross the delegation boundary, and that boundary is counted.

Everything durable it learns is plain Markdown on disk, versioned by git — no database, no vector store — so when it remembers something wrong, the fix is a commit.

How One Request Runs

• 01Deduped by Slack event id, then admitted through a semaphore capped at four concurrent requests
• 02Placeholder posted in-thread immediately, so the request is visibly accepted
• 03Context assembled from thread replies, cached images, inline reactions, and resolved speaker names
• 04Long-term memory injected in priority order, budgeted to 6 KB of prompt
• 05Tool loop runs up to 12 turns inside a 10-minute deadline, calls from one turn executing concurrently
• 06A second delegation in the same request is refused, telling the model to verify instead
• 07Reply redacted, chunked to 3800 characters, and footed with tokens, tools, duration, and cost
• 08Curation runs after the reply is sent, so it never blocks the answer — and most requests store nothing

Delegation

When a change is actually requested, the front agent doesn't forward the conversation — it writes a validated work order: a summary, one to three repositories each marked primary or dependent, whether each opens a pull request or an issue, the execution order, how the changes link to each other, and an explicit stopping point. One sandbox handles the whole order, so a change spanning two repositories keeps the context it needs while the one-delegation-per-request rule still holds.

The sandbox is created for one task with a hard time ceiling, credentials are written through the file API rather than a shell command, and it is killed in a finally block. A failure returns the last 4 KB of output, not megabytes of build log.

Then the part that matters: the front agent goes back to its read-only tools and checks whether the branch, PR, or issue actually exists in the state the report claims. The agent that did the work is not the agent that grades it.

Architecture Gallery

Fig. 2 — Delegation into a disposable sandbox. Fig. 3 — Three-layer memory with one write gate. Fig. 4 — One request, fully traced and costed.

Memory & Observability

• 01Files render in priority order until the prompt budget is spent; the curator instead sees everything uncapped so it can consolidate
• 02Template scaffolds live in HTML comments, stripped before counting — an unfilled file costs zero budget
• 03Whitespace- or comment-only rewrites touch no disk and create no git revision
• 04Retrieval returns at most five bounded excerpts, each cut back to the nearest heading
• 05A regex plus entropy screen sits at the store layer, so no credential can land in memory
• 06Every write is announced to the owner as a git diff — memory that changes silently is memory you stop trusting
• 07One trace per request with nested spans, and the same redaction runs in the span processor before export
• 08A health endpoint reports memory writability and queue depth — the “volume was never mounted” failure is otherwise silent

Engineering Notes

Every side-effecting dependency sits behind a port — the model, the sandbox, the Slack web and socket clients, the GitHub HTTP layer — with a single composition file as the only place concrete adapters are constructed. That is what lets the 241-test suite run with no network, no Slack workspace, and no sandbox, which in turn is what makes it safe to keep changing an agent whose failure modes are expensive.

It ships as one container. Pushing to main runs typecheck, lint, build, and the full test suite; only then does it build a multi-architecture image, push it to a private registry, and deploy over an SSH key restricted to a single forced command. A deploy that can't start fails loudly instead of reporting success and leaving the old container running.

Delegations that use a refreshable credential are serialized behind a mutex — restored into the sandbox, refreshed, read back, validated, and persisted atomically. Losing a token to a race between two sandboxes is the kind of failure you debug once before deciding to make it impossible.

Not Built Yet

Streaming progress — the port exists and the agent emits events, but nothing subscribes, so a long delegation is silent. Plan mode and an approval gate before write delegations. Test-gated delegation, requiring the coder to run the repository's tests before reporting success. A sandbox warm pool, since every delegation pays a cold CLI install. Hybrid memory search, which is lexical only today, so paraphrases miss. GitHub webhooks for CI-failure explanations and issue triage. And a prompt-injection corpus with an eval harness, so prompt changes stop being a matter of taste.

Technology Stack

Source Code