Comparison

A · AGENTS.md · triggerdotdev/trigger.dev B · CLAUDE.md · triggerdotdev/trigger.dev

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	38	4	0%
Commands	0	25	1	0%
Section tags	1	11	0	8%

What each file covers

Sections

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

− 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
+ Trigger.dev SDK
+ Import Rules
+ Key Exports
+ When Adding Features

Commands

0 shared · 25 only in A · 1 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
+ task

Section tags

1 shared · 11 only in A · 0 only in B

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

Line diff

+19 added−267 removed9 unchanged3.3% identical

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

triggerdotdev/trigger.dev · packages/trigger-sdk/CLAUDE.md

@@ +1 @@

1# Trigger.dev SDK

3`@trigger.dev/sdk` - the main customer-facing SDK for writing background tasks.

5## Import Rules

7Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` (deprecated path alias).

9## Key Exports

11- `task` - Define a background task

12- `schedules.task` - Define a scheduled (cron) task

13- `batch` - Batch trigger operations

14- `runs` - Run management and polling

15- `wait` - Wait for events, delays, or other tasks

16- `retry` - Retry utilities

17- `queue` - Queue configuration

18- `metadata` - Run metadata access

19- `logger` - Structured logging

21## When Adding Features

231. Implement the feature in the SDK

242. Test with the `hello-world` project in the [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo

253. Docs updates (`docs/`) are usually done in a separate PR

27Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked. These are maintained in separate dedicated passes.

@@ −1 +1 @@

1−# AGENTS.md

1+# Trigger.dev SDK

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.

3+`@trigger.dev/sdk` - the main customer-facing SDK for writing background tasks.

5−## Build and Development Commands

5+## Import Rules

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

7+Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` (deprecated path alias).

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.

9+## Key Exports

1010

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)

11+- `task` - Define a background task

12+- `schedules.task` - Define a scheduled (cron) task

13+- `batch` - Batch trigger operations

14+- `runs` - Run management and polling

15+- `wait` - Wait for events, delays, or other tasks

16+- `retry` - Retry utilities

17+- `queue` - Queue configuration

18+- `metadata` - Run metadata access

19+- `logger` - Structured logging

1620

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

21+## When Adding Features

1922

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−```

23+1. Implement the feature in the SDK

24+2. Test with the `hello-world` project in the [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo

25+3. Docs updates (`docs/`) are usually done in a separate PR

2326

24−### Verifying Changes

25−

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

27−

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

30−

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

35−

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

27+Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked. These are maintained in separate dedicated passes.

27628