A Claude Code subagent that reads an exported n8n workflow JSON and tells you where it will fail in production.
n8n workflows pass review the same way: someone runs them once in the editor,
with clean test data and their eyes on the screen, and they work. Then they go
on a schedule and run unattended at 3am on the 200th item with a flaky upstream
API. That is where the editor stops helping. An HTTP node with no error branch
swallows a 500 and the whole run quietly stops. A Code node reads $json.total
when the upstream node only ever set amount. A webhook trigger has no auth. A
credential is referenced by an id that only exists on the machine it was exported
from. None of these show up until the day they take down a client's automation.
This agent reads the JSON and names each of those, by node, before you ship.
It traces the workflow the way n8n actually executes it — data flowing as items
along main connections, expressions reading only what an upstream node emits —
and applies a checklist grounded in real n8n behavior:
- Missing error handling on HTTP and integration nodes (a node with no On-Error setting halts the entire run on its first failure).
- Expressions that read fields nothing upstream produces —
$json/$node/$('Name')references that resolve toundefinedat runtime (n8n doesn't error on a missing field, it passes the silence downstream). - References to nodes that don't exist — a renamed or deleted node still named in an expression, which is a hard runtime error.
- Missing retries on third-party API calls that rate-limit and return transient 5xx.
- Unauthenticated webhook triggers — public endpoints anyone can fire.
- Hardcoded secrets and instance-specific credential ids — keys baked into the exported file, credentials that won't resolve on another instance.
- Schedule/Cron timezone assumptions — a "6am daily" job that fires at the wrong hour because no timezone is set.
- IF/Switch branches that go nowhere — items routed to an unwired output disappear with no log.
A one-line verdict (safe to run unattended, yes or no), then findings ranked P0 / P1 / P2. Each finding names the exact node, the failure scenario as it happens at runtime, the evidence it read, and a one-line fix.
[P0] Fetch Orders — no error handling on the only data source; run halts on first failure
Scenario: no On-Error is set and no error output is wired. The first time the
shop API returns a 5xx, the entire 6am execution stops here and nobody is told.
Evidence: node "Fetch Orders" has no onError/continueOnFail; only main[0] wired.
Fix: set On Error to "Continue (using error output)" and wire it to an alert.
It is read-only. It tells you what to change; it does not rewrite your workflow.
agents/n8n-flow-auditor.md the subagent (YAML frontmatter + system prompt)
references/failure-patterns.md the failure taxonomy the agent reasons from
references/node-data-model.md how n8n passes data ($json, $node, items, connections)
examples/broken-workflow.json a workflow with eight planted problems
examples/expected-audit.md what a correct audit of that file finds
INSTALL.md how to install and run it
See INSTALL.md. Short version: copy agents/n8n-flow-auditor.md
into ~/.claude/agents/ (all projects) or .claude/agents/ (one project), keep
the references/ folder next to it, then ask Claude Code to use it on a
workflow file.
> Use the n8n-flow-auditor on examples/broken-workflow.json
Then read examples/expected-audit.md to see the eight problems it should find.
- It reads the exported JSON statically. It does not run the workflow.
- It cannot know the shape of an external API's response from the export alone, so it flags those as a dependency to verify, not as a confirmed missing field.
- It covers the failure modes above. It is not a linter for every node type's every parameter, and it is not a security scanner for your n8n instance — it audits the workflow file you hand it.
MIT. See LICENSE.
Built by Velkina — https://velkina.com