A platform for running background tasks with a TypeScript SDK, local development, and managed execution.
Trigger.dev maps how tasks execute, then gives each package its development, test, and release steps. The guide also protects retired execution paths, versioned SDK docs, shared dependency versions, and temporary debug code.
├── ├── · imports AGENTS.md ├── .claude │ └── rules │ ├── │ └── ├── .server-changes │ └── ├── apps │ ├── supervisor │ │ └── │ └── webapp │ └── ├── docs │ └── ├── internal-packages │ ├── clickhouse │ │ └── │ ├── database │ │ └── │ └── run-engine │ └── ├── node_modules │ └── agentcrumbs │ └── skills │ └── agentcrumbs │ ├── init │ │ └── SKILL.md · unavailable at this commit │ └── SKILL.md · unavailable at this commit └── packages ├── cli-v3 │ └── ├── core │ └── ├── redis-worker │ └── └── trigger-sdk └──
01 / Verification by change type
Apps and internal packages use typecheck, while public packages use build. The guide also limits those checks to major changes, making its verification policy depend on both location and change size.
Source excerpt starting at line 29.- **Public packages** (`packages/*`): Use `build`.
02 / Contribution etiquette
Changesets and server-change files ship verbatim to users. The guide requires them for noticeable behavior and explicitly excludes internal work, tests, and refactors that do not merit a user-facing note.
Source excerpt starting at line 117.When in doubt, ask a maintainer rather than adding a note by default. An unnecessary entry is noise in the changelog, not a safe default.
03 / Architecture as narrative
The webapp's v3 directory now serves Run Engine 2.0. Legacy V1 branches may only reject or finalize gracefully, preventing an old path name from reviving retired behavior.
Source excerpt starting at line 170.v3 (engine V1: MarQS + Graphile worker) is end-of-life and its execution code has been removed. The `apps/webapp/app/v3/` directory name is historical - everything there now serves V2 (Run Engine 2.0, `@internal/run-engine` + redis-worker). There is no V1 execution path: a `RunEngineVersion` `V1` branch only rejects or finalizes gracefully so v3 clients get a clean 4xx, never a 5xx. Do not reintroduce V1. See `apps/webapp/CLAUDE.md` and `.claude/rules/legacy-v3-code.md`.
04 / Hard prohibitions
The testing section prohibits mocks and provides named testcontainer helpers for Redis, PostgreSQL, and both together. The examples show how test callbacks receive the actual service connection or Prisma client.
Source excerpt starting at line 45.We use vitest exclusively. **Never mock anything** - use testcontainers instead.
05 / Pointing at the source of truth
Zod must use one exact version throughout the monorepo. The guide connects that constraint to runtime incompatibilities when schemas cross package boundaries.
Source excerpt starting at line 137.Zod is pinned to a single version across the entire monorepo. When adding zod to a new or existing package, use the **exact same version** as the rest of the repo - never a different version or a range. Mismatched zod versions cause runtime type incompatibilities (e.g., schemas from one package can't be used as body validators in another).
06 / House vocabulary
Temporary agentcrumbs markers use approved namespaces and must be removed before merge. Review rules account for that lifecycle instead of treating every marker as production code.
Source excerpt starting at line 284.Do not invent new namespaces — pick from this table or ask first.
These instructions explain how to work in Trigger.dev. Modem shows your agents what customers said, who is affected, and what changed.