Comparison

A · AGENTS.md · n8n-io/n8n B · AGENTS.md · n8n-io/n8n

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	4	6	22	13%
Commands	3	4	20	11%
Section tags	6	1	6	46%

What each file covers

Sections

4 shared · 6 only in A · 22 only in B

− Code Style
− Credential Pattern
− Engine Injection (EngineAgent)
− Integration tests
− Documentation
− PR naming convention
+ Project Overview
+ General Guidelines
+ Agent Skills and Claude Code Plugin
+ Essential Commands
+ Fresh checkout / agent setup
+ Code Quality
+ Architecture Overview
+ Technology Stack
+ Key Architectural Patterns
+ Key Development Patterns
+ Workflow Traversal Utilities
+ TypeScript Best Practices
+ Error Handling
+ Persistence layer & the TypeORM boundary
+ Frontend Development
+ Testing Guidelines
+ Common Development Tasks
+ Design Principles
+ Security Must Not Degrade the Building Experience
+ Security Fix Hygiene
+ Customer Confidentiality
+ Github Guidelines
AGENTS.md
Package Structure
Testing
Building

Commands

3 shared · 4 only in A · 20 only in B

− pnpm test:integration
− pnpm test:integration <file>
− pnpm test:integration:record <file>
− pnpm test:integration:replay
+ pnpm agent:setup
+ pnpm agent:setup install
+ pnpm agent:setup --json
+ pnpm build > build.log 2>&1
+ pnpm --filter @n8n/telemetry catalog
+ pnpm reset
+ pnpm reset --full
+ pnpm test:affected
+ pnpm test <test-file>
+ pnpm lint
+ node-dev
+ pnpm dev:ai
+ eslint-disable
+ vitest
+ pnpm --filter=n8n-playwright test:local
+ pnpm dev
+ pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy
+ node-1234-improve-request-handling
+ node-1234-fix-ddos-vulnerability
+ gh pr create --draft
pnpm build
pnpm typecheck
pnpm test

Section tags

6 shared · 1 only in A · 6 only in B

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

Line diff

+301 added−123 removed33 unchanged9.9% identical

n8n-io/n8n · packages/@n8n/agents/AGENTS.md

@@ −1 @@

1# AGENTS.md

3Conventions for the `@n8n/agents` package.

5## Code Style

7- **No `_` prefix on private properties** — use `private` access modifier

8 without underscore. Write `private name: string`, not `private _name: string`.

9- **Builder pattern with lazy build** — all public primitives use a fluent

10 builder API. **User code never calls `.build()`**. Builders are passed

11 directly to the consuming method (e.g. `agent.tool(myTool)`) which calls

12 `.build()` internally. Agent has `generate()`/`stream()` directly on the

13 class, which lazy-build via `ensureBuilt()` on first call. `build()` is

14 `protected` on Agent to keep it out of the public API.

15- **Zod for schemas** — all input/output schemas use Zod.

17## Package Structure

19```

20src/

21 index.ts # Public API barrel export

22 types/ # Public TypeScript types

23 index.ts # Re-exports consumable types

24 telemetry.ts

25 sdk/ # Types aligned with builders (agent, eval, guardrail, mcp, memory, message, provider, tool)

26 runtime/ # Serializable runtime shapes (events, message lists)

27 utils/ # JSON typing helpers re-exported with public types

28 sdk/ # Fluent builders and SDK entry points

29 agent.ts # Agent builder

30 catalog.ts # Provider catalog fetch

31 eval.ts # Evaluation primitives

32 evaluate.ts # Evaluation runner over agents + dataset

33 guardrail.ts # Guardrail builder

34 mcp-client.ts # MCP client integration

35 memory.ts # Memory builder

36 message.ts # LLM/DB message helpers

37 provider-tools.ts # Provider-defined tool factories

38 telemetry.ts # Telemetry builder (OTel, redaction)

39 tool.ts # Tool builder

40 verify.ts # Verification utilities

41 runtime/ # Internal — never exported

42 agent-runtime.ts # Core agent execution engine (AI SDK)

43 tool-adapter.ts # Tool execution, branded suspend detection

44 stream.ts # Streaming helpers

45 model-factory.ts # Model instantiation

46 memory-store.ts # In-memory conversation and observation-log storage

47 observation-log-observer.ts

48 observation-log-reflector.ts

49 observation-log-renderer.ts

50 scoped-memory-task-runner.ts

51 message-list.ts # Message list + serialization for agent loop

52 messages.ts # Message normalization

53 mcp-connection.ts # MCP connection lifecycle

54 mcp-tool-resolver.ts

55 run-state.ts # Run / checkpoint state

56 event-bus.ts # Internal agent events

57 runtime-helpers.ts

58 title-generation.ts

59 strip-orphaned-tool-messages.ts

60 logger.ts

61 storage/ # Shared memory backend base class (exported)

62 base-memory.ts

63 workspace/ # Workspace, sandbox, filesystem, built-in tools (exported)

64 integrations/ # Optional integrations (exported where applicable)

65 langsmith.ts # LangSmith telemetry adapter (peer `langsmith`)

66 utils/ # Internal helpers (e.g. Zod utilities); not barrel-exported

67examples/

68 basic-agent.ts # Sample snippet; included in format/lint paths

69docs/

70 agent-runtime-architecture.md # In-package runtime notes

71```

73The **`index.ts`** surface also exports `Workspace` / sandbox / filesystem types,

74`InMemoryMemory`, `LangSmithTelemetry`, and `evals` alongside the core SDK builders.

76Optional **peer dependencies** (telemetry): `langsmith`, `@opentelemetry/sdk-trace-node`,

77`@opentelemetry/sdk-trace-base`, `@opentelemetry/exporter-trace-otlp-http` — all

78optional; install only when wiring that telemetry.

80## Credential Pattern

82Agents declare credential requirements via `.credential('name')`. The execution

83engine resolves the name to an API key and injects it into the model config.

84User code never touches raw API keys.

