Quick start

Install

go get github.com/force1267/big-brain/pkg/bb

The 60-second demo

A complete, working brain — a persona assistant that just asks a model and replies. No config files, no YAML graph, no plugin system: it's Go.

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()

	// A model backs the "chat" role — a real provider if BIG_BRAIN_API_KEY is
	// set, else a canned reply so this runs with no credentials.
	if os.Getenv("BIG_BRAIN_API_KEY") != "" {
		bb.WithModel(bb.NewModel().WithName("gpt-4o-mini")).WithTag("chat")
	} else {
		bb.WithModel(bb.FixedModel("At your service.")).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
}

Run it:

go run .

Point any OpenAI-compatible client at it:

curl localhost:8080/v1/chat/completions -H 'content-type: application/json' -d '{
  "messages": [{"role": "user", "content": "hello there"}]
}'

Or an Anthropic-compatible one, same brain:

curl localhost:8080/v1/messages -H 'content-type: application/json' -d '{
  "messages": [{"role": "user", "content": "hello there"}]
}'

From the client's side this is an OpenAI (or Anthropic) model. From the inside it's a flow you grow — add a router that Selects capabilities, agents that call tools, memory the brain keeps across turns — none of which the client has to know about.

Environment

Provider credentials come from the environment (12-factor), prefix BIG_BRAIN_:

Variable	Purpose
BIG_BRAIN_API_KEY	Provider API key
BIG_BRAIN_BASE_URL	Override the OpenAI-compatible base URL (self-hosted endpoints, etc.)
BIG_BRAIN_MODEL	Default model name
BIG_BRAIN_DATA	Directory for durable state — makes a brain's durability survive restarts
BIG_BRAIN_TELEMETRY	stdout or otlp to turn on OTel metrics (see Telemetry)

Try the reference brains

Clone the repo and run a complete smart-home assistant with no API key:

git clone https://github.com/force1267/big-brain
cd big-brain
go run ./cmd/jarvis-demo   # smart-home brain: world on :8090, brain on :8080

See Reference brains for what each one demonstrates.

Where to go next

• Mental model — the vocabulary: flow, agent, turn.
• Flows, agents & turns — the full API, with the turn/chat split explained.
• Models & roles — how a model gets resolved and how to register several.