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,geminiand 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.
-
GitHub CLI (
gh) 2.50 or newer, authenticated.ghopens the PR and reads the checks before the merge. Check withgh --version. Ubuntu'saptpackage is old: install from the official GitHub CLI repository and rungh auth login. -
Reachable PostgreSQL. Install PostgreSQL 16 or newer, check
with
psql --versionand exportDATABASE_URL, for exampleexport DATABASE_URL=postgresql://t25:[email protected]:5432/t25. Without PostgreSQL, neithernpm run devnort25 createstarts.
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>' curl -fsSL https://raw.githubusercontent.com/ai-t25/t25-factory/main/scripts/install.sh | bash
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
If you ran the installer, it has already started the cockpit; skip the block below. Use it only for manual setup without running the installer.
t25 init t25 db up # or use any reachable Postgres export DATABASE_URL=postgresql://t25:[email protected]: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. Tasks, runs and events live in Postgres. Deleting .t25/ removes local overlays and blobs, but does not delete database tasks.
The installer initializes T25, prepares the database, applies migrations and starts t25 serve. Do not rerun initialization commands after using it. For manual setup, use the commands above instead of the installer.
3. Check the environment
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
t25 create "Add metrics endpoint" \ --body "Expose latency by route" --type feature --risk medium
The task remains in RECEIVED until an approved worker runs the pipeline. Register it in this order: t25 worker-bootstrap --project default, t25 worker run --control-plane-url https://<control-plane> --worker-id worker-a, then t25 worker-approve worker-a; the task can then reach SPEC for your approval. Follow it in the cockpit or with t25 list.
Read-only discovery is available at GET /api/v1/projects/:id/discovery; if there is no backlog, submit an objective with POST /api/v1/projects/:id/work-items. T25 should present the WorkItem, spec, plan, criteria and risk before execution. For medium risk, evidence requires REVIEWED; MERGE_READY is required for high or critical risk. Merge is always a human action. PR_OPEN alone is not success.
5. Approve the briefing and the plan
t25 spec TASK-0001 # read the briefing t25 spec-approve TASK-0001 # release for the flight plan 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 T25 carries on.
6. Let it run
After the gate, the task moves through implementation, QA and review in its worktree. When QA or review fails, it returns to implementation instead of moving forward incorrectly. At the end, the pull request is opened for real on GitHub; in a project without GitHub, the flow waits for human local-delivery approval (`LOCAL_APPROVED`). The merge remains yours.
t25 workspace TASK-0001 # where the task worktree is t25 cleanup TASK-0001 # remove (refuses if there are uncommitted changes)
When something goes wrong
- A stage failed:
t25 retry TASK-0001. - You changed your mind:
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.