86```typescript

87const agent = new Agent('assistant')

88 .model('anthropic/claude-sonnet-4-5')

89 .credential('anthropic')

90 .instructions('You are helpful.');

91```

93## Engine Injection (EngineAgent)

95The execution engine extends `Agent` and overrides `protected build()` to

96inject infrastructure (checkpoint storage, credentials) before calling

97`super.build()`. This is the pattern for all engine-level concerns:

99```typescript

100class EngineAgent extends Agent {

101 build() {

102 this.checkpoint(store);

103 const cred = this.declaredCredential;

104 if (cred) this.resolvedApiKey = resolve(cred);

105 return super.build();

106 }

107}

108```

109

110

111## Testing

112

113- Unit tests live in `src/__tests__/`, integration tests in `src/__tests__/integration/`

114- Unit tests use Vitest (`pnpm test`)

115- Integration tests use Vitest (`pnpm test:integration`) with real LLM calls

116 - A `.env` file at the package root is loaded automatically by the vitest config.

117 Always assume it exists when running integration tests. Never commit it.

118 - Required keys:

119 - `ANTHROPIC_API_KEY` — all integration tests

120 - Tests skip automatically when the required API key is not set

121- Run from the package directory: `cd packages/@n8n/agents && pnpm test`

122

123### Integration tests

124

125Integration tests make real LLM calls. CI replays recorded HTTP cassettes

126instead, so every test must have a matching recording.

127

128**Workflow after changing or adding integration tests:**

129

1301. `pnpm test:integration <file>` — verify the test passes with a live API key

1312. `pnpm test:integration:record <file>` — record HTTP cassettes

1323. `pnpm test:integration:replay` — confirm the test passes from recordings

133

134**Rules:**

135- No random IDs or current timestamps in HTTP requests — the replay matcher

136 must be able to match recorded requests deterministically

137- Run only the affected test files, not the full suite, unless changes affect all tests

138

139## Documentation

140

141- Spec-driven work in the wider repo may use `.agents/specs/` (see repo skill

142 `.agents/skills/spec-driven-development`).

143

144## Building

145

146```bash

147cd packages/@n8n/agents

148pnpm build # rimraf dist && tsc -p tsconfig.build.json → dist/

149pnpm typecheck # tsc --noEmit

150pnpm test # vitest (unit)

151```

152

153## PR naming convention

154

155The Agents feature is not generally available yet, so any PRs related to the Agents package should have (no-changelog) in the title to avoid generating a changelog entry.

156

n8n-io/n8n · AGENTS.md

@@ +1 @@

1# AGENTS.md

3This file provides guidance on how to work with the n8n repository.

5## Project Overview

7n8n is a workflow automation platform written in TypeScript, using a monorepo

8structure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js

9frontend, and extensible node-based workflow engine.

11## General Guidelines

13- Always use pnpm

14- **Secrets on the command line:** if a developer opted into anonymous dev

15 metrics (`scripts/dev-metrics`), pnpm command arguments are recorded. Arguments

16 of secret-carrying words (`config`, `login`, `publish`, `token`) — whether a

17 subcommand or baked into a flag — are dropped, and the home dir is stripped from

18 paths, but other args are sent as-is — so never put secrets in a command. Pass

19 sensitive values via environment variables, which are never captured.

20- When adding comments, keep them concise and to the point - explain the "why"

21 in a line or two; don't be overly verbose. Comments should be scoped and

22 relevant to the surrounding code, not just to the current task

23- We use Linear as a ticket tracking system

24- We use Posthog for feature flags

25- To find registered telemetry events (names, descriptions, properties), run

26 `pnpm --filter @n8n/telemetry catalog` (`--json` for structured output). The

27 registry is being adopted incrementally, so search call sites if the catalog

28 has no match. The `n8n:telemetry` skill covers adding or changing events

29- When starting to work on a new ticket – create a new branch from fresh

30 master with the name specified in Linear ticket

31- When creating a new branch for a ticket in Linear - use the branch name

32 suggested by Linear, **unless it is a security fix** (see Security Fix

33 Hygiene below)

34- Use mermaid diagrams in MD files when you need to visualise something

35- **Developing v3 features:** land normal feature work on `master` behind an

36 opt-in flag; introduce breaking changes only on the `3.x` branch. See

37 [.github/DEVELOPING_V3.md](.github/DEVELOPING_V3.md).

39## Agent Skills and Claude Code Plugin

41n8n shared skills live in `.agents/skills/`. Claude Code consumes them through

42symlinks in `.claude/plugins/n8n/skills/`; OpenCode reads `.agents/skills/`

43directly. Harness-specific overrides remain real directories in the harness

44path, such as `.opencode/skills/setup-mcps/`. See

45[skills README](.agents/skills/AGENTS.md) for editing and sync guidance.

47n8n-specific Claude Code commands and agents live in `.claude/plugins/n8n/` and

