big-brain An agent that disguises
itself as a model.
big-brain wraps LLMs behind standard OpenAI- and Anthropic-compatible APIs. From the outside it's just another model endpoint — every chat UI, IDE plugin, and SDK you already have is a free client. Inside, a request runs through a brain: a tree of flows and agents with memory, tools, routing, and durable execution.
package main
import (
"context"
"os"
"os/signal"
"github.com/force1267/big-brain/pkg/bb"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
bb.WithModel(bb.NewModel().WithName("gpt-4o-mini")).WithTag("chat")
// One agent, one flow: ask the model and reply.
assistant := bb.NewAgent().
WithModel(bb.NewModel("chat")).
WithRole(bb.Role("You are Jarvis: warm, brief, lightly witty."))
brain := bb.NewFlow().WithAgent(assistant)
bb.Serve(ctx, brain) // OpenAI + Anthropic at :8080
}A model call is one line. A brain is a system.
Hand-write the model calls, the prompt templates, the routing, and you get exactly what the reference brains do. The engine earns its place by owning the parts you'd get wrong or forget.
Memory
The brain remembers across turns and decides what to keep — a map, a KV
(bb.MemStore/bb.FileStore), or a vector DB — woven into the persona,
not bolted on as a transcript.
Initiative
A brain keeps acting past the reply. Chain flows after bb.Respond, fire on a
cron with bb.Every, or react to a webhook — durably, so a crash resumes instead
of restarting.
Hands
Tools are just Go. Bind a handler with bb.OnCall and let Resolve
run the loop, or forward a caller's own tools through untouched — nothing is ever
executed implicitly.
Character
Persona, tone, and routing logic live in your agents' roles and handlers — plain Go, not a prompt-template DSL you have to learn.
Composition & concurrency
Select routes to one capability; All/One/Group
run several concurrently; Checkpoint/Wait coordinate agents. Typed
Schema/Extract give you structured output for free.
Durable & observable
Opt a named flow into .Durable() and a crashed run resumes from its last
checkpoint. Every flow start/end, select, and token spent is a trace event at
/v1/diagnostics/trace — for free.
One endpoint. A tree underneath.
A flow runs one or more agents over a chat and hands the result to the next
flow. Flows compose — a Select, an All/One/Group,
or a Next chain — is itself a flow. There is no graph DSL and no node vocabulary
to learn: if is if.
Same wire protocol. A different thing behind it.
bb speaks the exact API your tools already expect — but the honesty stops at the wire.
The usage block it reports is the real sum of every upstream call the brain made,
not a mirror of your prompt.
| Capability | Raw model proxy | Agent orchestration framework | big-brain |
|---|---|---|---|
| Drop-in for existing OpenAI/Anthropic clients | ✓ | usually not | ✓ |
| Memory across turns, author-controlled | — | ✓ | ✓ |
| Durable, resumable execution | — | rare | ✓ |
| Control flow is plain Go, no graph DSL | n/a | usually a DSL/YAML | ✓ |
| Concurrency primitives (Select/All/One/Group) | — | varies | ✓ |
| Faithful passthrough of caller's own tools | ✓ | often reinterpreted | ✓ |
| Zero-config observability of real spend | — | bolt-on | ✓ |
| Embeddable library you own, not a hosted service | — | often a platform | ✓ |
Two reference brains, both pkg/bb-only
Exactly as an external author would write them — no internal shortcuts.
jarvis-demo
A runnable smart-home assistant over a self-contained dummy world (sensors, devices, a notification sink). Runs with no API key.
- Keyword router into talk / remember / recall / house / briefing
- Memory kept across turns
- Concurrent sensor reads via
Group - A
Notifyflow that fires after the reply - Durable execution + a jsonl trace
marvis-demo
The API "goal post" — the program the bb API was designed to make read well.
- An intent router classifies each message with a model + typed schema
Selectdispatches to the matching capability- Annotated line by line in the authoring guide
Read the docs, or hand them to your agent
A full authoring guide, organized by concept, generated statically — plus a single markdown file built for LLM agents that want to write a brain for you.