n8n-as-code

n8n-as-code provides a unified workflow model that can be applied across several different surfaces depending on your needs:

• Workspace environments: Managing active sync contexts and environments.
• Explicit sync: Moving workflows between environments.
• Local AI context: Providing context to AI agents (VS Code, Claude, etc.).
• Local managed instances: Running local n8n instances via Docker and tunnels.

Command Groups Summary

The monorepo consists of several specialized packages:

The monorepo is organized into several specialized packages:

• packages/cli: The n8nac facade and embedded sync engine.
• packages/workflow-core: Independent workflow contracts and the public workflow authoring API.
• packages/manager-adapter: A facade bridge to n8n-manager and credentials management.
• packages/skills: Workflow intelligence, node knowledge, documentation, and validation tools.
• packages/transformer: Handles conversion between workflow JSON and TypeScript.
• packages/mcp: The Model Context Protocol (MCP) facade for AI agents.
• packages/vscode-extension: The VS Code and Cursor extension facade.
• plugins/openclaw: The OpenClaw facade integration.

The n8n-as-code community is hosted on GitHub. You can interact with the project through the following channels:

• Discussions: Use GitHub Discussions to ask questions, share workflows, and discuss new ideas with other users and contributors.
• Bug Reports & Feature Requests: Use GitHub Issues to report bugs or request new features.
• Contributing: If you want to contribute code, documentation, or tests, refer to the Contribution Guide for architecture details and development setup instructions.

The extension provides two primary interfaces for workflow development:

Integrated Agent Workbench

An AI agent that operates with live n8n context. The agent has access to:

• The current workflow file and its metadata.
• Selected node or canvas context.
• The active n8n environment.
• The project and workflowsPath.
• The generated AGENTS.md file.
• Bundled n8n schemas, documentation, examples, templates, and validation rules.

Visual Workflow Workspace

• Sidebar: Browse both local and remote workflows via the n8n sidebar.
• Split View: Inspect the n8n canvas side-by-side with your source files.
• Workflow Sync: Explicitly pull, push, fetch, and resolve conflicts.
• Multi-environment: Work across multiple workspace environments without affecting your local instance state.

Depending on your preferred development environment, choose the appropriate tool:

• VS Code / Cursor: Use the VS Code Extension for a visual workspace and integrated Agent Workbench.
• Terminal / CI: Use the CLI for n8nac env management, syncing, validation, and automation.
• Managed local instances: Use n8n-manager to manage Docker instances, tunnels, and local machine state.
• Claude Code / Claude Desktop: Use the Claude Plugin for n8n skills and MCP-backed workflow work.
• Generic coding agents: Use the Skills Reference for portable n8n skills.
• OpenClaw: Use the OpenClaw Plugin for portable n8n skills inside OpenClaw.

The enhanced search algorithm uses relevance-based scoring rather than simple substring matching. When calling searchNodes(), results are ranked based on the following criteria:

• Exact name matches: 1000 points
• Display name matches: 800 points
• Keyword matches: 300 points
• Description matches: 100 points
• Operations matches: 100 points per match
• Use case matches: 80 points per match

This allows for multi-word queries (e.g., "generate image") to find nodes that satisfy multiple criteria.

The n8nac workspace is located at ~/.openclaw/n8nac/. It contains n8nac-config.json (storing workspace environments), AGENTS.md, .agents/skills/, and workflows/.

API keys and local managed instance state are kept local and are not stored in the config file. You can manually manage environments using the n8nac env command group.

# Manual environment setup example
n8nac env add Dev --base-url <url> --workflows-path workflows/dev
n8nac env auth set Dev --api-key-stdin
n8nac env use Dev
n8nac update-ai

# Adding an environment for a local managed instance
n8n-manager instance list
n8nac env add Local --managed-instance <id> --workflows-path workflows/local

When a user requests a workflow change, the Claude plugin follows this operational flow:

1. Context Gathering: Claude reads AGENTS.md and local skills.
2. Environment Check: Claude resolves the current n8nac env status.
3. File Management: Claude pulls or creates the relevant workflow files.
4. Knowledge Retrieval: Claude uses n8n node schemas and documentation.
5. Live Assistance: If the active environment has native MCP live assist configured, Claude uses it to access live n8n state.
6. Execution: Claude edits and validates the workflow, then pushes changes when requested.

The VS Code extension uses a specific model for managing workflow visibility:

• Tab-scoped Store: The Redux store is scoped to the active tab. When switching tabs, loadWorkflows() re-fetches with the new filter and replaces the workflow entries. The tree view always reflects the current tab's filter.
• Global Search: The "Find Workflow" command bypasses the tab-scoped store and calls cli.list() directly with includeArchived: true. This ensures the QuickPick search results include all workflows, regardless of which tab is currently active in the tree view.
• Auto-switching on Reveal: If a user selects an archived workflow from the QuickPick while the tree is viewing the standard "Workflows" tab, the extension automatically switches the tree to the "All" tab so the selected item is visible. The extension does not automatically revert to the previous tab after the reveal.