Comparison

A · Cursor rules · triggerdotdev/trigger.dev B · AGENTS.md · triggerdotdev/trigger.dev

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	3	38	0%
Commands	0	0	25	0%
Section tags	2	1	10	15%

What each file covers

Sections

0 shared · 3 only in A · 38 only in B

− Environment variables and testing
− Legacy run engine vs Run Engine 2.0
− Where to look for code
+ AGENTS.md
+ Build and Development Commands
+ pnpm run docker:full # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling
+ Build packages (required before running)
+ Verifying Changes
+ Apps and internal packages — use typecheck
+ Public packages — use build
+ Testing
+ Testcontainers for Redis/PostgreSQL
+ Code Style
+ Formatting and linting
+ Imports
+ Changesets and Server Changes
+ Dependency Pinning
+ Architecture Overview
+ Request Flow
+ Apps
+ Public Packages
+ Internal Packages
+ v3 (engine V1) removed
+ Documentation
+ Reference Projects
+ Docker Image Guidelines
+ Writing Trigger.dev Tasks
+ SDK Documentation Rules
+ Testing with the hello-world Reference Project
+ Local Task Testing Workflow
+ Step 1: Start Webapp in Background
+ Run from repo root with run_in_background: true
+ Step 2: Start Trigger Dev in Background
+ in your triggerdotdev/references clone
+ Wait for "Local worker ready [node]"
+ Step 3: Trigger and Monitor Tasks via MCP
+ Skill mappings — when working in these areas, load the linked skill file into context.
+ agentcrumbs
+ Namespaces
+ For PR reviewers
+ CLI

Commands

0 shared · 0 only in A · 25 only in B

+ pnpm run docker
+ pnpm run db:migrate
+ pnpm run db:seed
+ pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
+ pnpm run dev --filter webapp
+ pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"
+ pnpm run typecheck --filter webapp
+ pnpm run typecheck --filter @internal/run-engine
+ pnpm run build --filter @trigger.dev/sdk
+ pnpm run build --filter @trigger.dev/core
+ pnpm run test --filter webapp
+ pnpm run test ./src/engine/tests/ttl.test.ts --run
+ pnpm run build --filter @internal/run-engine
+ pnpm run format
+ pnpm run lint:fix
+ pnpm run lint
+ pnpm run changeset:add
+ pnpm exec agentcrumbs collect
+ pnpm exec agentcrumbs tail --app trigger
+ pnpm exec agentcrumbs clear --app trigger
+ pnpm run
+ pnpm add
+ pnpm i
+ pnpm run build --filter trigger.dev
+ pnpm exec agentcrumbs query --app trigger

Section tags

2 shared · 1 only in A · 10 only in B

− security
+ build
+ lint-format
+ code-style
+ architecture
+ testing-strategy
+ git-pr
+ dependencies
+ do-not
+ agent-behaviour
+ docs
setup
test

Line diff

+263 added−28 removed13 unchanged4.7% identical

triggerdotdev/trigger.dev · .cursor/rules/webapp.mdc

@@ −1 @@

1---

2description: Making updates to the main trigger.dev remix webapp

3globs: apps/webapp/**/*.tsx,apps/webapp/**/*.ts

4alwaysApply: false

5---

7The main trigger.dev webapp, which powers it's API and dashboard and makes up the docker image that is produced as an OSS image, is a Remix 2.17.4 app that uses an express server, written in TypeScript. The following subsystems are either included in the webapp or are used by the webapp in another part of the monorepo:

9- `@trigger.dev/database` exports a Prisma 6.14.0 client that is used extensively in the webapp to access a PostgreSQL instance. The schema file is [schema.prisma](mdc:internal-packages/database/prisma/schema.prisma)

10- `@trigger.dev/core` is a published package and is used to share code between the `@trigger.dev/sdk` and the webapp. It includes functionality but also a load of Zod schemas for data validation. When importing from `@trigger.dev/core` in the webapp, we never import the root `@trigger.dev/core` path, instead we favor one of the subpath exports that you can find in [package.json](mdc:packages/core/package.json)

