AGENTS.md

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

Project Overview

n8n is a workflow automation platform written in TypeScript, using a monorepo structure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js frontend, and extensible node-based workflow engine.

General Guidelines

• Always use pnpm
• When adding comments, keep them concise and to the point - explain the "why" in a line or two; don't be overly verbose. Comments should be scoped and relevant to the surrounding code, not just to the current task
• We use Linear as a ticket tracking system
• We use Posthog for feature flags
• When starting to work on a new ticket – create a new branch from fresh master with the name specified in Linear ticket
• When creating a new branch for a ticket in Linear - use the branch name suggested by Linear, unless it is a security fix (see Security Fix Hygiene below)
• Use mermaid diagrams in MD files when you need to visualise something

Agent Skills and Claude Code Plugin

n8n shared skills live in .agents/skills/. Claude Code consumes them through symlinks in .claude/plugins/n8n/skills/; OpenCode reads .agents/skills/ directly. Harness-specific overrides remain real directories in the harness path, such as .opencode/skills/setup-mcps/. See skills README for editing and sync guidance.

n8n-specific Claude Code commands and agents live in .claude/plugins/n8n/ and are namespaced under n8n:. Use n8n: prefix when invoking them (e.g. /n8n:create-pr, /n8n:plan, n8n:developer agent). See plugin README for structure and details.

Essential Commands

Fresh checkout / agent setup

For a fresh checkout (cat-bot, a new hire, any agent verifying the repo builds), prefer pnpm agent:setup over running install + build + tests by hand. It chains them in one process, caps per-process memory and turbo concurrency so a 6GB box doesn't OOM, streams all output to .agent-setup/<step>.log (gitignored), and surfaces only a one-line summary per step plus the tail of the failing log. A machine-readable .agent-setup/summary.json is always written so a backgrounded run is readable in a single shot — no polling, no scrolling logs.

pnpm agent:setup                 # install → build → test (full suite)
pnpm agent:setup install         # one step at a time
pnpm agent:setup --json          # JSON summary on stdout (for scripts/agents)

Building

Use pnpm build to build all packages. ALWAYS redirect the output of the build command to a file:

pnpm build > build.log 2>&1

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

tail -n 20 build.log

If build outputs or the turbo cache are stale (e.g. after switching branches or worktrees) but dependencies haven't changed, use pnpm reset (lightweight by default) for a fast recovery: it cleans build outputs and force-rebuilds (keeping node_modules and untracked files). If that doesn't fix your issue, use pnpm reset --full, which also wipes untracked files and reinstalls dependencies.

Testing

• pnpm test - Run all tests
• pnpm test:affected - Runs tests based on what has changed since the last commit

Running a particular test file requires going to the directory of that test and running: pnpm test <test-file>.

When changing directories, use pushd to navigate into the directory and popd to return to the previous directory. When in doubt, use pwd to check your current directory.

Code Quality

• pnpm lint - Lint code
• pnpm typecheck - Run type checks

Always run lint and typecheck before committing code to ensure quality. Execute these commands from within the specific package directory you're working on (e.g., cd packages/cli && pnpm lint). Run the full repository check only when preparing the final PR. When your changes affect type definitions, interfaces in @n8n/api-types, or cross-package dependencies, build the system before running lint and typecheck.

Architecture Overview

Monorepo Structure: pnpm workspaces with Turbo build orchestration

Package Structure

The monorepo is organized into these key packages:

• packages/@n8n/api-types: Shared TypeScript interfaces between frontend and backend
• packages/workflow: Core workflow interfaces and types
• packages/core: Workflow execution engine
• packages/cli: Express server, REST API, and CLI commands
• packages/editor-ui: Vue 3 frontend application
• packages/@n8n/i18n: Internationalization for UI text
• packages/nodes-base: Built-in nodes for integrations
• packages/@n8n/nodes-langchain: AI/LangChain nodes
• packages/@n8n/instance-ai: "AI Assistant" in the UI, "Instance AI" in code — AI assistant backend. See its CLAUDE.md for architecture docs.
• @n8n/design-system: Vue component library for UI consistency
• @n8n/config: Centralized configuration management

Technology Stack

• Frontend: Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library
• Backend: Node.js + TypeScript + Express + TypeORM
• Testing: Jest (unit) + Playwright (E2E)
• Database: TypeORM with SQLite/PostgreSQL support
• Code Quality: Biome (for formatting) + ESLint + lefthook git hooks

Key Architectural Patterns

