Turn typed Go functions, protobuf RPCs or MCP tools into capabilities a model composes inside a sandbox.
Ordinary tool use makes a model work one call at a time: fifty tasks, fifty round trips, every intermediate result back through the model. Code mode has the model write a program instead. The program loops and filters at machine speed inside a sandbox, and only the final answer returns.
const { todos } = codemode.execute("todos.list", {});
const pending = todos.filter(todo => !todo.completed);
codemode.execute("todos.complete", { id: pending[0].id });
return "completed " + pending[0].title;The sandbox cannot reach your database, network, or secrets. It gets one function, and that function goes back to Go, which checks a generated registry before anything runs.
go get github.com/mukezhz/codemodeThe Go functions you already have are the capabilities; their structs are the schema:
type ListOrders struct {
Status string `json:"status,omitempty" desc:"only orders in this status"`
}
// 1. your code: typed functions, the only place that touches data
source, err := gosource.New(
gosource.Func("orders.list", "Lists orders", gosource.Public(), shop.List, gosource.ReadOnly()),
gosource.Func("orders.refund", "Refunds a paid order", gosource.Roles("support"), shop.Refund, gosource.NeedsApproval()),
)
// 2. per request: only what this caller may call
mode, err := codemode.FromSource(source, capability.Caller{Roles: user.Roles})
// 3. model writes a program, sandbox runs it, the answer comes back as your struct
model, err := llm.NewFromEnv() // ANTHROPIC_API_KEY or OPENAI_API_KEY
runner, err := sandbox.NewFromEnv(sandbox.Options{}) // in-process JS by default
revenue, result, err := agent.RunAs[Revenue](ctx, mode, model, "how much have paid orders brought in?",
agent.Options{Runner: runner, Plans: plans, PlanOwner: user.ID, OnEvent: agent.LogEvents(logger)})
// 4. a refund waits for a person, in your database, until they decide
var pending *agent.Pending
if errors.As(err, &pending) {
// send pending.ID and pending.ExpiresAt to the client; later, on approval:
plan, err := plans.Approve(ctx, mode, user.ID, pending.ID)
}
// every other error is an *agent.Error carrying result.RunID and the stage that failedNo codegen and no switch over RPC names. Every call the program makes is
validated against your structs before your function runs; a bad call goes back
to the model to fix. Access is required on every capability, so nothing is
exposed by omission.
Already describe your API in protobuf, or have MCP servers? They are
sources too, and codemode.Combine serves several at
once. Blank-import the backends you want (llm/claude, sandbox/goja, …);
nothing else is linked. Quickstart builds this
as complete files in ten minutes.
mise install
make demo-todoRuns end to end with no API keys and no database: search falls back to keyword ranking, and a fixed program stands in for the model. Then give a model the pen:
export ANTHROPIC_API_KEY=...
go run ./examples/todo -request "finish anything about docs"For something complete — a task tracker with a web UI, SQLite storage,
twenty-three capabilities, per-user scoping, and charts rendered from a prompt —
see examples/taskreport. Go is the only requirement;
the frontend is built and committed:
go run ./examples/taskreport -serve :8080 \
-base-url https://api.deepseek.com/v1 -api-key sk-... -model deepseek-chatAsk it "what is overdue, and which of it is high priority?" and one model turn produces one program, which returns a document the browser renders as stat cards, a chart, and a table. Works against any OpenAI-compatible endpoint.
Two more show the new pieces in isolation: examples/shop
(the quickstart: typed answer, approved refund) and
examples/combined (Go functions, a proto service
and an MCP server in one program). Each example has a step-by-step README: examples/todo
(no key, no database, also an MCP server for Claude Code) and
examples/taskreport (web UI, roles, rate
limits, audit log). Both run programs in-process by default; add
SANDBOX_ISOLATION=process after make worker to run them in codemode-worker.
Full docs are a VitePress site under docs/.
Get started
- Quickstart — an empty directory to a typed answer and an approved write, in six steps
- Capability sources — Go structs, protobuf, MCP, or several at once · Capabilities from protobuf
- Integration guide — every integration choice, explained
- Adding it to an existing app — a CRM walked through: contract, adapter, roles, tenants, confirmed writes, and a non-Go CRM via a sidecar
Ship it
- Development and production · Running the worker — same binary, different isolation
- What your binary links — the blank imports, and why
- Permissions · Roles and tenants — roles in the contract, rows in your code
- Types and validation · Approving writes · Observability
- Writes and retries · Caching programs
Grow it
How it works
Reference
make docs # serve locally with hot reload
make docs-build # build the static site| Path | What it is |
|---|---|
proto/ |
codemode.proto: the service and method annotations (namespace, description, roles, permissions), embedded for consumers |
registry/ |
Builds a registry from linked descriptors or a Buf descriptor set; CLI in cmd/codemode-registry/ |
gen/ |
Generated Go for codemode.proto. Each example generates into its own tree |
capability/ |
Registry types, validation and the vector index; backends in sqlitestore/ and pgstore/ |
capability/gosource/ |
Capabilities from typed Go functions |
capability/mcpsource/ |
Capabilities from an MCP server's tools |
codemode/ |
The two-method public interface, Search and Execute, and Source / Combine |
llm/ |
The Client interface; providers in claude/ and openai/ |
sandbox/ |
The Runner interface; engines in goja/, starlark/, lua/ |
agent/ |
Search → prompt → model → sandbox, with a repair loop, typed answers and approval plans |
examples/todo/ |
The smallest end-to-end example, also served over MCP |
examples/shop/ |
The quickstart: Go-struct capabilities, a typed answer, an approved refund |
examples/combined/ |
Go functions, a proto service and an MCP server in one program |
examples/taskreport/ |
A complete app: SQLite tasks, 23 typed capabilities, roles, reporting, approval in the chat |
docs/ |
The published documentation site |
notes/ |
Internal writing: PRDs, milestones, decisions. Never published. |
| Command | What it does |
|---|---|
make generate |
Regenerate Go from every proto module and rebuild the example's registry.json |
make test |
Buf lint plus all Go tests |
make test-vector |
SQLite vector search; needs SQLITE_VECTOR_EXTENSION |
make test-consumer |
Checks a consumer links only what it blank-imports |
make test-env |
Checks no library package reads the environment outside env.go |
make test-postgres |
pgvector search against a throwaway container |
make docs |
Serve the documentation site |
Configuration is entirely environment-driven and entirely optional — see
.env.example.
Warning
The default engines run in-process and are not a defence against a determined
attacker. For programs steered by untrusted users, use process isolation (SANDBOX_ISOLATION=process),
and a container for multi-tenant input. See SECURITY.md.