11- `@internal/run-engine` has all the code needed to trigger a run and take it through it's lifecycle to completion.

12- `@trigger.dev/redis-worker` is a custom redis based background job/worker system that's used in the webapp and also used inside the run engine.

14## Environment variables and testing

16In the webapp, all environment variables are accessed through the `env` export of [env.server.ts](mdc:apps/webapp/app/env.server.ts), instead of directly accessing `process.env`.

18Ideally, the `env.server.ts` file would never be imported into a test file, either directly or indirectly. Tests should only imported classes and functions from a file matching `app/**/*.ts` of the webapp, and that file should not use environment variables, everything should be passed through as options instead. This "service/configuration" separation is important, and can be seen in a few places in the code for examples:

20- [realtimeClient.server.ts](mdc:apps/webapp/app/services/realtimeClient.server.ts) is the testable service, and [realtimeClientGlobal.server.ts](mdc:apps/webapp/app/services/realtimeClientGlobal.server.ts) is the configuration

22Also for writing tests in the webapp, checkout our [tests.md](mdc:ai/references/tests.md) guide

24## Legacy run engine vs Run Engine 2.0

26We originally the Trigger.dev "Run Engine" not as a single system, but just spread out all over the codebase, with no real separate or encapsulation. And we didn't even call it a "Run Engine". With Run Engine 2.0, we've completely rewritten big parts of the way the system works, and moved it over to an internal package called `@internal/run-engine`. So we've retroactively named the previous run engine "Legacy run engine". We're focused almost exclusively now on moving to Run Engine 2.0 and will be deprecating and removing the legacy run engine code eventually.

28## Where to look for code

30- The trigger API endpoint is [api.v1.tasks.$taskId.trigger.ts](mdc:apps/webapp/app/routes/api.v1.tasks.$taskId.trigger.ts)

31- The batch trigger API endpoint is [api.v1.tasks.batch.ts](mdc:apps/webapp/app/routes/api.v1.tasks.batch.ts)

32- Setup code for the prisma client is in [db.server.ts](mdc:apps/webapp/app/db.server.ts)

33- The run engine is configured in [runEngine.server.ts](mdc:apps/webapp/app/v3/runEngine.server.ts)

34- All the "services" that are found in app/v3/services/\*_/_.server.ts

35- The code for the TaskEvent data, which is the otel data sent from tasks to our servers, is in both the [eventRepository.server.ts](mdc:apps/webapp/app/v3/eventRepository.server.ts) and also the [otlpExporter.server.ts](mdc:apps/webapp/app/v3/otlpExporter.server.ts). The otel endpoints which are hit from production and development otel exporters is [otel.v1.logs.ts](mdc:apps/webapp/app/routes/otel.v1.logs.ts) and [otel.v1.traces.ts](mdc:apps/webapp/app/routes/otel.v1.traces.ts)

36- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/\*_/_.server.ts

38- All the "services" that are found in app/v3/services/\*_/_.server.ts

39- The code for the TaskEvent data, which is the otel data sent from tasks to our servers, is in both the [eventRepository.server.ts](mdc:apps/webapp/app/v3/eventRepository.server.ts) and also the [otlpExporter.server.ts](mdc:apps/webapp/app/v3/otlpExporter.server.ts). The otel endpoints which are hit from production and development otel exporters is [otel.v1.logs.ts](mdc:apps/webapp/app/routes/otel.v1.logs.ts) and [otel.v1.traces.ts](mdc:apps/webapp/app/routes/otel.v1.traces.ts)

40- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/\*_/_.server.ts

triggerdotdev/trigger.dev · AGENTS.md

@@ +1 @@

1# AGENTS.md

3This file provides guidance to Claude Code when working with this repository. Subdirectory CLAUDE.md files provide deeper context when you navigate into specific areas.

5## Build and Development Commands

7This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`.

9**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.

11```bash

12pnpm run docker # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite)

13# pnpm run docker:full # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling

14pnpm run db:migrate # Run database migrations

15pnpm run db:seed # Seed the database (required for reference projects)

17# Build packages (required before running)

18pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk

20pnpm run dev --filter webapp # Run webapp (http://localhost:3030)