1. Dependency Injection: Uses @n8n/di for IoC container
2. Controller-Service-Repository: Backend follows MVC-like pattern
3. Event-Driven: Internal event bus for decoupled communication
4. Context-Based Execution: Different contexts for different node types
5. State Management: Frontend uses Pinia stores
6. Design System: Reusable components and design tokens are centralized in @n8n/design-system, where all pure Vue components should be placed to ensure consistency and reusability

Key Development Patterns

• Each package has isolated build configuration and can be developed independently
• Hot reload works across the full stack during development
• Node development uses dedicated node-dev CLI tool
• Workflow tests are JSON-based for integration testing
• AI features have dedicated development workflow (pnpm dev:ai)

Workflow Traversal Utilities

The n8n-workflow package exports graph traversal utilities from packages/workflow/src/common/. Use these instead of custom traversal logic.

Key concept: workflow.connections is indexed by source node. To find parent nodes, use mapConnectionsByDestination() to invert it first.

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

// Finding parent nodes (predecessors) - requires inverted connections
const connectionsByDestination = mapConnectionsByDestination(workflow.connections);
const parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1);

// Finding child nodes (successors) - uses connections directly
const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);

TypeScript Best Practices

• NEVER use any type - use proper types or unknown
• Avoid type casting with as - use type guards or type predicates instead (except in test code where as is acceptable)
• Define shared interfaces in @n8n/api-types package for FE/BE communication
• Lazy-load heavy modules — if a module is only used in a specific code path (not every request), use await import() at point of use instead of top-level import. Applies especially to native modules and large parsers.

Error Handling

• Don't use ApplicationError class in CLI and nodes for throwing errors, because it's deprecated. Use UnexpectedError, OperationalError or UserError instead.
• Import from appropriate error classes in each package

Frontend Development

• Refer to packages/frontend/AGENTS.md
• All UI text must use i18n - add translations to @n8n/i18n package
• Use CSS variables directly - never hardcode spacing as px values
• data-testid must be a single value (no spaces or multiple values)
• Always use design-system-rules skill in reviews

Testing Guidelines

• Always work from within the package directory when running tests
• Mock all external dependencies in unit tests
• 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.
• Confirm test cases with user before writing unit tests
• Typecheck is critical before committing - always run pnpm typecheck
• When modifying pinia stores, check for unused computed properties
• 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 Containers and Container.get(...) returns undefined.

What we use for testing and writing tests:

• For testing nodes and other backend components, we use Jest for unit tests. Examples can be found in packages/nodes-base/nodes/**/*test*.
• We use nock for server mocking
• For frontend we use vitest
• For E2E tests we use Playwright. Run with pnpm --filter=n8n-playwright test:local. See packages/testing/playwright/README.md for details.
• To iterate on a feature without docker rebuilds, boot service containers and run pnpm dev locally — pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy then pnpm dev. See Develop against running containers.
• 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).

Common Development Tasks

When implementing features:

1. Define API types in packages/@n8n/api-types
2. Implement backend logic in packages/cli module, follow @packages/cli/scripts/backend-module/backend-module-guide.md
3. Add API endpoints via controllers
4. Update frontend in packages/editor-ui with i18n support
5. Write tests with proper mocks
6. Run pnpm typecheck to verify types

Design Principles

Security Must Not Degrade the Building Experience

Security improvements, whether driven by enterprise requirements or internal standards, must NEVER add friction to the common-case building experience. When designing security-related features (defaults, behaviors, flows, error handling), apply these checks:

• No friction for the common case: A community builder's workflow should remain intuitive. Security should be invisible when it can be.
• Migration and upgrade paths: Existing users must have a clear, non-disruptive path forward when defaults or behaviors change.
• Security layers on top, not in competition: Great UX and strong security are not trade-offs. They're both required. If a design forces a choice between them, the design needs more work.

Security Fix Hygiene

This is a public repository. When working on security fixes, never expose the attack vector or vulnerability type in any public-facing artifact. Attackers monitor open-source repos for signals like branch names, commit messages, PR titles, test descriptions, and Linear URLs.

Rules for security fixes:

• Branch names: Do NOT use the Linear-suggested branch name if it reveals the vulnerability. Rename to describe the fix neutrally (e.g. node-1234-improve-request-handling, not node-1234-fix-ddos-vulnerability).
• Commit messages: Describe what the code now does, not the threat it prevents (e.g. fix: add payload size validation, not fix: prevent denial of service).
• Test descriptions: Use neutral, functional language (e.g. 'should sanitize query parameters', not 'should prevent SQL injection').
• Code comments: Do not describe the attack scenario in comments.
• Linear references: Never include the URL slug (e.g. .../N8N-1234/fix-ssrf-vulnerability).