48are namespaced under `n8n:`. Use `n8n:` prefix when invoking them (e.g.

49`/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). See

50[plugin README](.claude/plugins/n8n/README.md) for structure and details.

52## Essential Commands

54### Fresh checkout / agent setup

56For a fresh checkout (cat-bot, a new hire, any agent verifying the repo

57builds), prefer `pnpm agent:setup` over running install + build + tests by

58hand. It chains them in one process, caps per-process memory and turbo

59concurrency so a 6GB box doesn't OOM, streams all output to

60`.agent-setup/<step>.log` (gitignored), and surfaces only a one-line summary

61per step plus the tail of the failing log. A machine-readable

62`.agent-setup/summary.json` is always written so a backgrounded run is

63readable in a single shot — no polling, no scrolling logs.

65```bash

66pnpm agent:setup # install → build → test (full suite)

67pnpm agent:setup install # one step at a time

68pnpm agent:setup --json # JSON summary on stdout (for scripts/agents)

69```

71### Building

72Use `pnpm build` to build all packages. ALWAYS redirect the output of the

73build command to a file:

75```bash

76pnpm build > build.log 2>&1

77```

79You can inspect the last few lines of the build log file to check for errors:

80```bash

81tail -n 20 build.log

82```

84If build outputs or the turbo cache are stale (e.g. after switching branches

85or worktrees) but dependencies haven't changed, use `pnpm reset` (lightweight

86by default) for a fast recovery: it cleans build outputs and force-rebuilds

87(keeping `node_modules` and untracked files). If that doesn't fix your issue,

88use `pnpm reset --full`, which also wipes untracked files and reinstalls

89dependencies.

91### Testing

92- `pnpm test` - Run all tests

93- `pnpm test:affected` - Runs tests based on what has changed since the last

94 commit

96Running a particular test file requires going to the directory of that test

97and running: `pnpm test <test-file>`.

99When changing directories, use `pushd` to navigate into the directory and

100`popd` to return to the previous directory. When in doubt, use `pwd` to check

101your current directory.

102

103### Code Quality

104- `pnpm lint` - Lint code

105- `pnpm typecheck` - Run type checks

106

107Always run lint and typecheck before committing code to ensure quality.

108Execute these commands from within the specific package directory you're

109working on (e.g., `cd packages/cli && pnpm lint`). Run the full repository

110check only when preparing the final PR. When your changes affect type

111definitions, interfaces in `@n8n/api-types`, or cross-package dependencies,

112build the system before running lint and typecheck.

113

114## Architecture Overview

115

116**Monorepo Structure:** pnpm workspaces with Turbo build orchestration

117

118### Package Structure

119

120The monorepo is organized into these key packages:

121

122- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend

123- **`packages/workflow`**: Core workflow interfaces and types

124- **`packages/core`**: Workflow execution engine

125- **`packages/cli`**: Express server, REST API, and CLI commands

126- **`packages/editor-ui`**: Vue 3 frontend application

127- **`packages/@n8n/i18n`**: Internationalization for UI text

128- **`packages/nodes-base`**: Built-in nodes for integrations

129- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes

130- **`packages/@n8n/instance-ai`**: "AI Assistant" in the UI, "Instance AI" in code — AI assistant backend. See its `CLAUDE.md` for architecture docs.

131- **`@n8n/design-system`**: Vue component library for UI consistency

132- **`@n8n/config`**: Centralized configuration management

133

134## Technology Stack

135

136- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library

137- **Backend:** Node.js + TypeScript + Express + TypeORM

138- **Testing:** Vitest (unit) + Playwright (E2E)

139- **Database:** TypeORM with SQLite/PostgreSQL support

140- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks

141

142### Key Architectural Patterns

143

1441. **Dependency Injection**: Uses `@n8n/di` for IoC container

1452. **Controller-Service-Repository**: Backend follows MVC-like pattern

1463. **Event-Driven**: Internal event bus for decoupled communication

1474. **Context-Based Execution**: Different contexts for different node types

1485. **State Management**: Frontend uses Pinia stores

1496. **Design System**: Reusable components and design tokens are centralized in

150 `@n8n/design-system`, where all pure Vue components should be placed to

151 ensure consistency and reusability

152

153## Key Development Patterns

154

155- Each package has isolated build configuration and can be developed independently

156- Hot reload works across the full stack during development

157- Node development uses dedicated `node-dev` CLI tool

158- Workflow tests are JSON-based for integration testing

159- AI features have dedicated development workflow (`pnpm dev:ai`)

160

161### Workflow Traversal Utilities

162

163The `n8n-workflow` package exports graph traversal utilities from

164`packages/workflow/src/common/`. Use these instead of custom traversal logic.

165

166**Key concept:** `workflow.connections` is indexed by **source node**.

167To find parent nodes, use `mapConnectionsByDestination()` to invert it first.

168

169```typescript

170import { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';

171

172// Finding parent nodes (predecessors) - requires inverted connections

173const connectionsByDestination = mapConnectionsByDestination(workflow.connections);

174const parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);

175

176// Finding child nodes (successors) - uses connections directly

177const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);

