Quickstart

From install to a running loop in a few minutes. For the why behind each step, read Big picture first.

Before you start

tsforge runs shell commands and writes files in the project you point it at. Use it only on repos you trust, or inside a sandbox.

You need Bun ≥ 1.3.14 and an OpenAI-compatible model endpoint (local server or hosted API).

1. Install tsforge

Recommended (install script: Bun if missing, then tsforge from npm or GitHub):

curl -fsSL https://tsforge.dev/install.sh | bash

Or with Bun directly (from npm):

bun install -g @agjs/tsforge

From source (contributors and bleeding edge):

git clone https://github.com/boringstack-xyz/tsforge.git
cd tsforge
bun install
bun link --global --cwd packages/core   # installs `tsforge` on PATH
# or without global link:
bun run tsforge

If tsforge is not found after install, add Bun’s global bin directory to your PATH:

export PATH="$(bun pm bin -g):${PATH}"

2. Configure the model registry

mkdir -p ~/.tsforge
cat > ~/.tsforge/models.json <<'EOF'
{
  "active": "local",
  "models": {
    "local": {
      "baseUrl": "http://localhost:8000/v1",
      "model": "deepseek-v4-flash",
      "thinking": true
    }
  }
}
EOF

Override per-run with TSFORGE_BASE_URL and TSFORGE_MODEL. See Environment variables.

3. Run the CLI

tsforge

Point tsforge at your target project when prompted, or pass --dir. See Interactive CLI for slash commands, flags, and session persistence.

Harness at a glance

flowchart LR
  you(["task"]) --> agent["model agent"]
  agent --> tools["read · edit · run"]
  tools --> gate["gate: tsc + ESLint + tests"]
  gate -->|"fail"| agent
  gate -->|"pass"| done(["checkpoint"])

You give it a task; the model edits; the gate decides done. For the full architecture (the general core, the adapters at the seams, and the request flow), see Big picture.

The loop (short version)

flowchart LR
  task[Approved task] --> agent[Model agent]
  agent --> edit[edit / edit_lines]
  edit --> gate[Gate: tsc + ESLint + …]
  gate -->|fail| repair[Repair loop]
  repair --> agent
  gate -->|pass| done[Checkpoint]

The gate is the acceptance check tsforge builds from your project (How the gate is built). On existing repos the embedded TypeScript language server adds navigation tools and write-time diagnostics (Language server).

What to read next

If you are…	Start here
Still orienting	Big picture
Driving the REPL day to day	Interactive CLI
Building a new full-stack app	Greenfield scaffolding + Greenfield loop
Building a Phaser 4 game	Phaser scaffolding
Running benchmark specs	Spec format
Tuning ESLint enforcement	Stack detection · Rule catalog
Measuring feature wins	A/B testing