Github Guidelines

• When creating a PR, use the conventions in .github/pull_request_template.md and .github/pull_request_title_conventions.md.
• Use gh pr create --draft to create draft PRs.
• If there is a corresponding Linear ticket, reference it in the PR description using https://linear.app/n8n/issue/[TICKET-ID]. Do not create a Linear ticket on your own — ask first.
• always link to the github issue if mentioned in the linear ticket.

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 conventions across 11 categories. From common project instruction files to newer agent-web discovery and trust formats.

Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot.

This repo keeps the map practical:

• Know what a file is for. Each entry names the convention, usual filename, primary readers, and spec or source.
• Study real examples. Examples are fetched from public repositories by script, with provenance kept at the top of each file.
• Separate practice from proposal. Maturity labels show what is widely used, what is early, and what is still only proposed.

Contents

• Instruction & context · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

What counts

This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints.

Any file type can qualify - .md, .txt, .prompty, .json, dotfiles, or a directory pattern. Human-first project docs such as README.md, CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md stay out unless the file has become an agent convention in its own right.

Maturity tiers

The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea.

Badge	Tier	Meaning
🟢	Adopted	Used in production by multiple tools, projects, or teams.
🟠	Emerging	Published by a real organization, but still early or limited in adoption.
🔵	Proposed	Publicly described, but without clear adoption beyond the proposal.

Instruction & context

Standalone page: categories/instruction-context.md

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	GEMINI.md AGENT.md QWEN.md WARP.md CONVENTIONS.md copilot-instructions.md	Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md	spec ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• AGENTS.md - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file.
• CLAUDE.md - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns.
• Tool-specific instruction files - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	Memory Bank	projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md	Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern)	spec ↗

• MEMORY.md - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time.
• Memory Bank - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant.

Spec-driven development

Standalone page: categories/spec-driven-development.md

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• Spec Kit - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation.
• Kiro steering files - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec.

Skills & prompt assets

Standalone page: categories/skills-prompt-assets.md

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• SKILL.md - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it.
• Prompt asset files - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames.
• Claude Code commands - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right.
• Copilot prompt & instruction files - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md.

Tooling & connections

Standalone page: categories/tooling-connections.md

	Convention	Files	Read by	Spec
🟢	MCP server config	.mcp.json	Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool	spec ↗

• MCP server config - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client.

Rules & ignore files

Standalone page: categories/rules-ignore-files.md

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/.mdc, .clinerules/, .windsurf/rules/.md).
• AI ignore files - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context.

Design

Standalone page: categories/design.md

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• DESIGN.md - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec.

Web & discoverability

Standalone page: categories/web-discoverability.md

	Convention	Files	Read by	Spec
🟢	llms.txt	llms.txt llms-full.txt (pattern)	Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it	spec ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• llms.txt - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven.
• pricing.md - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern.

Agent-web trust

Standalone page: categories/agent-web-trust.md

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• auth.md - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early.
• ai.txt - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵.

Identity & protocols

Standalone page: categories/identity-protocols.md

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early.

Proposed namespace

Standalone page: categories/proposed-namespace.md

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats.

Maintaining examples

Example files are fetched, not invented. The extractor pulls them from public sources, stores them under conventions/<slug>/examples/<source>/<filename>, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md before reusing them.

To refresh everything:

pip install -r scripts/requirements.txt
python scripts/extract.py          # fetch real files + rebuild each convention's README
python scripts/build_readme.py     # rebuild this README from scripts/targets.json

Re-running is idempotent. A missing target prints a miss and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB llms-full.txt) is truncated with a marker pointing back to the full source. scripts/targets.json remains the source of truth for conventions that have not been migrated yet; the skill-md pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts.

Shortcut targets are available in the Makefile:

make verify          # schema + generated files + example provenance + links
make extract         # refetch public examples and rebuild generated docs
make license-report  # summarize upstream licenses for vendored examples

CI keeps the generated files and links honest. The verify workflow checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with python scripts/check_links.py.

Contributing

Read CONTRIBUTING.md. In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to scripts/targets.json for non-migrated conventions, run the scripts, and open a PR. The skill-md pilot uses local convention metadata instead. Do not hand-write example files.

Before proposing adjacent standards, check WATCHLIST.md. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.