- You write two inputs: proto files (the API) and SQL migrations (the schema).
forge generateturns them into the Go and TypeScript stubs, the ORM, the CRUD wiring, React Query hooks, mocks, test helpers, the composition graph and the deploy config, in one ordered run. - Each output is either regenerated on every run or written once and then yours. A run never overwrites a file you own, and it stops if you edited one it owns.
- A run that changes nothing records the tree as verified. The next run on the same tree prints
nothing to doand exits in under a second. - Concurrent runs in one checkout queue on
.forge/forge.lockrather than collide. A failed or interrupted run puts back every file it wrote. - For an agent, a feature becomes a few lines of input plus one command. It does not have to read and rewrite eight layers by hand, and it gets a named error when the inputs disagree.
The problem this solves
A typical Go and React app with an RPC API has several layers that all describe the same data: the wire messages, the database structs, the conversions between them, the handler registration, the frontend client and its hooks, test doubles, and the database grants. Each layer is usually generated by a different tool, or written by hand:protoc for stubs, an ORM generator for structs, an OpenAPI generator for the client, a mock generator. A Makefile runs them in some order. The order, what to do when one fails halfway, and whether a hand-edited generated file survives the next run are all left to you.
Each layer is also a place for one change to be missed. Add a column, and someone has to remember the struct, the conversion, the search filter, the read-only grant and the mock data. For a person that is tedium. For an agent it is also context: every layer it has to read and rewrite costs tokens, and every layer it forgets is a bug that compiles.
Forge replaces the stitched toolchain with one command that knows every layer. Two sources of truth explains why the inputs are split into proto and SQL, and Generated vs yours explains how files declare their owner. This page covers the run itself: what it reads, the order of its steps, what it writes, and how it stays safe to run often, in parallel, and on a broken tree.
How it works
Read the diagram left to right. Everything in the first lane is yours, and so is everything in the last. A run rewrites only the regenerated lane. It writes a file in the last lane once, when the file does not exist yet and has never existed, and then leaves it alone. The one exception iscompose.go, where a run adds entries for new components and never touches the expressions you wrote.
The pipeline is a typed list of steps. Each step has a gate that decides whether it applies to this project, and reliant forge generate --dry-run prints the list without running it. On the scratch project used for this page (one catalog service, two tables, one web frontend) the plan has 75 steps, and 70 apply:
Lock, then check whether there is anything to do
Every run that may write the project first takes the project’s lock,.forge/forge.lock. Then it fingerprints the tree and compares it with the last run that verified it (see The nothing to do cache below). If they match, the run stops there. On a machine shared by many agents, a run that has real work also waits for one of the machine’s heavy slots, which it takes before the lock. The cache check needs no slot, so a run with nothing to do never waits behind real work.
Read the inputs and check the forge version
The run loadsforge.yaml, derives the frontend inventory, and loads the hashes that certify each generated file. It refuses to continue if the running forge is not the one forge.yaml pins, because a different forge would rewrite generated files that the pinned one would have left alone (the version check). The file-stomp guard then looks for generated files you have edited. A file that no longer matches its own hash is compared with what this run would write. If the content matches, it is re-recorded. If not, the run fails with one report naming every edited file.
Compile the proto
buf generate writes the Go and Connect stubs into gen/. A forge plugin extracts the services, RPCs and config messages into gen/forge_descriptor/, one file per .proto. Every later step reads that descriptor instead of parsing proto again.
Apply the migrations once
Forge applies every migration indb/migrations/ to a throwaway Postgres and reads the schema back from Postgres’s own catalog. The server is your dev stack’s Postgres when one is reachable, and otherwise an embedded Postgres that needs no Docker. The schema is applied once per run, to a template database, and every step that needs it reads a copy. The --timings output reports this:
Project the app
This is the bulk of the run. The steps join the descriptor with the applied schema:- Entities. An entity is a table in the applied schema whose CRUD RPCs a service declares. For each one, the run writes the ORM row type and store under
internal/db/, and the CRUD wiring and conversions inhandlers_crud_ops_gen.go. The conversions map the fields the message and the table share, by name. What makes an RPC CRUD has the exact rule. - Stubs for what you have not written. An RPC with no handler method gets a stub in its own
rpc_<name>.go, written once. That file is yours from then on. - Frontend. TypeScript stubs, one typed React Query hook per RPC, deterministic mock data per entity, and, the first time an entity appears, its list, detail, create and edit pages.
- Mocks and contracts. A recording mock for every service, and a
mock_gen.gofor every interface in an internal package’s contract. - Per-RPC policy.
pkg/middleware/procedures_gen.golists the RPCs that setauth_required: falseor a timeout.
Wire it together
The composition step resolves every component’sDeps by type and writes graph_gen.go and routes_gen.go. It reconciles compose.go by adding constructor methods and Deps keys that are missing, and it fails, naming the field, when a dependency is missing, ambiguous or cyclic. Contracts and dependency injection covers this in detail, under “How compose.go is reconciled”. The same stage writes the per-service test helpers, embeds the migrations into the binary, writes the read-only role’s grants from the applied schema, and regenerates the KCL config, observability dashboards, CI workflows and seed data.
Tidy, guard and validate
go mod tidy and goimports run over the generated code. Stale generated files from removed inputs are deleted. Then the run checks its own work: it compares any drift with fresh renders, compiles the whole tree with go build, and loads every environment’s KCL. A run is only reported as complete when the tree it leaves builds.
What a run does when it fails
From the first write onward, every file a run writes is journaled with its previous bytes. If any step fails, the build included, or you interrupt the run with Ctrl-C, the run puts every file back. By default it keeps running the steps that do not depend on the failed one, so one run reports every independent error at once.--strict (listed by --help-dev) stops at the first failure instead. This is the end of a run on a migration with a typo in it:
git status was the same before and after that run. The generated sources that failed are kept under .forge/failed-generate/, with the full error in error.txt, so you can read the code the error points at. The next successful run removes them.
A change, end to end
To see the projection at work, add asku column to the products table in a new migration, and the same field to the Product message:
terminal
db/migrations/20261120072110_add_product_sku.up.sql
proto/services/catalog/v1/catalog.proto
reliant forge generate (18 seconds here) changed these files, in addition to the two you edited:
sku is a text column, it also joined the list RPC’s free-text search:
internal/handlers/catalog/handlers_crud_ops_gen.go
frontends/web/src/app/products/ changed. The product pages were written once, when the entity was born, and they are yours now, so showing sku in the form is an edit you make. The same is true of handlers_crud.go and the migration itself.
What this saves an agent
The savings come from what the agent does not have to do, not from a faster model:- It writes inputs, not layers. In the example above, the agent’s whole change was one SQL statement and one proto field. Seven generated files followed. It never reads or writes conversion code, grants or mock data.
- “Did I regenerate?” costs nothing to answer. Running generate on an unchanged tree takes under a second, so an agent can run it whenever it is unsure, instead of reasoning about whether its last edit needs it.
- Mistakes come back named. An edited generated file, a dependency nothing provides, or SQL Postgres rejects each fails the run with the file and the reason. A CRUD RPC with no table generates a handler that returns
Unimplementedrather than a guess. The agent does not have to find the problem by reading generated code. - Parallel agents need no coordination. Two agents in one checkout can both run generate. The second waits for the first and then usually finds nothing to do.
- It can find any symbol without searching.
reliant forge project shapes --grep <Name>lists the RPC, message, table, handler, store and hook withfile:line, because generate put each of them in a known place.
Design decisions and trade-offs
One ordered pipeline instead of a set of generators. Steps share one parsed descriptor and one applied schema, and the order is fixed in code, so a hook never runs before the stubs it needs. The cost is that any input change runs every step. On the scratch project a full run took 18 to 27 seconds, and the time grows with the project. Two memos inside a run reduce it:go mod tidy is skipped for a module whose go.mod, go.sum and imports are what its last tidy left, and the validating build is skipped when every Go build input is byte-identical to one it last passed on.
Read the schema from Postgres instead of parsing SQL. Forge used an in-memory SQLite shadow before, and it broke on the first schema-qualified table name. Applying the migrations to real Postgres means there is nothing to normalize and no dialect to model. The cost is a Postgres server for every run that projects the schema, and about 3 seconds to apply the migrations on this project.
The nothing to do cache
Cache whole runs that change nothing, instead of individual steps. A skip claims exactly one thing: a full run with this forge binary, these tools and this environment, started from this tree, changed nothing. Generate is a function of what it reads, so it would produce the same tree again. Nothing weaker is recorded. A run that wrote files is not evidence, because only the next run can show that the output has settled. So after a change the first run does the work, the second run verifies and records, and the third skips:
go.work and installed node_modules), the outputs the recorded run wrote, local replace targets, the forge executable, every tool generate runs (Go, buf and its plugins, goimports, node, hook commands), the environment variables that steer them, and which Postgres server the schema would be applied to. The cost of this design is that the run right after a change is always a full one, even though it usually writes nothing. A false skip, which would leave stale code that still compiles, is the failure the design ranks above every other, so the cache refuses to skip during a merge or rebase and records only full-strength runs.
The .forge/forge.lock lock
Queue concurrent runs instead of failing them. Two pipelines in one tree would interleave their writes and, worse, their rollbacks: each would restore what it saw before writing, which could be the other run’s fresh output. The second run’s inputs are as valid as the first’s, so it waits and says why:
reliant forge scaffold command takes the same lock for its whole run. The cost is that a run can wait the full length of another agent’s run, 20 seconds in the example above.
Undo a failed run instead of leaving it half written. A run that stopped mid-way used to leave mocks in their pre-goimports form and an ORM file that did not match the code beside it, and the fix was a git checkout that could also discard your own work. The rollback journal makes a failed run cost nothing but its error message. The cost is that a run never leaves partial progress to inspect in place, which is why the failing sources are copied to .forge/failed-generate/ instead.
Limits and what it does not do
- It does not change your files after they exist. Migrations, handler bodies,
rpc_<name>.gofiles,providers.goand the CRUD pages are written once. A new column reaches the generated layers, but not the pages or forms you already have. Generate does not tell you which pages are missing a new field. - It does not write schema changes.
// forge:entitywith barereliant forge scaffoldwrites a table’s first migration only. Every later change is a migration you write. - It does not write access rules. Generated CRUD requires a signed-in caller and does not check who it is. Row scoping is code you write in the handler.
reliant forge project auditlists the RPCs that never look at the caller. - The cache is per checkout.
.forge/generate-cache.jsonis gitignored, so a fresh clone, a new worktree or CI runs in full the first time. The lock is per checkout too: two worktrees each have their own. - The cache has known gaps. A tool that a generate hook runs indirectly (a Makefile target calling an unpinned binary), a hand edit inside
node_modulesthat npm’s lockfile does not record, and a Postgres upgraded in place at the same address can each cause a false skip. Pin hook tools by version.--no-cache, orFORGE_GENERATE_NO_CACHE=1, always runs every step. - It runs only under the pinned forge.
reliant forgehands off to the versionforge.yamlpins, and a mismatched forge refuses to generate. - Narrowed runs skip hooks. A run narrowed with
--stepsor--templates-onlydoes not run the project’s generate hooks, and says so.
See it for yourself
Run these inside any Forge project, for example the one Build a Go and React app with Connect RPC creates. Print the pipeline plan without running it:terminal
--timings (listed by --help-dev) prints where the time went:
terminal
terminal
terminal
Guides
Build a Go and React app with Connect RPC
Create a project and run generate for the first time
Add a database table with a CRUD API and pages
One marked message becomes a migration, RPCs, hooks and pages
Add a custom RPC with typed React hooks
Logic CRUD can’t express, with its stub and hook generated
Expose REST endpoints and an OpenAPI spec
Turn on the OpenAPI step the plan above skips
Build the UI before the backend
Run the frontend on the generated mock data
Reference
- Two sources of truth: proto and migrations, and the rule that makes an RPC CRUD
- Generated vs yours: file headers, drift detection, disowning and rescaffolding
- Contracts and dependency injection:
Deps, mocks andcompose.goreconciliation - Project anatomy: where each kind of file lives
- Adding a feature: the everyday loop of edit, generate, lint and test
- How Forge keeps Postgres migrations safe: what happens to migrations after generate
- The
reliant forgeCLI: version pinning and command reference