178```

179

180### TypeScript Best Practices

181- **NEVER use `any` type** - use proper types or `unknown`

182- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)

183- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication

184- **Lazy-load heavy modules** — if a module is only used in a specific code

185 path (not every request), use `await import()` at point of use instead of

186 top-level `import`. Applies especially to native modules and large parsers.

187

188### Error Handling

189- Don't use the deprecated `ApplicationError` class anywhere — it's a

190 compatibility shim kept only so community nodes keep resolving. Use one of

191 these instead, picking by cause:

192 - `UserError` — the user caused it (invalid input, unauthorized action,

193 business-rule violation).

194 - `OperationalError` — a transient, expected issue (network request failing,

195 DB query timing out) that should be handled gracefully.

196 - `UnexpectedError` — a bug in the code (logic mistake, unhandled case,

197 failed assertion) that developers need to fix.

198- Import from appropriate error classes in each package

199

200### Persistence layer & the TypeORM boundary

201

202TypeORM (`@n8n/typeorm`) must stay in the **persistence layer** — the `@n8n/db`

203package or a backend module's own `database/` folder (entity/repository files).

204Business logic — services, controllers, handlers, commands, factories — must not

205import from `@n8n/typeorm` (including `@n8n/typeorm/...` subpaths). In

206`packages/cli` this is enforced by the `misplaced-n8n-typeorm-import` lint rule;

207a new import (or an inline `eslint-disable` of the rule) fails CI.

208

209- **Pattern:** when a query needs operators (`In`, `IsNull`, `LessThan`,

210 `FindOptionsWhere`, …), put it behind a **use-case-named repository method**

211 that takes plain parameters and returns domain-shaped values — not a generic

212 `find(options)` passthrough.

213- **Transactions:** transaction orchestration belongs in the persistence layer.

214 Don't reach for `.manager` / `.manager.transaction(...)` or

215 `createQueryBuilder(...)` in business logic. Use the sanctioned primitive in

216 `@n8n/db`: inject the abstract `TransactionRunner` and wrap the unit of work in

217 `txRunner.run(ctx, async (ctx) => …)`. The callback receives an

218 `OperationContext` carrying the active transaction; thread that `ctx` into the

219 repository methods you call. `run` **requires** a context — pass an empty `{}`

220 at the operation entry point, and reuse the one you were handed everywhere

221 below it (a context that already carries a transaction is joined, not nested).

222 Repositories extend `BaseRepository` and resolve the right `EntityManager` with

223 `this.managerFor(ctx)`; the `Transaction` handle is opaque and never exposes a

224 driver type to business logic. See `oauth-token.service.ts` +

225 `oauth-*-token.repository.ts` for a worked example.

226- **Anti-patterns reviewers reject** — they hide the dependency instead of

227 removing it:

228 - String-matching TypeORM errors, e.g. `error.name === 'QueryFailedError'`.

229 - Relabeling the import from `@n8n/typeorm` to `@n8n/db` to silence the rule

230 (`@n8n/db` re-exports several operators/types, but this relabels the

231 dependency rather than removing it).

232 - Pushing `.manager` / `createQueryBuilder` into business logic to avoid an

233 operator import — trades a visible leak for an invisible one.

234

235### Frontend Development

236- Refer to `packages/frontend/AGENTS.md`

237- **All UI text must use i18n** - add translations to `@n8n/i18n` package

238- **Use CSS variables directly** - never hardcode spacing as px values

239- **data-testid must be a single value** (no spaces or multiple values)

240- Always use `design-system-rules` skill in reviews

241

242### Testing Guidelines

243- **Always work from within the package directory** when running tests

244- **Mock all external dependencies** in unit tests

245- **Prefer reusing hoisted shared `mock<T>(...)` fixtures** when a typed mock is immutable and used across tests. This rule exists to avoid massive test slowdowns from repeatedly creating nested proxy mocks while preserving the type contract. Avoid replacing these with `as unknown as T` helpers for entities like `User`.

246- **Confirm test cases with user** before writing unit tests

247- **Typecheck is critical before committing** - always run `pnpm typecheck`

248- **When modifying pinia stores**, check for unused computed properties

249- **For Vitest packages that use `@n8n/di` decorators**, use `createVitestConfigWithDecorators` from `@n8n/vitest-config/node-decorators`. It enables SWC `decoratorMetadata` (esbuild doesn't emit it) and externalizes workspace packages that register services (`@n8n/di`, `@n8n/config`, `@n8n/constants`, `n8n-workflow`) so a single DI `Container` instance is shared across the runtime. Loading them through Vitest's pipeline alongside their CJS dist produces two `Container`s and `Container.get(...)` returns `undefined`.

250

251What we use for testing and writing tests:

252- For testing nodes and other backend components, we use Vitest for unit tests. Examples can be found in `packages/nodes-base/nodes/**/*test*`.

253- We use `nock` for server mocking

254- For frontend we use `vitest`

255- For E2E tests we use Playwright. Run with `pnpm --filter=n8n-playwright test:local`.

256 See `packages/testing/playwright/README.md` for details.

257- **To iterate on a feature without docker rebuilds**, boot service containers

258 and run `pnpm dev` locally — `pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy`

259 then `pnpm dev`. See [Develop against running containers](packages/testing/playwright/README.md#develop-against-running-containers-avoid-docker-rebuilds).

260- **For Playwright test maintenance/cleanup**, see `packages/testing/playwright/AGENTS.md` (includes janitor tool for static analysis, dead code removal, architecture enforcement, and TCR workflows).

261

262### Common Development Tasks

263

264When implementing features:

2651. Define API types in `packages/@n8n/api-types`

2662. Implement backend logic in `packages/cli` module, follow

267 `@packages/cli/scripts/backend-module/backend-module-guide.md`

2683. Add API endpoints via controllers

2694. Update frontend in `packages/editor-ui` with i18n support

2705. Write tests with proper mocks

2716. Run `pnpm typecheck` to verify types

272

273## Design Principles

274

275### Security Must Not Degrade the Building Experience

276

277Security improvements, whether driven by enterprise requirements or internal

278standards, must NEVER add friction to the common-case building experience. When

279designing security-related features (defaults, behaviors, flows, error

280handling), apply these checks:

281

282- **No friction for the common case:** A community builder's workflow should

283 remain intuitive. Security should be invisible when it can be.

284- **Migration and upgrade paths:** Existing users must have a clear,

285 non-disruptive path forward when defaults or behaviors change.

286- **Security layers on top, not in competition:** Great UX and strong security

287 are not trade-offs. They're both required. If a design forces a choice

288 between them, the design needs more work.

289

290### Security Fix Hygiene

291

292**This is a public repository.** When working on security fixes, never expose

293the attack vector or vulnerability type in any public-facing artifact. Attackers

294monitor open-source repos for signals like branch names, commit messages, PR

295titles, test descriptions, and Linear URLs.

296

297**Rules for security fixes:**

298

299- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals

300 the vulnerability. Rename to describe the fix neutrally

301 (e.g. `node-1234-improve-request-handling`, not

302 `node-1234-fix-ddos-vulnerability`).

303- **Commit messages:** Describe what the code now does, not the threat it

304 prevents (e.g. `fix: add payload size validation`, not

305 `fix: prevent denial of service`).

306- **Test descriptions:** Use neutral, functional language

307 (e.g. `'should sanitize query parameters'`, not

308 `'should prevent SQL injection'`).

309- **Code comments:** Do not describe the attack scenario in comments.

310- **Linear references:** Never include the URL slug

311 (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).

312

313### Customer Confidentiality

314

315**This is a public repository.** Never mention customer names in any

316public-facing artifact — not all customers have agreed to be named publicly,

317and naming them can reveal security-relevant details about their setup.

318

319This applies to PR titles and descriptions, branch names, commit messages,

320code, code comments, test names and test data, and fixtures. When implementing

321a customer request, describe the use case neutrally (e.g. "a customer with a

322large multi-main setup", not the company name) and use generic placeholder

323names (e.g. `Acme Corp`) in tests and examples.

324

325## Github Guidelines

326- When creating a PR, use the conventions in

327 `.github/pull_request_template.md` and

328 `.github/pull_request_title_conventions.md`.

329- Use `gh pr create --draft` to create draft PRs.

330- If there is a corresponding Linear ticket, reference it in the PR

331 description using `https://linear.app/n8n/issue/[TICKET-ID]`. Do not