21pnpm run dev --filter trigger.dev --filter "@trigger.dev/*" # Watch CLI and packages

22```

24### Verifying Changes

26The verification command depends on where the change lives:

28- **Apps and internal packages** (`apps/*`, `internal-packages/*`): Use `typecheck`. **Never use `build`** for these — building proves almost nothing about correctness.

29- **Public packages** (`packages/*`): Use `build`.

31```bash

32# Apps and internal packages — use typecheck

33pnpm run typecheck --filter webapp # ~1-2 minutes

34pnpm run typecheck --filter @internal/run-engine

36# Public packages — use build

37pnpm run build --filter @trigger.dev/sdk

38pnpm run build --filter @trigger.dev/core

39```

41Only run typecheck/build after major changes (new files, significant refactors, schema changes). For small edits, trust the types and let CI catch issues.

43## Testing

45We use vitest exclusively. **Never mock anything** - use testcontainers instead.

47```bash

48pnpm run test --filter webapp # All tests for a package

49cd internal-packages/run-engine

50pnpm run test ./src/engine/tests/ttl.test.ts --run # Single test file

51pnpm run build --filter @internal/run-engine # May need to build deps first

52```

54Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`).

56### Testcontainers for Redis/PostgreSQL

58```typescript

59import { redisTest, postgresTest, containerTest } from "@internal/testcontainers";

61redisTest("should use redis", async ({ redisOptions }) => {

62 /* ... */

63});

64postgresTest("should use postgres", async ({ prisma }) => {

65 /* ... */

66});

67containerTest("should use both", async ({ prisma, redisOptions }) => {

68 /* ... */

69});

70```

72## Code Style

74### Formatting and linting

76Format and lint are enforced by CI (`code-quality` check). Run before committing:

78```bash

79pnpm run format # oxfmt — auto-fixes formatting

80pnpm run lint:fix # oxlint — auto-fixes lint violations

81pnpm run lint # oxlint — check only (no fixes)

