Guides

Quickstart.

From invite to the first task waiting at the gate. Access is by invite: a personal download link arrives by e-mail. Installation takes a few minutes, and the step that trips people up is the last prerequisite: an agent CLI already signed in and a reachable Postgres.

Before you start

• Node.js 22 or newer. Check with node --version.
• At least one authenticated agent CLI on the machine — claude, codex, kimi, gemini and others. Authenticated for real: for real: T25 invokes the binary you already use; it does not store any key.
• Git. Every task creates a worktree, so the directory has to be a real Git repository.
• Reachable PostgreSQL. Install PostgreSQL 16 or newer, check with psql --version and export DATABASE_URL, for example export DATABASE_URL=postgres://factory:factory@localhost:5432/factory. Without PostgreSQL, neither npm run dev nor t25 create starts.

1. Download and install the private package

Access to T25 is by invite and the package is not published to the public npm registry. The invite arrives by e-mail with a personal download link: the installer downloads the private tarball, verifies the SHA-256 before installing and removes the temporary file when done.

# replace with the data from your invite
export T25_PACKAGE_TARBALL='<private-tarball-url>'
export T25_PACKAGE_SHA256='<tarball-sha256>'
bash ./install.sh

No invite yet? The Request an invite page explains the early evaluators program. Code access is restricted; the evaluator path is the invite one, above.

2. Bring up the cockpit

t25 init
t25 db up                       # or use any reachable Postgres
export DATABASE_URL=postgres://t25:t25@127.0.0.1:5432/t25
t25 upgrade                     # aplica migrations
t25 doctor --evaluation        # evaluator preflight; fails on error-level checks
t25 serve                      # starts at http://localhost:4173

Open http://localhost:4173. The factory state is created under .factory/, on your machine, and is not versioned. Deleting that folder resets everything, which is exactly what you want between experiments.

3. Check the environment

npm run t25 -- doctor --evaluation

doctor --evaluation prints a JSON preflight report for the evaluation program: detectable agent CLIs, Git, version, PostgreSQL client, state_dir, web/dist. It exits with an error if any check is in error. It is the first place to look when something won't start, and once everything is green the next step is your first task.

4. Open the first task

npm run t25 -- create "Add metrics endpoint" \
  --body "Expose latency by route" --type feature --risk medium

The task comes in and moves to SPEC, where it stops: an agent wrote the briefing and is waiting for you to read it. Follow along in the cockpit or with npm run t25 -- list.

5. Approve the briefing and the plan

npm run t25 -- spec TASK-0001          # read the briefing
npm run t25 -- spec-approve TASK-0001  # release for the flight plan
npm run t25 -- approve TASK-0001       # the go/no-go gate

At medium or high risk the task stops again at AWAITING_APPROVAL, this time with the plan and the acceptance criteria. That stop is deliberate: this is where you decide whether the factory carries on.

6. Let it run

After the gate the task goes on by itself through implementation, QA and review, inside its own worktree. When QA or review fails, it goes back to implementation instead of carrying on crooked. At the end the pull request is really opened on GitHub, and the merge is still yours.

npm run t25 -- workspace TASK-0001  # where the task worktree is
npm run t25 -- cleanup TASK-0001    # remove (refuses if there are uncommitted changes)

When something goes wrong

• A stage failed: npm run t25 -- retry TASK-0001.
• You changed your mind: npm run t25 -- cancel TASK-0001.
• No agent available: routing is a preference chain, not a fixed CLI per role. If none of the list is on PATH, the stage does not run — see configuration.

Next Configuration: routing, limits and risk in t25.yaml →