n8n-as-code: keeping n8n workflows in Git and giving agents the node schemas
Give your AI agent n8n superpowers. 537 nodes with full schemas, 7,700+ templates, Git-like sync, and TypeScript workflows.
At a glance
- What is it?
- n8n-as-code is an MIT-licensed TypeScript toolkit that stores n8n workflows as .workflow.ts files, syncs them explicitly against named environments, and ships agent skills backed by bundled node schemas. It is worth a look if your automation lives in a repository and your editor is where you work; it is not a hosted n8n replacement.
- Who is it for?
- Adopt n8n-as-code if your n8n workflows already live in a Git repository, you run more than one n8n environment, and you want an agent to edit .workflow.ts files against bundled schemas rather than against its own memory of n8n nodes.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap n8n-as-code fills between the n8n canvas and a repository
n8n is a visual workflow tool. Work you build there tends to live in the instance, which makes review, rollback and environment promotion awkward once more than one person or more than one environment is involved. n8n-as-code takes the position that a workflow should be a file in a repository, and that an AI agent should be able to edit that file without inventing node parameters. The README frames the project as turning a repository into a full n8n development workspace, with five stated capabilities: editor-native workflow work, agent-ready context, GitOps-style sync, TypeScript workflow authoring, and live n8n operations. The audience is narrow and specific: teams already running n8n who use VS Code, Cursor or Claude Code, who want workflow source under version control, and who are willing to run CLI commands rather than only clicking in a canvas. It is an independent community project, and the README states plainly that it is not affiliated with, endorsed by, or sponsored by n8n. That matters for procurement: you are adding a third-party layer in front of your automation platform, not an official extension of it.
Workflow files, environments, and the agent context layer
The architecture visible in the README separates three kinds of state. Workflow source lives in the repository as .workflow.ts files, described as readable TypeScript that people and agents can edit. Repository context lives in workspace environments, each with a name, a base URL and a workflows path. Machine-local resources, such as a locally managed n8n instance, stay on the machine. The README is explicit that secrets and machine-local runtime state stay local, and that the repository stores workflow files, generated agent context and workspace-safe configuration. The agent side is a generated context layer rather than a live API call: the project bundles node schemas (the description says 537 nodes with full schemas), templates, examples and validation rules, and exposes them through skills such as n8n-architect. The CLI command npx --yes n8nac update-ai is what regenerates that context. So the data flow is: pull workflow source from an n8n environment into the repository, let a person or agent edit the TypeScript, validate and push it back, and refresh the generated context when node knowledge changes. The schema is built against the latest stable n8n release, which is why the README asks you to keep your instance current.
Installing the extension, the skills, or the CLI
There are three entry points and they are not mutually exclusive. For editors, install the extension from the VS Code Marketplace or Open VSX, open a folder or a .code-workspace, click the extension icon and then the gear icon to configure the workspace, create or select an n8n environment, and pull or create workflows. For Claude Code, the README gives two commands: /plugin marketplace add https://github.com/EtienneLescot/n8n-as-code followed by /plugin install n8n-as-code@n8nac-marketplace. For other agents, point the agent at the skills directory in the repository, or at skills/n8n-architect if it wants an explicit path. The CLI path is the most concrete. To register an existing n8n URL as a named environment: npx --yes n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev, then pipe the API key in with printf '%s' "$N8N_API_KEY" | npx --yes n8nac env auth set Dev --api-key-stdin, then npx --yes n8nac env use Dev, then npx --yes n8nac update-ai. A local managed instance is attached differently, through n8n-manager instance list and npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local. Sync is explicit: npx --yes n8nac list, npx --yes n8nac pull <workflow-id>, and npx --yes n8nac push workflows/dev/my-workflow.workflow.ts --verify. Nothing here happens implicitly, which is the point.
Promotion between environments is the most opinionated part
The promote command is where the project stops being a file-sync wrapper and starts making decisions on your behalf. The README describes it as moving workflow source from one environment workflowsPath to another, either for a single workflow path or, when omitted, for every *.workflow.ts file in the source environment including nested folders. Along the way it rewrites target project metadata, remaps credentials and supported Execute Workflow references, and records stable source-to-target bindings in n8nac-promotion.json. It pushes by default unless --no-push is set. And --dry-run performs discovery so the create/update plan is accurate, but does not write files, push, or update the promotion config. That last detail is the one to read twice: the dry run is a plan, not a rehearsal that leaves any trace. The credential remapping is also the sharpest edge. It handles credentials and Execute Workflow references it supports, and the word supported implies there are cases it does not. If your Dev and Prod environments use different credential names or a reference pattern outside that set, the promotion config is the artifact to inspect before you trust a push. The n8nac-promotion.json file is effectively a state file for the Dev-to-Prod relationship, and it belongs in review like any other committed file.
Where the schema-bundling approach breaks down
The most honest limitation is stated by the project itself: the node schema bundled with n8n-as-code is built against the latest stable release of n8n, and the README asks you to keep your instance up to date for the best generation and validation results. Read that as a coupling, not a suggestion. If your n8n instance trails the stable release, or if you run a version with custom or community nodes, an agent generating workflow steps from the bundled schema may produce nodes or parameters that do not match what your instance actually accepts. The --verify flag on push exists because of this class of mismatch. A second limitation is scope: this is not a hosted n8n and it does not replace the canvas. The README describes browsing, opening, editing, validating and syncing workflows, and inspecting credentials, running tests, activating workflows and inspecting executions against a selected environment. What it does not offer is a visual editor for people who do not want to read TypeScript. A team whose workflow authors are non-developers will find .workflow.ts files harder to review than a canvas, and the GitOps model assumes someone is comfortable with pull requests and conflict resolution. Finally, the release history supplied here is entirely v2.6.0 release candidates, the most recent being v2.6.0-rc.6. Release candidates are not a stability guarantee, and there is no stable v2.6.0 in the material provided.
How this differs from editing n8n in the browser
The obvious alternative is the n8n editor itself: build in the canvas, let the instance hold the definition, export JSON when you need a copy. The difference is not cosmetic. In the canvas model the instance is the source of truth and review happens after the fact, if at all. In the n8n-as-code model the repository is the source of truth and the instance is a target you push to, which is why pull and push are separate explicit commands rather than a background sync. That separation costs you keystrokes and buys you diffs. It also changes what an agent can do. An agent working against a canvas has no stable artifact to edit and no schema to check against; an agent working in this repository edits a .workflow.ts file and has the bundled node schemas, examples and validation rules available through the skill. The trade is real in both directions. You gain reviewable history and environment promotion with a dry-run plan. You lose the immediacy of clicking a node and seeing it run, and you take on a dependency on a community project that tracks n8n's stable release rather than being part of it. Teams that never promote between environments and never review workflow changes get little from the swap.
Licence, maintenance, and what upgrading actually costs
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and it is the same one many tools in this space use. It is not legal advice; if you redistribute the toolkit inside a product, have your own counsel read the LICENSE file rather than this paragraph. On maintenance, the material shows a project that is actively pushed to, with three release candidates inside a week in September 2026 and a documentation site at n8nascode.dev carrying getting-started, VS Code, CLI, skills and Claude plugin guides. The Claude Code integration is labelled Beta / Pending Review in the README badges, so treat that path as less settled than the CLI. The upgrade cost that matters is not the package version, it is the generated context. Because the bundled schema is tied to the latest stable n8n release, upgrading n8n and upgrading n8n-as-code are effectively one operation if you want generation and validation to stay accurate, and npx --yes n8nac update-ai is the step that refreshes the agent-facing side. Plan for that as a recurring task tied to your n8n upgrade cadence, not a one-time install.
Editorial conclusion
Adopt n8n-as-code if your n8n workflows already live in a Git repository, you run more than one n8n environment, and you want an agent to edit .workflow.ts files against bundled schemas rather than against its own memory of n8n nodes. Do not adopt it if you treat n8n purely as a hosted canvas and have no intention of reviewing workflow diffs in a pull request, or if you cannot keep your n8n instance on the latest stable release, since the README states the bundled schema is built against that release. Before committing, verify three things in your own workspace: that npx --yes n8nac list returns the workflows you expect from your instance, that a single npx --yes n8nac pull <workflow-id> produces a .workflow.ts file your team can read, and that npx --yes n8nac promote --from Dev --to Prod --dry-run prints a create/update plan you agree with. The release line is still at v2.6.0-rc.6, so pin the version you test.
Community notes