82```

84### Imports

86**Prefer static imports over dynamic imports.** Only use dynamic `import()` when:

87- Circular dependencies cannot be resolved otherwise

88- Code splitting is genuinely needed for performance

89- The module must be loaded conditionally at runtime

91Dynamic imports add unnecessary overhead in hot paths and make code harder to analyze. If you find yourself using `await import()`, ask if a regular `import` statement would work instead.

93## Changesets and Server Changes

95When modifying any public package (`packages/*` or `integrations/*`), add a changeset:

97```bash

98pnpm run changeset:add

99```

100

101- Default to **patch** for bug fixes and minor changes

102- Confirm with maintainers before selecting **minor** (new features)

103- **Never** select major without explicit approval

104

105When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation.

106

107**Write the description for users, not maintainers.** Both changesets and `.server-changes/` notes ship verbatim in user-visible release notes. Lead with what changed *for the user* - one plain sentence describing behavior, not implementation, and never naming internal tools or infra. The full writing guidance in `.server-changes/README.md` applies to changesets too.

108

109## Dependency Pinning

110

111Zod is pinned to a single version across the entire monorepo (currently `3.25.76`). 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).

112

113## Architecture Overview

114

115### Request Flow

116

117User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state)

118

119### Apps

120

121- **apps/webapp**: Remix 2.17.4 app - main API, dashboard, orchestration. Uses Express server.

122- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes).

123

124### Public Packages

125

126- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks

127- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images

128- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root).

129- **packages/build** (`@trigger.dev/build`): Build extensions and types

130- **packages/react-hooks**: React hooks for realtime and triggering

131- **packages/redis-worker** (`@trigger.dev/redis-worker`): Redis-based background job system

132

133### Internal Packages

134

135- **internal-packages/database**: Prisma 6.14.0 client and schema (PostgreSQL)

136- **internal-packages/clickhouse**: ClickHouse client, schema migrations, analytics queries

137- **internal-packages/run-engine**: "Run Engine 2.0" - core run lifecycle management

138- **internal-packages/redis**: Redis client creation utilities (ioredis)

139- **internal-packages/testcontainers**: Test helpers for Redis/PostgreSQL containers

140- **internal-packages/schedule-engine**: Durable cron scheduling

141

142### v3 (engine V1) removed

143

144v3 (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`.

145

146### Documentation

147

148Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for conventions.

149

150### Reference Projects

151

152Reference/example projects for testing SDK and platform features live in a separate repo: [`triggerdotdev/references`](https://github.com/triggerdotdev/references). Clone it alongside this repo and use its `projects/hello-world` to manually test changes before submitting PRs. See that repo's README for setup and linking to a local monorepo build.

153

154## Docker Image Guidelines

155

156When updating Docker image references:

157

158- **Always use multiplatform/index digests**, not architecture-specific digests

159- Architecture-specific digests cause CI failures on different build environments

160- Use the digest from the main Docker Hub page, not from a specific OS/ARCH variant

161

162## Writing Trigger.dev Tasks

163

164Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob`.

165

166```typescript

167import { task } from "@trigger.dev/sdk";

168

169export const myTask = task({

170 id: "my-task",

171 run: async (payload: { message: string }) => {

172 // Task logic

173 },

174});

175```

176

177### SDK Documentation Rules

178

179The `rules/` directory contains versioned SDK documentation distributed via the SDK installer. Current version: `rules/manifest.json`. Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked - these are maintained in separate dedicated passes.

180

181## Testing with the hello-world Reference Project

182

183The reference projects live in the separate [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo - clone it alongside this repo.

184

185First-time setup:

186

1871. `pnpm run db:seed` to seed the database (creates the References org + hello-world project)

1882. Build the CLI/packages you want to test: `pnpm run build --filter trigger.dev`

1893. In your `references` clone, follow its README to link to your local monorepo build, then authorize: `cd projects/hello-world && pnpm exec trigger login -a http://localhost:3030`

190

191Running (from your `references` clone): `cd projects/hello-world && pnpm exec trigger dev`

192

193## Local Task Testing Workflow

194

195### Step 1: Start Webapp in Background

196

197```bash

198# Run from repo root with run_in_background: true

199pnpm run dev --filter webapp

200curl -s http://localhost:3030/healthcheck # Verify running

201```

202

203### Step 2: Start Trigger Dev in Background

204

205```bash

206# in your triggerdotdev/references clone

207cd projects/hello-world && pnpm exec trigger dev

208# Wait for "Local worker ready [node]"

209```

210

211### Step 3: Trigger and Monitor Tasks via MCP

212

213```

214mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev")

215mcp__trigger__trigger_task(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskId: "hello-world", payload: {"message": "Hello"})

216mcp__trigger__list_runs(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskIdentifier: "hello-world", limit: 5)

217```

218

219Dashboard: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs

220

221

222

223# Skill mappings — when working in these areas, load the linked skill file into context.

224

225skills:

226

227- task: "Using agentcrumbs for debug tracing, adding crumbs, trails, markers, querying traces, or stripping debug code before merge"

228 load: "node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md"

229- task: "Setting up agentcrumbs in the project, initializing namespace catalog, running crumbs init"

230 load: "node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md"

231

232

233## agentcrumbs

234

235Add crumbs as you write code — not just when debugging. Mark lines with

236`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the

237branch throughout development and are stripped by `agentcrumbs strip`

238before merge.

239

240### Namespaces

241

242| Namespace | Description | Path |

243| ----------------- | ---------------------------------------------- | ----------------------------------- |

244| `webapp` | Main Remix app — API, dashboard, orchestration | `apps/webapp` |

245| `supervisor` | Task execution container manager | `apps/supervisor` |

246| `sdk` | Main SDK for writing tasks | `packages/trigger-sdk` |

247| `cli` | CLI and task image bundling | `packages/cli-v3` |

248| `core` | Shared types and subpath exports | `packages/core` |

249| `build` | Build extensions and types | `packages/build` |

250| `react-hooks` | React hooks for realtime/triggering | `packages/react-hooks` |

251| `redis-worker` | Redis-based background job system | `packages/redis-worker` |

252| `run-engine` | Run Engine 2.0 — core run lifecycle | `internal-packages/run-engine` |

253| `database` | Prisma client and schema | `internal-packages/database` |

254| `clickhouse` | ClickHouse client, migrations, analytics | `internal-packages/clickhouse` |

255| `schedule-engine` | Durable cron scheduling | `internal-packages/schedule-engine` |

256| `run-queue` | Run queue management | `internal-packages/run-queue` |

257

258Do not invent new namespaces — pick from this table or ask first.

259

260### For PR reviewers

261

262Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs

263imports in reviews. These are temporary debug instrumentation stripped

264before merge. Data logged in crumbs (IDs, names, values) never reaches

265production.

266

267### CLI

268

269```bash

270pnpm exec agentcrumbs collect # start collector (multi-service)

271pnpm exec agentcrumbs tail --app trigger # live tail

272pnpm exec agentcrumbs clear --app trigger # remove crumbs before merge

273```

274

275The preferred way to query for crumbs is to use `pnpm exec agentcrumbs query --app trigger` with the `--limit` option and cursor pagination, and clear existing crumbs before reproducing a bug via `pnpm exec agentcrumbs clear --app trigger`.

276

@@ −1 +1 @@

1−---

2−description: Making updates to the main trigger.dev remix webapp

3−globs: apps/webapp/**/*.tsx,apps/webapp/**/*.ts

