n8n-as-code: agent context, TypeScript workflows and GitOps sync for n8n

Who n8n-as-code is for, and the problem it removes

n8n is a low-code workflow tool, but the artifact it produces is a large JSON graph. That format is fine for a canvas and poor for a diff. Renaming one node can move hundreds of lines, and an AI agent editing that JSON has no reliable way to know which node types exist, which parameters they accept, or whether the result will import. n8n-as-code attacks that gap from two directions at once: it gives the agent grounded knowledge about n8n nodes, and it gives the human a workflow representation that survives version control.

The README states the bundled node schema covers 537 nodes with full schemas and 7,700+ templates. Those numbers matter less than what they enable. An agent with a schema can refuse to invent a parameter. An agent with templates has working examples to imitate rather than a blank canvas. The project is explicit that it is an independent community project, not affiliated with, endorsed by, or sponsored by n8n, so the node knowledge is a snapshot maintained by the author rather than an official export.

The intended user is not someone who has never opened n8n. It is a developer or automation engineer who already has an n8n instance, wants workflows in Git, and wants an agent (Claude Code, Cursor, Copilot, or anything that reads a skills directory) to do the editing. The repository ships separate plugin folders for Claude and Cursor, plus a generic skills directory, which tells you the author expects the agent surface to vary by tool.

How the pieces fit: skills, CLI, MCP and the extension

The monorepo layout is the clearest statement of the architecture. The workspaces list in package.json includes packages/cli, packages/skills, packages/mcp, packages/vscode-extension and packages/telemetry, and the build script compiles them in a fixed order after running generate:nodes. That ordering is the mechanism: node schemas are generated first, then the skills package consumes them, then the CLI, MCP server and extension are built on top.

The skills package is the agent-facing layer. The README describes it as giving an agent n8n schemas, examples, validation rules and workspace commands. The CLI is the execution layer, and the README draws a distinction worth noting: workspace environments are repository context, while local managed instances are machine resources. In practice that means the environment definition (a base URL and a workflows path) can be committed, while credentials and runtime state stay local. The .env-example and .env.test.example files at the repository root, together with the statement that secrets and machine-local runtime state stay local, support that reading.

An MCP package exists in the workspace list, but the README excerpt does not document its tools or transport. Treat it as present in the repository and undocumented in the README; if you need MCP specifically, read packages/mcp before assuming behaviour. The same caution applies to the telemetry package, which is built but not described.

Installing n8n-as-code and pulling a first workflow

There are three entry points, and they are not equivalent. The VS Code and Cursor route is the extension: install it from the VS Code Marketplace or Open VSX, open a folder, open the extension, use the gear icon to configure the workspace, create or select an n8n environment, then pull or create workflows. That path assumes you want a UI for configuration.

The CLI route is the one that fits a scripted or headless setup. The README gives this sequence for an existing n8n URL, using npx so nothing is installed globally:

npx --yes n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev
printf '%s' "$N8N_API_KEY" | npx --yes n8nac env auth set Dev --api-key-stdin
npx --yes n8nac env use Dev
npx --yes n8nac update-ai

The first command registers an environment named Dev and points it at a workflows directory inside the repository. The second pipes the API key through stdin rather than passing it as an argument, which keeps it out of shell history. The third makes Dev the active environment. The fourth regenerates agent context for that workspace.

If you run n8n locally rather than at a URL, the README shows a managed instance path instead:

n8n-manager instance list
npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

After either setup, sync is explicit rather than automatic:

npx --yes n8nac list
npx --yes n8nac pull <workflow-id>

You should see the workflow written into the configured workflows path as a .workflow.ts file. The README does not document what n8nac list prints when the environment is unreachable, so verify that case yourself before wiring it into a pipeline.

Push, verify and promote across environments

Pushing is where the GitOps claim gets tested. The README gives this form:

npx --yes n8nac push workflows/dev/my-workflow.workflow.ts --verify

The --verify flag is the interesting part. It implies the tool checks the workflow against the instance rather than blindly uploading. What verification covers is not spelled out in the README excerpt; the validation rules live in the skills package and the schema generation step.

Promotion is the other half. The README documents promote as moving workflow source from one environment workflowsPath to another, and it does considerably more than copy files. It rewrites target project metadata, remaps credentials and supported Execute Workflow references, records stable source-to-target bindings in n8nac-promotion.json, and pushes by default unless --no-push is set. A dry run is available:

