builder

The day-0 agentic development harness for togo — and a blueprint you scaffold new projects from.

One command gives you a running Go + TanStack app with a public landing page, JWT/RBAC auth and a seeded admin, an empty dashboard, and — floating over every page — a draggable feedback button. A report becomes an issue on a kanban board. A triage agent classifies it. An orchestrator claims it under a fenced database lease and delegates it to a specialist from a fleet you generated by handing over a plan. That agent runs as a real Claude Code session in an isolated workspace and writes a verdict; the runner, never the agent, derives the facts, runs the gates and opens the PR.

npx create-togo-builder@latest acme     # no Go, no togo installed
togo builder new acme                   # via togo's external command dispatch
togo-builder new acme                   # standalone binary

Status

Phase 0 — foundation. What is real today:

db/migrations/0001_builder_init.sql	30 tables, 9 enums, 70 indexes. Verified against Postgres 14
internal/authz	Wildcard-aware permission checks. togo's Can() is an exact match, so permissions=["*"] denies everything
internal/db/seeders	Idempotent admin seeder — togo ships no way to get a first admin
internal/runner	20 preflight probes; gh auth, claude auth and a live claude -p execution probe are non-skippable
internal/vault	AES-256-GCM with AAD bound to the row identity, so a copied ciphertext fails to decrypt
blueprint/_claude	The shipped agent operating system — rules, agents, skills, guard hooks

Later phases: the issue plane and feedback widget (1), the orchestrator and fleet (2), memory drivers (3), notifications and human-in-the-loop (4).

togo-builder doctor          # run the 20 preflight probes
togo-builder doctor --json   # the same report the setup wizard consumes

The claim mechanism

The concurrency control is one SQL statement — no queue, no broker, no advisory lock. Two runners racing for the same issue cannot both win, because the outer AND status='ready' is a compare-and-swap and RowsAffected() != 1 means you lost.

Three exclusions are enforced by the database rather than by convention:

• human_only = true — agents never claim it
• attempt_count >= max_attempts — a failing issue stops burning budget
• a pending decision on the issue — the human-in-the-loop gate is a NOT EXISTS join, so an agent waiting on an answer is structurally unclaimable

builder_decisions additionally carries CREATE UNIQUE INDEX … WHERE state = 'pending', so an issue can never accumulate two open questions.

Six providers, one install target

togo install togo-framework/builder resolves exactly one togo.plugin.yaml, so builder ships as one repo and one module — but registers six independent kernel providers (vault, brain, notify, issues, fleet, orchestrator). Each is disableable today:

BUILDER_DISABLE=vault,brain togo serve

and extractable to its own repo tomorrow. That property is the point; six repos on day one would mean six release pipelines and a cross-repo version graph before anything runs.

Configuration

Variable	Meaning
DATABASE_URL	Postgres 16+. Falls back to the SQLite dev DSN
BUILDER_VAULT_KEY	32 bytes, base64 or hex. openssl rand -base64 32. Required — a missing key is fatal at boot rather than at first secret read
BUILDER_ADMIN_EMAIL	Seeded administrator
BUILDER_ADMIN_PASSWORD	Non-interactive seeding. There is deliberately no default and no generated-and-printed password
BUILDER_EXEC	local | coder. local is refused outside local development
BUILDER_CLAUDE_BIN	Path to the claude binary
BUILDER_DISABLE	Comma-separated provider short names

Development

go build ./...
go test ./internal/...

# The seeder test needs a real database; it skips without one.
createdb builder_dev
psql -d builder_dev -f db/migrations/0001_builder_init.sql
TEST_DATABASE_URL="postgres://$USER@localhost:5432/builder_dev?sslmode=disable" go test ./internal/db/seeders/

Two things worth knowing before you extend this

Never pass --bare to Claude Code here. It refuses OAuth entirely and accepts only an API key, so it is incompatible with the subscription auth the preflight verifies.

A client-side hook is not a merge gate. guard-merge-gate.sh constrains the agent's own shell, not the GitHub API. The real control is branch protection with required review and required status checks — the hook is defence in depth.

License

MIT

Building from a clone

The plugin module builds normally:

go build ./...

builderd/ — the standalone daemon — does not yet. Its go.mod carries replace directives pointing at sibling checkouts, because the togo plugins it depends on (auth, auth-dev, db-postgres, realtime) are not published yet. It builds inside a workspace that has those repositories side by side, and will build from a clone once they are tagged.

The in-process plugin build has no such dependency and is unaffected.