4−alwaysApply: false

5−---

1+# AGENTS.md

7−The main trigger.dev webapp, which powers it's API and dashboard and makes up the docker image that is produced as an OSS image, is a Remix 2.17.4 app that uses an express server, written in TypeScript. The following subsystems are either included in the webapp or are used by the webapp in another part of the monorepo:

3+This file provides guidance to Claude Code when working with this repository. Subdirectory CLAUDE.md files provide deeper context when you navigate into specific areas.

9−- `@trigger.dev/database` exports a Prisma 6.14.0 client that is used extensively in the webapp to access a PostgreSQL instance. The schema file is [schema.prisma](mdc:internal-packages/database/prisma/schema.prisma)

10−- `@trigger.dev/core` is a published package and is used to share code between the `@trigger.dev/sdk` and the webapp. It includes functionality but also a load of Zod schemas for data validation. When importing from `@trigger.dev/core` in the webapp, we never import the root `@trigger.dev/core` path, instead we favor one of the subpath exports that you can find in [package.json](mdc:packages/core/package.json)

11−- `@internal/run-engine` has all the code needed to trigger a run and take it through it's lifecycle to completion.

12−- `@trigger.dev/redis-worker` is a custom redis based background job/worker system that's used in the webapp and also used inside the run engine.

5+## Build and Development Commands

136

14−## Environment variables and testing

7+This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`.

158

16−In the webapp, all environment variables are accessed through the `env` export of [env.server.ts](mdc:apps/webapp/app/env.server.ts), instead of directly accessing `process.env`.

9+**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.

1710

18−Ideally, the `env.server.ts` file would never be imported into a test file, either directly or indirectly. Tests should only imported classes and functions from a file matching `app/**/*.ts` of the webapp, and that file should not use environment variables, everything should be passed through as options instead. This "service/configuration" separation is important, and can be seen in a few places in the code for examples:

11+```bash

12+pnpm run docker # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite)

13+# pnpm run docker:full # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling

14+pnpm run db:migrate # Run database migrations

15+pnpm run db:seed # Seed the database (required for reference projects)

1916

20−- [realtimeClient.server.ts](mdc:apps/webapp/app/services/realtimeClient.server.ts) is the testable service, and [realtimeClientGlobal.server.ts](mdc:apps/webapp/app/services/realtimeClientGlobal.server.ts) is the configuration

17+# Build packages (required before running)

18+pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk

2119

22−Also for writing tests in the webapp, checkout our [tests.md](mdc:ai/references/tests.md) guide

20+pnpm run dev --filter webapp # Run webapp (http://localhost:3030)

21+pnpm run dev --filter trigger.dev --filter "@trigger.dev/*" # Watch CLI and packages

