AGENTS.md

1# AGENTS.md
2 
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.
4 
5## Build and Development Commands
6 
7This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`.
8 
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.
10 
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)
16 
17# Build packages (required before running)
18pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
19
20pnpm run dev --filter webapp  # Run webapp (http://localhost:3030)
21pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"  # Watch CLI and packages
22```
23 
24### Verifying Changes
25 
26The 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
33pnpm run typecheck --filter webapp                  # ~1-2 minutes
34pnpm run typecheck --filter @internal/run-engine
35 
36# Public packages — use build
37pnpm run build --filter @trigger.dev/sdk
38pnpm run build --filter @trigger.dev/core
39```
40 
41Only 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 
45We use vitest exclusively. **Never mock anything** - use testcontainers instead.
46 
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```
53 
54Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`).
55 
56### Testcontainers for Redis/PostgreSQL
57 
58```typescript
59import { redisTest, postgresTest, containerTest } from "@internal/testcontainers";
60 
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```
71 
72## Code Style
73 
74### Formatting and linting
75 
76Format and lint are enforced by CI (`code-quality` check). Run before committing:
77 
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```
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 
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.
92 
93## Changesets and Server Changes
94 
95When modifying any public package (`packages/*` or `integrations/*`), add a changeset:
96 
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<!-- intent-skills:start -->
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<!-- intent-skills:end -->
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