Commands

Run tsforge

After install:

tsforge
tsforge --dir ./my-app
tsforge "add tests" --files "src/**" --accept "bun test"

From a monorepo checkout (contributors):

bun run tsforge

Environment variables: Environment variables. Interactive usage: Interactive CLI.

Scaffold a new project

tsforge scaffold --dest ./my-app                       # full BoringStack (interactive)
tsforge scaffold --dest ./site --archetype astro       # Astro static site
tsforge scaffold --dest ./my-game --archetype phaser   # Phaser 4 game
tsforge scaffold --dest ./my-app --set WITH_OBSERVABILITY=0 --no-boot

tsforge scaffold stands up a new project: BoringStack (clone → configure → boot), its Astro site, or a Phaser 4 game. Greenfield only; editing an existing repo never scaffolds.

Set up a repo

tsforge setup          # the interactive conventions wizard
tsforge setup --yes    # write the scan's recommendations, no prompts

tsforge setup (or /setup in a session) scans the repo and writes a conventions block to tsforge.config.json so the guardrails match your repo’s taste: interface naming, enums, test layout, component folders. It never weakens the safety floor (no any/as/!, complexity cap, ===), and writes nothing until you Apply. Outside a terminal it prints the proposal and writes nothing unless you pass --yes. See Set up a repo.

Review the change you’re on

tsforge review                 # functional review of the current diff
tsforge review --staged        # only staged changes (pre-commit)
tsforge review --base develop  # diff against an explicit base ref
tsforge review --with-gate     # run the gate first; skip what it already covers

tsforge review reviews the change you’re working on: the working tree (committed and uncommitted edits) vs the auto-detected base (merge-base with main/master). No commit or push required.

It is functional review: logic, regressions, edge cases, and business rules, guided by a built-in senior-review rubric (lenses), with each finding adversarially re-checked against the real code so false positives are dropped. Types, structure, and style are out of scope (the gate covers those). When a tsconfig.json is present it also feeds the reviewer a caller blast-radius signal (who calls each changed export, computed type-exactly) so the regression lens has concrete call sites to check. Exits non-zero if any error-severity finding survives, so it’s CI-usable.

The same review is available inside an interactive session as /review (optionally /review <base> to diff against a specific ref). A review also runs automatically after a task goes green (toggle with TSFORGE_NO_REVIEW); when it surfaces findings, /reviewfix hands them to the agent to address. See Review your changes.

Recipes

tsforge recipes                          # list this repo's recipes
tsforge run api-endpoint "add a route"   # run a saved recipe by name
tsforge run api-endpoint --files lib/**  # ...with a CLI override (CLI wins)

A recipe is declarative JSON in .tsforge/recipes/<id>.json (project) or ~/.tsforge/recipes/<id>.json (global) that composes a run’s options: model, gate, scope, limits, policy mode. See Recipes.

Build a whole app (greenfield)

tsforge --greenfield "build a kanban board" --accept "bun run build"
tsforge --greenfield "..." --notify 'curl -s "$WEBHOOK?s=$TSFORGE_STATUS"'

--greenfield (or a recipe with mode: "greenfield") is the headless whole-app checklist loop: it plans features and drives them to all-green one at a time under .tsforge/greenfield/. It is separate from interactive plan mode, which saves a session-bound plan under .tsforge/worklist/plans/ on approve and continues in the same session (--continue). Each greenfield feature is verified by the gate, the browser oracle, and a reject-by-default judge. --notify <cmd> runs a shell command on completion with the outcome in $TSFORGE_STATUS. See Greenfield builds.

Drive one change, then review it

tsforge "fix the off-by-one in paginate" --accept "bun test" --with-review

--with-review runs the functional review after the gate goes green and feeds any verified findings into a single repair pass, reverting it if it breaks the gate. Also a recipe field (withReview).

Map the repo to prime the agent

tsforge map            # build a structural map of the workspace
tsforge map status     # when it was built, files/hubs, how much drifted
tsforge map forget     # delete it

tsforge map (or /map in a session) builds a deterministic structural map of a TypeScript repo: the directory shape, what each module exports, and the hub modules everything imports. It persists under .tsforge/, and on the next session it’s injected into the agent’s context so it starts oriented instead of exploring from scratch. All compiler facts (no AI guessing, no extra dependencies); it primes future sessions (run /clear to apply mid-session). Best for existing repos; greenfield builds don’t need it.

Trace a run

tsforge trace            # summarize the newest --log run
tsforge trace run.jsonl  # a specific log file

tsforge trace (or /trace in a session) reads a --log ledger and prints a one-screen summary: model/tool calls, policy decisions (allow/ask/deny by risk), gate verdicts, turns-to-green, and the accept rate / cost-per-accepted-change (how many edits stuck vs were reverted). All deterministically, with no model call. See Trace a run.

Merge gate (repo root)

Commands for people working on the tsforge repository itself:

bun run validate   # typecheck + lint + format:check + test — run before every push

Command	Proves
bun run typecheck	strict TypeScript
bun run lint	ESLint on packages
bun run format:check	Prettier
bun test packages	full test suite

Doc generators

bun run rules:build    # regenerate packages/core/RULES.md
bun run rules:docs     # regenerate rule-docs.generated.json

Eval scripts

Run from a cloned tsforge repo (not shipped with the tsforge npm package):

# A/B sweep — compare feature variants
TSFORGE_FEATURE_VARIANTS=git,script bun run eval:sweep

# Compare edit mechanisms across run dirs
bun run eval:benchmark evals/run-a-* evals/run-b-*

See A/B testing.