22+```

2323

24−## Legacy run engine vs Run Engine 2.0

24+### Verifying Changes

2525

26−We originally the Trigger.dev "Run Engine" not as a single system, but just spread out all over the codebase, with no real separate or encapsulation. And we didn't even call it a "Run Engine". With Run Engine 2.0, we've completely rewritten big parts of the way the system works, and moved it over to an internal package called `@internal/run-engine`. So we've retroactively named the previous run engine "Legacy run engine". We're focused almost exclusively now on moving to Run Engine 2.0 and will be deprecating and removing the legacy run engine code eventually.

26+The verification command depends on where the change lives:

2727

28−## Where to look for code

28+- **Apps and internal packages** (`apps/*`, `internal-packages/*`): Use `typecheck`. **Never use `build`** for these — building proves almost nothing about correctness.

29+- **Public packages** (`packages/*`): Use `build`.

2930

30−- The trigger API endpoint is [api.v1.tasks.$taskId.trigger.ts](mdc:apps/webapp/app/routes/api.v1.tasks.$taskId.trigger.ts)

31−- The batch trigger API endpoint is [api.v1.tasks.batch.ts](mdc:apps/webapp/app/routes/api.v1.tasks.batch.ts)

32−- Setup code for the prisma client is in [db.server.ts](mdc:apps/webapp/app/db.server.ts)

33−- The run engine is configured in [runEngine.server.ts](mdc:apps/webapp/app/v3/runEngine.server.ts)

34−- All the "services" that are found in app/v3/services/\*_/_.server.ts

35−- The code for the TaskEvent data, which is the otel data sent from tasks to our servers, is in both the [eventRepository.server.ts](mdc:apps/webapp/app/v3/eventRepository.server.ts) and also the [otlpExporter.server.ts](mdc:apps/webapp/app/v3/otlpExporter.server.ts). The otel endpoints which are hit from production and development otel exporters is [otel.v1.logs.ts](mdc:apps/webapp/app/routes/otel.v1.logs.ts) and [otel.v1.traces.ts](mdc:apps/webapp/app/routes/otel.v1.traces.ts)

36−- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/\*_/_.server.ts

31+```bash

32+# Apps and internal packages — use typecheck

33+pnpm run typecheck --filter webapp # ~1-2 minutes

34+pnpm run typecheck --filter @internal/run-engine

3735

38−- All the "services" that are found in app/v3/services/\*_/_.server.ts

39−- The code for the TaskEvent data, which is the otel data sent from tasks to our servers, is in both the [eventRepository.server.ts](mdc:apps/webapp/app/v3/eventRepository.server.ts) and also the [otlpExporter.server.ts](mdc:apps/webapp/app/v3/otlpExporter.server.ts). The otel endpoints which are hit from production and development otel exporters is [otel.v1.logs.ts](mdc:apps/webapp/app/routes/otel.v1.logs.ts) and [otel.v1.traces.ts](mdc:apps/webapp/app/routes/otel.v1.traces.ts)

40−- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/\*_/_.server.ts

36+# Public packages — use build

37+pnpm run build --filter @trigger.dev/sdk

38+pnpm run build --filter @trigger.dev/core

39+```

40+

41+Only run typecheck/build after major changes (new files, significant refactors, schema changes). For small edits, trust the types and let CI catch issues.

42+

43+## Testing

44+

45+We use vitest exclusively. **Never mock anything** - use testcontainers instead.

46+

47+```bash

48+pnpm run test --filter webapp # All tests for a package

49+cd internal-packages/run-engine

50+pnpm run test ./src/engine/tests/ttl.test.ts --run # Single test file

51+pnpm run build --filter @internal/run-engine # May need to build deps first

52+```

53+

54+Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`).

55+

56+### Testcontainers for Redis/PostgreSQL

57+

58+```typescript

59+import { redisTest, postgresTest, containerTest } from "@internal/testcontainers";

60+

61+redisTest("should use redis", async ({ redisOptions }) => {

62+ /* ... */

63+});

64+postgresTest("should use postgres", async ({ prisma }) => {

65+ /* ... */

66+});

67+containerTest("should use both", async ({ prisma, redisOptions }) => {

68+ /* ... */

69+});

