builder

A togo plugin that gives a project an autonomous agent fleet — and a blueprint you scaffold new projects from.

A bug 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 on a real git branch and writes a verdict; the runner, never the agent, derives the facts, runs the gates and opens the PR.

Around that loop: a project brain with provenance, scheduled ingestion sources, a secrets vault, chat, an MCP server and a terminal.

Quickstart

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

togo-builder doctor                     # 20 preflight probes before you rely on it

Minimum environment — copy .env.example to .env:

DATABASE_URL=postgres://localhost:5432/builder_dev?sslmode=disable
BUILDER_VAULT_KEY=$(openssl rand -base64 32)   # required; fatal at boot if missing
BUILDER_ADMIN_EMAIL=you@example.com

The agent loop stays off until BUILDER_RUNNER=1. It spends money.

The two ways to run it

In-process plugin

builder registers into the product's own togo kernel and is served by the product's binary. In the reference host ../builder-dev/, that is port 3000 for the dashboard dev server and port 8080 for the API.

togo install togo-framework/builder

Simple, and wrong for what builder is for: it lives inside the process it observes, so a rebuild, a deploy or a panic takes the issue board down with the product.

→ docs/run-in-process.md

Standalone daemon

builderd/ is builder as its own binary, on port 8099, with its own database (builder_standalone). It serves the SDK shell and iframes the product, so it stays up while the product is rebuilt, deployed or broken. That is its entire purpose.

cd builderd && ./run.sh
curl -s http://localhost:8099/api/health
# {"status":"ok","service":"builderd"}

The dashboard is compiled into the binary and served at http://localhost:8099/builder/ — nothing needs to be checked out or built for it to work, and / redirects there. BUILDER_WEB_DIR is an optional override for developing the dashboard itself.

run.sh resolves BUILDER_VAULT_KEY and AUTH_SECRET from builder-dev/.env and rebuilds the binary.

The service field is what distinguishes the daemon from the product — 8099 is not a reserved port, and a 200 there proves nothing on its own.

→ docs/run-standalone.md

Documentation

Start at docs/README.md — it routes you to one file in one hop.

architecture.md	The eight providers, the package map, the claim mechanism
run-in-process.md	Plugin mode
run-standalone.md	The builderd daemon, the shell, multiple targets
agent-runs-tmux.md	Watching a live run: tmux attach -t builder-issue-<n>-<attempt>
custom-apps.md	Adding a screen without editing builder
brain.md	The project brain — and how good recall really is
sources.md	github, rss, slack, crawl, whatsapp, sql
environment.md	Every BUILDER_* variable, with the file that reads it
http-api.md	The route map
cli.md	togo-builder new | app | doctor | seed | version
troubleshooting.md	The five failures that cost real debugging time

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 independent kernel providers (vault, brain, notify, issues, fleet, orchestrator, sources, apps). Each is disableable today and extractable to its own repo tomorrow:

BUILDER_DISABLE=vault,brain togo serve

One repo per provider on day one would mean as many release pipelines and a cross-repo version graph before anything ran.

Custom apps

builder's ten screens are not the limit. A custom app is an eleventh, added by dropping a directory into apps/ — a manifest and an ES module, discovered at boot. No file in builder names it.

togo-builder app new changelog --title "Changelog" --title-ar "سجل التغييرات"
togo-builder app new metrics --go      # …plus a Go backend that registers via init()
togo-builder app list                  # what would load, and what was rejected

A fleet agent does not need the CLI. list_apps and create_app on the agents MCP server are the same generator reachable from inside a run, so an agent that decides mid-issue the product needs a screen adds one itself and sees it live without a restart. Not on the feedback server — an app ships code the dashboard executes, and the token you wire into a shared editor must not be able to do that.

One broken app costs exactly one tile: a malformed manifest, a missing module or an Init that errors is recorded and skipped, and GET /api/builder/apps/_health says which app and why. An extension point that could take builder down would break the one promise the SDK makes.

→ docs/custom-apps.md · contract in blueprint/_claude/skills/custom-app/SKILL.md

Development

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

builderd/ is a nested module and does not yet build from a bare clone — 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 in a workspace that has them side by side. The in-process plugin build is unaffected.

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