npx --yes n8nac promote --from Dev --to Prod --dry-run

The README states that --dry-run performs discovery for an accurate create/update plan but does not write files, push, or update the promotion config. That is a sensible split, and the n8nac-promotion.json file is the detail that matters most: it is the record of which source workflow maps to which target workflow, which is what makes repeated promotions idempotent rather than duplicating workflows. Note the word "supported" in front of Execute Workflow references. Sub-workflow remapping has limits, and the README does not enumerate them. The repository root contains a promote-plan.json, which suggests promotion planning has its own artifact beyond what the README describes.

Where n8n-as-code is the wrong tool

The README carries a compatibility note that should shape adoption more than any feature list: the node schema bundled with n8n-as-code is built against the latest stable release of n8n, and the README advises keeping your instance up to date for best generation and validation results. If your organisation pins n8n to an older version, the schema your agent reasons about will not match the nodes your instance actually has. That is a real failure mode, and it is not a bug that will be fixed by configuration. It is a consequence of shipping generated node knowledge inside the tool.

The second limitation is scope. This is an editing and delivery layer, not a runtime. It does not replace the n8n canvas for exploration, does not host n8n, and does not remove the need for an API key with sufficient permissions. The README is silent on rollback: there is no documented command to undo a push or revert a promotion. Your recovery path is Git, which means the workflows path must actually be committed before you push.

Third, the release history is worth reading as a signal. The most recent releases listed are v2.6.0-rc.6, v2.6.0-rc.5 and v2.6.0-rc.4, all release candidates within days of each other, and the last push to the repository was on 2026-09-10. A rapid rc cadence on a 2.6 line means the surface is still moving. The repository is not archived, but a project publishing release candidates at that rate is one where you should pin versions rather than track the latest tag in production automation.

How it differs from the n8n MCP server approach

The obvious alternative is an MCP server that exposes n8n operations as tools to an agent. The difference is in where the knowledge lives and what the durable artifact is. An MCP server typically gives an agent verbs: list workflows, get a workflow, create one, activate it. The agent then composes those calls, and the workflow it builds exists on the instance. Version control is something you add afterwards.

n8n-as-code inverts that. The repository is the primary location, the .workflow.ts file is the artifact you review and commit, and the instance is a target you push to. The agent's knowledge comes from generated schemas and templates in the skills package rather than from live introspection of your instance. That has a cost: the schema can drift from your n8n version, as the compatibility note warns. It has a benefit that matters more in team settings: a pull request containing a readable workflow diff is reviewable, and a sequence of MCP tool calls is not.

This is not a strict either/or. The repository contains a packages/mcp workspace, so the project is positioned to offer both surfaces. But the README's own framing, with explicit pull, explicit push and a promotion config file, points at the repository-first model as the intended workflow.

Licence and the cost of keeping up

The project is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice are retained. Nothing in the repository suggests a dual licence, a contributor licence agreement with commercial terms, or a separate enterprise tier. The README does link to a GitHub Sponsors page, which is funding rather than licensing. This is a description of the licence text, not legal advice; if you redistribute the tool inside a product, read the LICENSE file yourself.

The maintenance cost is the schema refresh cycle. Node schemas are generated during the build (the build script runs generate:nodes before compiling), and the README ties schema freshness to your n8n version rather than to a schedule. In practice that means upgrading n8n and upgrading n8n-as-code are coupled operations, and the rc-heavy release history suggests you should test a version bump against a non-production environment first. The promote command's --dry-run flag exists precisely for that kind of rehearsal. The repository also carries a MANUAL_TESTING.md and a SWEEP-FINDINGS.md at the root, which indicates the author maintains an explicit manual test surface alongside the automated one; if you fork, those files are where the untested edges are likely recorded.

Editorial conclusion

Adopt n8n-as-code if you already treat n8n workflows as repository artifacts and want an agent to edit them with node schemas and validation rather than guessing at JSON. Do not adopt it if you want a hosted GUI replacement, or if you cannot keep your n8n instance near the latest stable release, since the bundled schema is built against that release. Before committing, verify the environment round trip yourself: run npx --yes n8nac env add, then npx --yes n8nac list, then npx --yes n8nac pull <workflow-id>, and confirm the pulled file matches what the instance holds.

Frequently asked questions

Official sources

1. EtienneLescot/n8n-as-code on GitHub
2. License: MIT
3. Project website
4. README
5. Releases