332 create a Linear ticket on your own — ask first.

333- always link to the github issue if mentioned in the linear ticket.

334

@@ −1 +1 @@

11 # AGENTS.md

3−Conventions for the `@n8n/agents` package.

3+This file provides guidance on how to work with the n8n repository.

5−## Code Style

5+## Project Overview

7−- **No `_` prefix on private properties** — use `private` access modifier

8− without underscore. Write `private name: string`, not `private _name: string`.

9−- **Builder pattern with lazy build** — all public primitives use a fluent

10− builder API. **User code never calls `.build()`**. Builders are passed

11− directly to the consuming method (e.g. `agent.tool(myTool)`) which calls

12− `.build()` internally. Agent has `generate()`/`stream()` directly on the

13− class, which lazy-build via `ensureBuilt()` on first call. `build()` is

14− `protected` on Agent to keep it out of the public API.

15−- **Zod for schemas** — all input/output schemas use Zod.

7+n8n is a workflow automation platform written in TypeScript, using a monorepo

8+structure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js

9+frontend, and extensible node-based workflow engine.

1610

17−## Package Structure

11+## General Guidelines

1812

13+- Always use pnpm

14+- **Secrets on the command line:** if a developer opted into anonymous dev

15+ metrics (`scripts/dev-metrics`), pnpm command arguments are recorded. Arguments

16+ of secret-carrying words (`config`, `login`, `publish`, `token`) — whether a

17+ subcommand or baked into a flag — are dropped, and the home dir is stripped from

18+ paths, but other args are sent as-is — so never put secrets in a command. Pass

19+ sensitive values via environment variables, which are never captured.

20+- When adding comments, keep them concise and to the point - explain the "why"

21+ in a line or two; don't be overly verbose. Comments should be scoped and

22+ relevant to the surrounding code, not just to the current task

23+- We use Linear as a ticket tracking system

24+- We use Posthog for feature flags

25+- To find registered telemetry events (names, descriptions, properties), run

26+ `pnpm --filter @n8n/telemetry catalog` (`--json` for structured output). The

27+ registry is being adopted incrementally, so search call sites if the catalog

28+ has no match. The `n8n:telemetry` skill covers adding or changing events

29+- When starting to work on a new ticket – create a new branch from fresh

30+ master with the name specified in Linear ticket

31+- When creating a new branch for a ticket in Linear - use the branch name

32+ suggested by Linear, **unless it is a security fix** (see Security Fix

33+ Hygiene below)

34+- Use mermaid diagrams in MD files when you need to visualise something

35+- **Developing v3 features:** land normal feature work on `master` behind an

36+ opt-in flag; introduce breaking changes only on the `3.x` branch. See

37+ [.github/DEVELOPING_V3.md](.github/DEVELOPING_V3.md).

38+

39+## Agent Skills and Claude Code Plugin

40+

41+n8n shared skills live in `.agents/skills/`. Claude Code consumes them through

42+symlinks in `.claude/plugins/n8n/skills/`; OpenCode reads `.agents/skills/`

43+directly. Harness-specific overrides remain real directories in the harness

44+path, such as `.opencode/skills/setup-mcps/`. See

45+[skills README](.agents/skills/AGENTS.md) for editing and sync guidance.

46+

47+n8n-specific Claude Code commands and agents live in `.claude/plugins/n8n/` and

48+are namespaced under `n8n:`. Use `n8n:` prefix when invoking them (e.g.

49+`/n8n:create-pr`, `/n8n:plan`, `n8n:developer` agent). See

50+[plugin README](.claude/plugins/n8n/README.md) for structure and details.

51+

52+## Essential Commands

53+

54+### Fresh checkout / agent setup

55+

56+For a fresh checkout (cat-bot, a new hire, any agent verifying the repo

57+builds), prefer `pnpm agent:setup` over running install + build + tests by

58+hand. It chains them in one process, caps per-process memory and turbo

59+concurrency so a 6GB box doesn't OOM, streams all output to

60+`.agent-setup/<step>.log` (gitignored), and surfaces only a one-line summary

61+per step plus the tail of the failing log. A machine-readable

62+`.agent-setup/summary.json` is always written so a backgrounded run is

63+readable in a single shot — no polling, no scrolling logs.

64+

65+```bash

66+pnpm agent:setup # install → build → test (full suite)

67+pnpm agent:setup install # one step at a time

68+pnpm agent:setup --json # JSON summary on stdout (for scripts/agents)

1969 ```

20−src/

21− index.ts # Public API barrel export

22− types/ # Public TypeScript types

23− index.ts # Re-exports consumable types

24− telemetry.ts

25− sdk/ # Types aligned with builders (agent, eval, guardrail, mcp, memory, message, provider, tool)

26− runtime/ # Serializable runtime shapes (events, message lists)

27− utils/ # JSON typing helpers re-exported with public types

28− sdk/ # Fluent builders and SDK entry points

29− agent.ts # Agent builder

30− catalog.ts # Provider catalog fetch

31− eval.ts # Evaluation primitives

32− evaluate.ts # Evaluation runner over agents + dataset

33− guardrail.ts # Guardrail builder

34− mcp-client.ts # MCP client integration

35− memory.ts # Memory builder

36− message.ts # LLM/DB message helpers

37− provider-tools.ts # Provider-defined tool factories

38− telemetry.ts # Telemetry builder (OTel, redaction)

39− tool.ts # Tool builder

40− verify.ts # Verification utilities

41− runtime/ # Internal — never exported

42− agent-runtime.ts # Core agent execution engine (AI SDK)