70+```

71+

72+## Code Style

73+

74+### Formatting and linting

75+

76+Format and lint are enforced by CI (`code-quality` check). Run before committing:

77+

78+```bash

79+pnpm run format # oxfmt — auto-fixes formatting

80+pnpm run lint:fix # oxlint — auto-fixes lint violations

81+pnpm run lint # oxlint — check only (no fixes)

82+```

83+

84+### Imports

85+

86+**Prefer static imports over dynamic imports.** Only use dynamic `import()` when:

87+- Circular dependencies cannot be resolved otherwise

88+- Code splitting is genuinely needed for performance

89+- The module must be loaded conditionally at runtime

90+

91+Dynamic imports add unnecessary overhead in hot paths and make code harder to analyze. If you find yourself using `await import()`, ask if a regular `import` statement would work instead.

92+

93+## Changesets and Server Changes

94+

95+When modifying any public package (`packages/*` or `integrations/*`), add a changeset:

96+

97+```bash

98+pnpm run changeset:add

99+```

100+

101+- Default to **patch** for bug fixes and minor changes

102+- Confirm with maintainers before selecting **minor** (new features)

103+- **Never** select major without explicit approval

104+

105+When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation.

106+

107+**Write the description for users, not maintainers.** Both changesets and `.server-changes/` notes ship verbatim in user-visible release notes. Lead with what changed *for the user* - one plain sentence describing behavior, not implementation, and never naming internal tools or infra. The full writing guidance in `.server-changes/README.md` applies to changesets too.

108+

109+## Dependency Pinning

110+

111+Zod is pinned to a single version across the entire monorepo (currently `3.25.76`). 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).

112+

113+## Architecture Overview

114+

115+### Request Flow

116+

117+User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state)

118+

119+### Apps

120+

121+- **apps/webapp**: Remix 2.17.4 app - main API, dashboard, orchestration. Uses Express server.

122+- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes).

123+

124+### Public Packages

125+

126+- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks

127+- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images

128+- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root).

129+- **packages/build** (`@trigger.dev/build`): Build extensions and types

130+- **packages/react-hooks**: React hooks for realtime and triggering

131+- **packages/redis-worker** (`@trigger.dev/redis-worker`): Redis-based background job system

132+

133+### Internal Packages

134+

135+- **internal-packages/database**: Prisma 6.14.0 client and schema (PostgreSQL)

136+- **internal-packages/clickhouse**: ClickHouse client, schema migrations, analytics queries

137+- **internal-packages/run-engine**: "Run Engine 2.0" - core run lifecycle management

138+- **internal-packages/redis**: Redis client creation utilities (ioredis)

139+- **internal-packages/testcontainers**: Test helpers for Redis/PostgreSQL containers

140+- **internal-packages/schedule-engine**: Durable cron scheduling

141+

142+### v3 (engine V1) removed

143+

144+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`.

145+

146+### Documentation

147+

148+Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for conventions.

149+

150+### Reference Projects

151+

152+Reference/example projects for testing SDK and platform features live in a separate repo: [`triggerdotdev/references`](https://github.com/triggerdotdev/references). Clone it alongside this repo and use its `projects/hello-world` to manually test changes before submitting PRs. See that repo's README for setup and linking to a local monorepo build.

153+

154+## Docker Image Guidelines

155+

156+When updating Docker image references:

157+

158+- **Always use multiplatform/index digests**, not architecture-specific digests

159+- Architecture-specific digests cause CI failures on different build environments

160+- Use the digest from the main Docker Hub page, not from a specific OS/ARCH variant

161+

162+## Writing Trigger.dev Tasks

163+

164+Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob`.

165+

166+```typescript

167+import { task } from "@trigger.dev/sdk";

168+

169+export const myTask = task({

170+ id: "my-task",

171+ run: async (payload: { message: string }) => {

172+ // Task logic

173+ },

174+});

175+```

176+

177+### SDK Documentation Rules

178+

179+The `rules/` directory contains versioned SDK documentation distributed via the SDK installer. Current version: `rules/manifest.json`. Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked - these are maintained in separate dedicated passes.

180+

181+## Testing with the hello-world Reference Project

182+

183+The reference projects live in the separate [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo - clone it alongside this repo.

184+

185+First-time setup:

186+

187+1. `pnpm run db:seed` to seed the database (creates the References org + hello-world project)

188+2. Build the CLI/packages you want to test: `pnpm run build --filter trigger.dev`

189+3. In your `references` clone, follow its README to link to your local monorepo build, then authorize: `cd projects/hello-world && pnpm exec trigger login -a http://localhost:3030`

190+

191+Running (from your `references` clone): `cd projects/hello-world && pnpm exec trigger dev`

192+

193+## Local Task Testing Workflow

194+

195+### Step 1: Start Webapp in Background

196+

197+```bash

198+# Run from repo root with run_in_background: true

199+pnpm run dev --filter webapp

200+curl -s http://localhost:3030/healthcheck # Verify running

201+```

202+

203+### Step 2: Start Trigger Dev in Background

204+

205+```bash

206+# in your triggerdotdev/references clone

207+cd projects/hello-world && pnpm exec trigger dev

208+# Wait for "Local worker ready [node]"

209+```

210+

211+### Step 3: Trigger and Monitor Tasks via MCP

212+

213+```

214+mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev")

215+mcp__trigger__trigger_task(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskId: "hello-world", payload: {"message": "Hello"})

216+mcp__trigger__list_runs(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskIdentifier: "hello-world", limit: 5)

217+```

218+

219+Dashboard: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs

220+

221+

222+

223+# Skill mappings — when working in these areas, load the linked skill file into context.

224+

225+skills:

226+

227+- task: "Using agentcrumbs for debug tracing, adding crumbs, trails, markers, querying traces, or stripping debug code before merge"

228+ load: "node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md"

229+- task: "Setting up agentcrumbs in the project, initializing namespace catalog, running crumbs init"

230+ load: "node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md"

231+

232+

233+## agentcrumbs

234+

235+Add crumbs as you write code — not just when debugging. Mark lines with

236+`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the

237+branch throughout development and are stripped by `agentcrumbs strip`

238+before merge.

239+

240+### Namespaces

241+

242+| Namespace | Description | Path |

243+| ----------------- | ---------------------------------------------- | ----------------------------------- |

244+| `webapp` | Main Remix app — API, dashboard, orchestration | `apps/webapp` |

245+| `supervisor` | Task execution container manager | `apps/supervisor` |

246+| `sdk` | Main SDK for writing tasks | `packages/trigger-sdk` |

247+| `cli` | CLI and task image bundling | `packages/cli-v3` |

248+| `core` | Shared types and subpath exports | `packages/core` |

249+| `build` | Build extensions and types | `packages/build` |

250+| `react-hooks` | React hooks for realtime/triggering | `packages/react-hooks` |

251+| `redis-worker` | Redis-based background job system | `packages/redis-worker` |

252+| `run-engine` | Run Engine 2.0 — core run lifecycle | `internal-packages/run-engine` |

253+| `database` | Prisma client and schema | `internal-packages/database` |

254+| `clickhouse` | ClickHouse client, migrations, analytics | `internal-packages/clickhouse` |

255+| `schedule-engine` | Durable cron scheduling | `internal-packages/schedule-engine` |

256+| `run-queue` | Run queue management | `internal-packages/run-queue` |

257+

258+Do not invent new namespaces — pick from this table or ask first.

259+

260+### For PR reviewers

261+

262+Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs

263+imports in reviews. These are temporary debug instrumentation stripped

264+before merge. Data logged in crumbs (IDs, names, values) never reaches

265+production.

266+

267+### CLI

268+

269+```bash

270+pnpm exec agentcrumbs collect # start collector (multi-service)

271+pnpm exec agentcrumbs tail --app trigger # live tail

272+pnpm exec agentcrumbs clear --app trigger # remove crumbs before merge

273+```

274+

275+The preferred way to query for crumbs is to use `pnpm exec agentcrumbs query --app trigger` with the `--limit` option and cursor pagination, and clear existing crumbs before reproducing a bug via `pnpm exec agentcrumbs clear --app trigger`.

41276