Skip to main content
In short
  • You write two inputs: proto files (the API) and SQL migrations (the schema). forge generate turns 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 do and exits in under a second.
  • Concurrent runs in one checkout queue on .forge/forge.lock rather 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 is compose.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:
The stages below follow that order.

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 loads forge.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 in db/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:
A migration Postgres rejects stops the run here, with Postgres’s error and the statement. Because the schema comes from Postgres rather than from a parser, anything Postgres accepts works.

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 in handlers_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.go for every interface in an internal package’s contract.
  • Per-RPC policy. pkg/middleware/procedures_gen.go lists the RPCs that set auth_required: false or a timeout.

Wire it together

The composition step resolves every component’s Deps 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 a sku 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
One reliant forge generate (18 seconds here) changed these files, in addition to the two you edited:
The row type gained the field, the conversions copy it both ways, and the read-only role may now select it. Because sku is a text column, it also joined the list RPC’s free-text search:
internal/handlers/catalog/handlers_crud_ops_gen.go
Nothing under 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 Unimplemented rather 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 with file: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:
That skip took 0.31 seconds. The fingerprint covers the work tree by content, the gitignored files generate reads (such as 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:
The lock is an operating-system file lock, not the file’s existence. The OS releases it when the holder exits, however it exits, so a crashed run never leaves it stuck and there is nothing to delete. Never delete the file: a waiter blocked on the old file and a newcomer that created a new one would both hold “the” lock. Every 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>.go files, providers.go and 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:entity with bare reliant forge scaffold writes 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 audit lists the RPCs that never look at the caller.
  • The cache is per checkout. .forge/generate-cache.json is 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_modules that 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, or FORGE_GENERATE_NO_CACHE=1, always runs every step.
  • It runs only under the pinned forge. reliant forge hands off to the version forge.yaml pins, and a mismatched forge refuses to generate.
  • Narrowed runs skip hooks. A run narrowed with --steps or --templates-only does 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
Run generate twice, then a third time, to watch the run, the verification and the skip. --timings (listed by --help-dev) prints where the time went:
terminal
See how many files forge certifies as its own, and how many it wrote once and handed to you:
terminal
Find every layer one entity produced:
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