43− tool-adapter.ts # Tool execution, branded suspend detection

44− stream.ts # Streaming helpers

45− model-factory.ts # Model instantiation

46− memory-store.ts # In-memory conversation and observation-log storage

47− observation-log-observer.ts

48− observation-log-reflector.ts

49− observation-log-renderer.ts

50− scoped-memory-task-runner.ts

51− message-list.ts # Message list + serialization for agent loop

52− messages.ts # Message normalization

53− mcp-connection.ts # MCP connection lifecycle

54− mcp-tool-resolver.ts

55− run-state.ts # Run / checkpoint state

56− event-bus.ts # Internal agent events

57− runtime-helpers.ts

58− title-generation.ts

59− strip-orphaned-tool-messages.ts

60− logger.ts

61− storage/ # Shared memory backend base class (exported)

62− base-memory.ts

63− workspace/ # Workspace, sandbox, filesystem, built-in tools (exported)

64− integrations/ # Optional integrations (exported where applicable)

65− langsmith.ts # LangSmith telemetry adapter (peer `langsmith`)

66− utils/ # Internal helpers (e.g. Zod utilities); not barrel-exported

67−examples/

68− basic-agent.ts # Sample snippet; included in format/lint paths

69−docs/

70− agent-runtime-architecture.md # In-package runtime notes

70+

71+### Building

72+Use `pnpm build` to build all packages. ALWAYS redirect the output of the

73+build command to a file:

74+

75+```bash

76+pnpm build > build.log 2>&1

7177 ```

7278

73−The **`index.ts`** surface also exports `Workspace` / sandbox / filesystem types,

74−`InMemoryMemory`, `LangSmithTelemetry`, and `evals` alongside the core SDK builders.

79+You can inspect the last few lines of the build log file to check for errors:

80+```bash

81+tail -n 20 build.log

82+```

7583

76−Optional **peer dependencies** (telemetry): `langsmith`, `@opentelemetry/sdk-trace-node`,

77−`@opentelemetry/sdk-trace-base`, `@opentelemetry/exporter-trace-otlp-http` — all

78−optional; install only when wiring that telemetry.

84+If build outputs or the turbo cache are stale (e.g. after switching branches

85+or worktrees) but dependencies haven't changed, use `pnpm reset` (lightweight

86+by default) for a fast recovery: it cleans build outputs and force-rebuilds

87+(keeping `node_modules` and untracked files). If that doesn't fix your issue,

88+use `pnpm reset --full`, which also wipes untracked files and reinstalls

89+dependencies.

7990

80−## Credential Pattern

91+### Testing

92+- `pnpm test` - Run all tests

93+- `pnpm test:affected` - Runs tests based on what has changed since the last

94+ commit

8195

82−Agents declare credential requirements via `.credential('name')`. The execution

83−engine resolves the name to an API key and injects it into the model config.

84−User code never touches raw API keys.

96+Running a particular test file requires going to the directory of that test

97+and running: `pnpm test <test-file>`.

8598

86−```typescript

87−const agent = new Agent('assistant')

88− .model('anthropic/claude-sonnet-4-5')

89− .credential('anthropic')

90− .instructions('You are helpful.');

91−```

99+When changing directories, use `pushd` to navigate into the directory and

100+`popd` to return to the previous directory. When in doubt, use `pwd` to check

101+your current directory.

92102

93−## Engine Injection (EngineAgent)

103+### Code Quality

104+- `pnpm lint` - Lint code

105+- `pnpm typecheck` - Run type checks

94106

95−The execution engine extends `Agent` and overrides `protected build()` to

96−inject infrastructure (checkpoint storage, credentials) before calling

97−`super.build()`. This is the pattern for all engine-level concerns:

107+Always run lint and typecheck before committing code to ensure quality.

108+Execute these commands from within the specific package directory you're

109+working on (e.g., `cd packages/cli && pnpm lint`). Run the full repository

110+check only when preparing the final PR. When your changes affect type

111+definitions, interfaces in `@n8n/api-types`, or cross-package dependencies,

112+build the system before running lint and typecheck.

98113

114+## Architecture Overview

115+

116+**Monorepo Structure:** pnpm workspaces with Turbo build orchestration

117+

118+### Package Structure

119+

120+The monorepo is organized into these key packages:

121+

122+- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend

123+- **`packages/workflow`**: Core workflow interfaces and types

124+- **`packages/core`**: Workflow execution engine

125+- **`packages/cli`**: Express server, REST API, and CLI commands

126+- **`packages/editor-ui`**: Vue 3 frontend application

127+- **`packages/@n8n/i18n`**: Internationalization for UI text

128+- **`packages/nodes-base`**: Built-in nodes for integrations

129+- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes

130+- **`packages/@n8n/instance-ai`**: "AI Assistant" in the UI, "Instance AI" in code — AI assistant backend. See its `CLAUDE.md` for architecture docs.

131+- **`@n8n/design-system`**: Vue component library for UI consistency

132+- **`@n8n/config`**: Centralized configuration management

133+

134+## Technology Stack

135+

136+- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library

137+- **Backend:** Node.js + TypeScript + Express + TypeORM

138+- **Testing:** Vitest (unit) + Playwright (E2E)

139+- **Database:** TypeORM with SQLite/PostgreSQL support

140+- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks

141+

142+### Key Architectural Patterns

143+

144+1. **Dependency Injection**: Uses `@n8n/di` for IoC container

145+2. **Controller-Service-Repository**: Backend follows MVC-like pattern

146+3. **Event-Driven**: Internal event bus for decoupled communication

147+4. **Context-Based Execution**: Different contexts for different node types

148+5. **State Management**: Frontend uses Pinia stores

149+6. **Design System**: Reusable components and design tokens are centralized in

150+ `@n8n/design-system`, where all pure Vue components should be placed to

151+ ensure consistency and reusability

152+

153+## Key Development Patterns

154+

155+- Each package has isolated build configuration and can be developed independently

156+- Hot reload works across the full stack during development

157+- Node development uses dedicated `node-dev` CLI tool

158+- Workflow tests are JSON-based for integration testing

159+- AI features have dedicated development workflow (`pnpm dev:ai`)

160+

161+### Workflow Traversal Utilities

162+

163+The `n8n-workflow` package exports graph traversal utilities from

164+`packages/workflow/src/common/`. Use these instead of custom traversal logic.

165+

166+**Key concept:** `workflow.connections` is indexed by **source node**.

167+To find parent nodes, use `mapConnectionsByDestination()` to invert it first.

168+

99169 ```typescript

100−class EngineAgent extends Agent {

101− build() {

102− this.checkpoint(store);

103− const cred = this.declaredCredential;

104− if (cred) this.resolvedApiKey = resolve(cred);

105− return super.build();

106− }

107−}

170+import { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow';

171+

172+// Finding parent nodes (predecessors) - requires inverted connections

173+const connectionsByDestination = mapConnectionsByDestination(workflow.connections);

174+const parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);

175+

176+// Finding child nodes (successors) - uses connections directly

177+const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);

108178 ```

109179

180+### TypeScript Best Practices

181+- **NEVER use `any` type** - use proper types or `unknown`

182+- **Avoid type casting with `as`** - use type guards or type predicates instead (except in test code where `as` is acceptable)

183+- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication

184+- **Lazy-load heavy modules** — if a module is only used in a specific code

185+ path (not every request), use `await import()` at point of use instead of

186+ top-level `import`. Applies especially to native modules and large parsers.

110187

111−## Testing

188+### Error Handling

189+- Don't use the deprecated `ApplicationError` class anywhere — it's a

190+ compatibility shim kept only so community nodes keep resolving. Use one of

191+ these instead, picking by cause:

192+ - `UserError` — the user caused it (invalid input, unauthorized action,

193+ business-rule violation).

194+ - `OperationalError` — a transient, expected issue (network request failing,

195+ DB query timing out) that should be handled gracefully.

196+ - `UnexpectedError` — a bug in the code (logic mistake, unhandled case,

197+ failed assertion) that developers need to fix.

198+- Import from appropriate error classes in each package

112199

113−- Unit tests live in `src/__tests__/`, integration tests in `src/__tests__/integration/`

114−- Unit tests use Vitest (`pnpm test`)

115−- Integration tests use Vitest (`pnpm test:integration`) with real LLM calls

116− - A `.env` file at the package root is loaded automatically by the vitest config.

117− Always assume it exists when running integration tests. Never commit it.

118− - Required keys:

119− - `ANTHROPIC_API_KEY` — all integration tests

120− - Tests skip automatically when the required API key is not set

121−- Run from the package directory: `cd packages/@n8n/agents && pnpm test`

200+### Persistence layer & the TypeORM boundary

122201

123−### Integration tests

202+TypeORM (`@n8n/typeorm`) must stay in the **persistence layer** — the `@n8n/db`

203+package or a backend module's own `database/` folder (entity/repository files).

204+Business logic — services, controllers, handlers, commands, factories — must not

205+import from `@n8n/typeorm` (including `@n8n/typeorm/...` subpaths). In

206+`packages/cli` this is enforced by the `misplaced-n8n-typeorm-import` lint rule;

207+a new import (or an inline `eslint-disable` of the rule) fails CI.

124208

125−Integration tests make real LLM calls. CI replays recorded HTTP cassettes

126−instead, so every test must have a matching recording.

209+- **Pattern:** when a query needs operators (`In`, `IsNull`, `LessThan`,

210+ `FindOptionsWhere`, …), put it behind a **use-case-named repository method**

211+ that takes plain parameters and returns domain-shaped values — not a generic

212+ `find(options)` passthrough.

213+- **Transactions:** transaction orchestration belongs in the persistence layer.

214+ Don't reach for `.manager` / `.manager.transaction(...)` or

215+ `createQueryBuilder(...)` in business logic. Use the sanctioned primitive in

216+ `@n8n/db`: inject the abstract `TransactionRunner` and wrap the unit of work in

217+ `txRunner.run(ctx, async (ctx) => …)`. The callback receives an

218+ `OperationContext` carrying the active transaction; thread that `ctx` into the

219+ repository methods you call. `run` **requires** a context — pass an empty `{}`

220+ at the operation entry point, and reuse the one you were handed everywhere

221+ below it (a context that already carries a transaction is joined, not nested).

222+ Repositories extend `BaseRepository` and resolve the right `EntityManager` with

223+ `this.managerFor(ctx)`; the `Transaction` handle is opaque and never exposes a

224+ driver type to business logic. See `oauth-token.service.ts` +

225+ `oauth-*-token.repository.ts` for a worked example.

226+- **Anti-patterns reviewers reject** — they hide the dependency instead of

227+ removing it:

228+ - String-matching TypeORM errors, e.g. `error.name === 'QueryFailedError'`.

229+ - Relabeling the import from `@n8n/typeorm` to `@n8n/db` to silence the rule

230+ (`@n8n/db` re-exports several operators/types, but this relabels the

231+ dependency rather than removing it).

232+ - Pushing `.manager` / `createQueryBuilder` into business logic to avoid an

233+ operator import — trades a visible leak for an invisible one.

127234

128−**Workflow after changing or adding integration tests:**

235+### Frontend Development

236+- Refer to `packages/frontend/AGENTS.md`

237+- **All UI text must use i18n** - add translations to `@n8n/i18n` package

238+- **Use CSS variables directly** - never hardcode spacing as px values

239+- **data-testid must be a single value** (no spaces or multiple values)

240+- Always use `design-system-rules` skill in reviews

129241

130−1. `pnpm test:integration <file>` — verify the test passes with a live API key

131−2. `pnpm test:integration:record <file>` — record HTTP cassettes

132−3. `pnpm test:integration:replay` — confirm the test passes from recordings

242+### Testing Guidelines

243+- **Always work from within the package directory** when running tests

244+- **Mock all external dependencies** in unit tests

245+- **Prefer reusing hoisted shared `mock<T>(...)` fixtures** when a typed mock is immutable and used across tests. This rule exists to avoid massive test slowdowns from repeatedly creating nested proxy mocks while preserving the type contract. Avoid replacing these with `as unknown as T` helpers for entities like `User`.

246+- **Confirm test cases with user** before writing unit tests

247+- **Typecheck is critical before committing** - always run `pnpm typecheck`

248+- **When modifying pinia stores**, check for unused computed properties

249+- **For Vitest packages that use `@n8n/di` decorators**, use `createVitestConfigWithDecorators` from `@n8n/vitest-config/node-decorators`. It enables SWC `decoratorMetadata` (esbuild doesn't emit it) and externalizes workspace packages that register services (`@n8n/di`, `@n8n/config`, `@n8n/constants`, `n8n-workflow`) so a single DI `Container` instance is shared across the runtime. Loading them through Vitest's pipeline alongside their CJS dist produces two `Container`s and `Container.get(...)` returns `undefined`.

133250

134−**Rules:**

135−- No random IDs or current timestamps in HTTP requests — the replay matcher

136− must be able to match recorded requests deterministically

137−- Run only the affected test files, not the full suite, unless changes affect all tests

251+What we use for testing and writing tests:

252+- For testing nodes and other backend components, we use Vitest for unit tests. Examples can be found in `packages/nodes-base/nodes/**/*test*`.

253+- We use `nock` for server mocking

254+- For frontend we use `vitest`

255+- For E2E tests we use Playwright. Run with `pnpm --filter=n8n-playwright test:local`.

256+ See `packages/testing/playwright/README.md` for details.

257+- **To iterate on a feature without docker rebuilds**, boot service containers

258+ and run `pnpm dev` locally — `pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy`

259+ then `pnpm dev`. See [Develop against running containers](packages/testing/playwright/README.md#develop-against-running-containers-avoid-docker-rebuilds).

260+- **For Playwright test maintenance/cleanup**, see `packages/testing/playwright/AGENTS.md` (includes janitor tool for static analysis, dead code removal, architecture enforcement, and TCR workflows).

138261

139−## Documentation

262+### Common Development Tasks

140263

141−- Spec-driven work in the wider repo may use `.agents/specs/` (see repo skill

142− `.agents/skills/spec-driven-development`).

264+When implementing features:

265+1. Define API types in `packages/@n8n/api-types`

266+2. Implement backend logic in `packages/cli` module, follow

267+ `@packages/cli/scripts/backend-module/backend-module-guide.md`

268+3. Add API endpoints via controllers

269+4. Update frontend in `packages/editor-ui` with i18n support

270+5. Write tests with proper mocks

271+6. Run `pnpm typecheck` to verify types

143272

144−## Building

273+## Design Principles

145274

146−```bash

147−cd packages/@n8n/agents

148−pnpm build # rimraf dist && tsc -p tsconfig.build.json → dist/

149−pnpm typecheck # tsc --noEmit

150−pnpm test # vitest (unit)

151−```

275+### Security Must Not Degrade the Building Experience

152276

153−## PR naming convention

277+Security improvements, whether driven by enterprise requirements or internal

278+standards, must NEVER add friction to the common-case building experience. When

279+designing security-related features (defaults, behaviors, flows, error

280+handling), apply these checks:

154281

155−The Agents feature is not generally available yet, so any PRs related to the Agents package should have (no-changelog) in the title to avoid generating a changelog entry.

282+- **No friction for the common case:** A community builder's workflow should

283+ remain intuitive. Security should be invisible when it can be.

284+- **Migration and upgrade paths:** Existing users must have a clear,

285+ non-disruptive path forward when defaults or behaviors change.

286+- **Security layers on top, not in competition:** Great UX and strong security

287+ are not trade-offs. They're both required. If a design forces a choice

288+ between them, the design needs more work.

289+

290+### Security Fix Hygiene

291+

292+**This is a public repository.** When working on security fixes, never expose

293+the attack vector or vulnerability type in any public-facing artifact. Attackers

294+monitor open-source repos for signals like branch names, commit messages, PR

295+titles, test descriptions, and Linear URLs.

296+

297+**Rules for security fixes:**

298+

299+- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals

300+ the vulnerability. Rename to describe the fix neutrally

301+ (e.g. `node-1234-improve-request-handling`, not

302+ `node-1234-fix-ddos-vulnerability`).

303+- **Commit messages:** Describe what the code now does, not the threat it

304+ prevents (e.g. `fix: add payload size validation`, not

305+ `fix: prevent denial of service`).

306+- **Test descriptions:** Use neutral, functional language

307+ (e.g. `'should sanitize query parameters'`, not

308+ `'should prevent SQL injection'`).

309+- **Code comments:** Do not describe the attack scenario in comments.

310+- **Linear references:** Never include the URL slug

311+ (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).

312+

313+### Customer Confidentiality

314+

315+**This is a public repository.** Never mention customer names in any

316+public-facing artifact — not all customers have agreed to be named publicly,

317+and naming them can reveal security-relevant details about their setup.

318+

319+This applies to PR titles and descriptions, branch names, commit messages,

320+code, code comments, test names and test data, and fixtures. When implementing

321+a customer request, describe the use case neutrally (e.g. "a customer with a

322+large multi-main setup", not the company name) and use generic placeholder

323+names (e.g. `Acme Corp`) in tests and examples.

324+

325+## Github Guidelines

326+- When creating a PR, use the conventions in

327+ `.github/pull_request_template.md` and

328+ `.github/pull_request_title_conventions.md`.

329+- Use `gh pr create --draft` to create draft PRs.

330+- If there is a corresponding Linear ticket, reference it in the PR

331+ description using `https://linear.app/n8n/issue/[TICKET-ID]`. Do not

332+ create a Linear ticket on your own — ask first.

333+- always link to the github issue if mentioned in the linear ticket.

156334