neitn>_

neitn is an AI-native CLI for modular n8n workflows.

Instead of editing one large exported n8n JSON file, neitn works with a project DSL:

• flow.yaml
• nodes/*.yaml
• edges/*.yaml
• code/*.ts
• code/*.runtime.ts
• code/__tests__/*.test.ts

This keeps AI tasks smaller, diffs cleaner, and Code nodes testable.

It now also has a first ADK-backed execution target for a supported synchronous subset, so an imported flow can be compiled into an embeddable runtime artifact and mounted inside a normal Node application.

Why This Exists

Raw n8n workflow JSON is expensive for AI to edit well:

• too much context
• too easy to rewrite unrelated parts
• hard to patch safely
• hard to test Code nodes

neitn solves that by splitting workflow structure and code into small files, then compiling back to standard n8n workflow JSON.

Install

From npm

npm install -g @neitn/cli

This installs the neitn CLI and an npm package that contains the bundled AI contract files.

To install the AI contract into a workflow project, use:

neitn agents:install . --ai codex

Inside a source checkout, the bundled source files live at:

• .agents/skills/neitn/
• docs/neitn/

In a global npm install, they are shipped inside the installed package directory.

There is no separate neitn skills install step today.

Local development

npm install
npm run build
npm run link:global

Quick Demo

There is now a self-contained mock example under examples/README.md.

Run it from the repo root:

npm run build
node examples/test-example.js

This will:

1. import examples/workflow.mock.json into a temp neitn project
2. compile it with --target adk
3. run the compiled flow locally
4. print the final mocked JSON response
5. keep the generated temp project on disk so you can inspect the imported DSL and generated dist/adk/*

Commands

neitn help
neitn --version
neitn init my-flow
neitn init my-flow --ai codex
neitn agents:install . --ai codex
neitn validate .
neitn apply .workflow/patches/some.patch.json
neitn doctor .
neitn migrate .
neitn build .
neitn compile .
neitn compile . --target adk
neitn import workflow.json
neitn code:scaffold assemble_final_response --node
neitn code:test .
neitn code:build .

What neitn Does Today

neitn already supports:

• project bootstrap with neitn init
• AI contract install with neitn agents:install
• import from existing n8n workflow JSON
• modular DSL editing through files
• apply and migrate for patch packages
• validate / doctor / compile / build
• Code node scaffold and split runtime/pure/test files
• first ADK-backed compile target for a supported synchronous subset
• generated ADK artifacts for:
  • local run
  • simple HTTP server
  • Express-compatible handler

What neitn does not do by itself:

• it does not generate patches on its own
• it does not include an autonomous AI agent runtime
• it does not yet turn a free-form natural-language request into a patch by itself

Patch generation is expected to come from:

• an external AI agent using the bundled skill contract
• not from humans manually writing patch JSON as the normal workflow

Workflow Lifecycle

Import existing n8n workflow

neitn import workflow.json

This creates a modular project:

flow.yaml
nodes/
edges/
code/
dist/

Create a new workflow from scratch

neitn init my-flow --ai codex
cd my-flow
neitn code:scaffold normalize_input --node
neitn validate .
neitn build .

That gives you:

• flow.yaml
• nodes/normalize_input.yaml
• code/normalize_input.ts
• code/normalize_input.runtime.ts
• code/__tests__/normalize_input.test.ts

You then add or edit:

• more nodes/*.yaml
• edges/*.yaml
• pure code in code/*.ts
• runtime wrappers only when n8n I/O needs to change

At this stage, creating a new workflow is a file-first flow. neitn gives you the project structure, scaffolded Code nodes, validation, import, build, apply, and migrate. It does not yet include a built-in prompt-to-patch generator.

If you already have a project and want to prepare it for an AI agent later:

cd my-flow
neitn agents:install . --ai codex

Validate and build

neitn validate .
neitn doctor .
neitn build .

Compile only

neitn compile .

Output:

dist/<flow.id>.workflow.json

Compile to ADK target

neitn compile . --target adk

Output:

dist/adk/workflow.json
dist/adk/runtime.js
dist/adk/agent.js
dist/adk/run.js
dist/adk/server.js
dist/adk/express.js

Current supported subset for the first ADK target:

• webhook
• code
• if
• httpRequest
• respondToWebhook
• set

The ADK target is intentionally not full n8n parity. Unsupported semantics should fail explicitly.

ADK Embedding

The generated ADK artifact can be used as a normal Node module.

Function call

const { runWorkflowViaAdk } = require('/path/to/workflow-project/dist/adk/agent.js');

async function evaluateIdea(input) {
  const { result } = await runWorkflowViaAdk(input);
  return result.response?.body ?? result.output?.[0]?.json ?? null;
}

Express route

After compiling the workflow project with --target adk:

const express = require('express');
const { createExpressHandler } = require('/path/to/workflow-project/dist/adk/express.js');

const app = express();
app.use(express.json());

app.post('/api/idea-evaluator', createExpressHandler());

app.listen(3000);

Or use the bundled example launcher:

node examples/express-server.js /path/to/workflow-project

Then call it:

curl -X POST http://127.0.0.1:3000/api/idea-evaluator \
  -H 'content-type: application/json' \
  -d '{"idea":"Wohnung renovieren in Wien","region":"Austria","language":"de","provider":"claude"}'

Example Files

The examples/ folder now contains:

• workflow.json — the large imported example flow
• workflow.mock.json — a smaller no-external-API demo flow
• input.json — sample input payload
• test-example.js — self-contained example runner
• express-server.js — simple Express server for compiled ADK flows

Code Nodes

New Code nodes can be scaffolded:

neitn code:scaffold assemble_final_response --node

This generates:

code/assemble_final_response.ts
code/assemble_final_response.runtime.ts
code/__tests__/assemble_final_response.test.ts
nodes/assemble_final_response.yaml

The intended split is:

• *.ts: pure business logic
• *.runtime.ts: thin n8n runtime wrapper
• __tests__/*.test.ts: unit tests for pure logic

Build injects the compiled runtime wrapper into final n8n JSON as parameters.jsCode.

Creating Nodes

Today there are two practical ways to create workflow pieces.

1. Direct file-first workflow

Use the CLI and edit the DSL directly:

neitn init my-flow
cd my-flow
neitn code:scaffold assemble_final_response --node

Then:

1. edit nodes/*.yaml
2. edit edges/*.yaml
3. edit code/*.ts
4. run neitn build .

This path is fully ready now.

2. AI patch workflow

If an external AI agent uses the bundled skill contract, it can emit patch JSON targeting the DSL.

Primary mode for a file-writing agent:

• create a new patch file in .workflow/patches/
• choose a timestamped descriptive filename automatically
• write only valid Patch Schema v0 JSON into that file

Fallback mode for a text-only agent:

• return only the patch JSON content so it can be saved into .workflow/patches/

Then you apply it with:

neitn apply .workflow/patches/your.patch.json

or migrate a folder of patches with:

neitn migrate .

This means:

• AI creates the patch
• neitn applies and validates it
• neitn build . compiles the final workflow JSON

So yes: patch-based AI editing is part of the model, but the current CLI does not itself generate those patches.

Humans normally should not hand-author patch JSON. For humans, the primary interface is the DSL files themselves.

3. Migration flow

If you keep patch files in .workflow/patches/, neitn can apply them as an ordered migration stream:

neitn migrate .
neitn validate .
neitn build .

This is ready now for applying existing patch files. What is not built into neitn yet is automatic patch authoring from natural language.

AI Editing Model

neitn is built so an AI agent can make smaller, higher-quality changes.

Source of truth:

• flow.yaml
• nodes/*.yaml
• edges/*.yaml
• code/*

Generated artifact:

• dist/*.workflow.json

The intended editing pattern is:

1. read only affected DSL files
2. change the smallest possible set of files
3. run neitn validate .
4. run neitn build .

Bundled Skills

The npm package contains the AI skills bundle.

In a repo checkout, the main entrypoint is:

.agents/skills/neitn/

These files are intended for AI-assisted workflow editing, not for runtime execution.

They describe:

• DSL conventions
• patch/editing rules
• import/build behavior
• code node structure
• roadmap/spec decisions

If you install neitn from npm, the skills ship inside the package so another agent can reuse the same editing contract with lower token cost.

There is no separate extra install step for skills inside the npm package. The main practical options today are:

• use neitn init <name> --ai codex
• or run neitn agents:install . --ai codex inside an existing project
• or use the repo checkout directly

The main skill entrypoint is:

.agents/skills/neitn/SKILL.md

The broader spec bundle lives under:

docs/neitn/

This keeps the installable skill entrypoint small while preserving the full AI contract and roadmap docs.

In practice:

• the skill tells an AI agent how to work against the DSL
• the docs bundle gives the deeper contracts and roadmap context
• the CLI executes validate/apply/build/compile steps

Recommended Packaging Model

For distribution, treat neitn as two layers:

Runtime layer

• CLI
• compiler
• validator
• import/build pipeline

AI layer

• bundled skills
• workflow editing conventions
• specs and contract docs

That combination is what makes the system useful for AI-native workflow development.

Current Scope

Included today:

• modular workflow DSL
• import from existing n8n workflow JSON
• validate / doctor / compile / build
• Code node scaffold
• Code node split runtime/pure/test files
• workflow round-trip fidelity improvements

Not the goal of v0:

• perfect automatic refactoring of arbitrary imported jsCode
• full n8n runtime simulation
• secret extraction or credential provisioning

Example Flow

neitn import workflow.json
neitn build .

After that:

• edit nodes/*.yaml
• edit code/*.ts
• run tests with neitn code:test .
• rebuild with neitn build .

Example: AI + Patches

If you have an external agent that understands the bundled skill:

1. it reads .agents/skills/neitn/SKILL.md
2. it edits DSL files directly or emits a patch package
3. you run:

neitn apply .workflow/patches/2026-04-24-some-change.patch.json
neitn validate .
neitn build .

If you keep patches as a migration stream:

neitn migrate .
neitn validate .
neitn build .

That workflow is supported now.

The intended user-facing prompt can stay short:

Use the neitn skill for this project.

Add:
- a webhook node `lead_webhook`
- an HTTP Request node `send_lead`
- a connection from `lead_webhook` to `send_lead`
- set `flow.entry` to `lead_webhook`

Patch file location, filename convention, and patch shape are skill-level defaults.

Example: Human + AI Flow

One practical flow today looks like this:

1. create the project:

neitn init my-flow --ai codex
cd my-flow
neitn code:scaffold normalize_input --node

2. let an external AI agent read:

.agents/skills/neitn/SKILL.md
docs/neitn/

3. the agent either:

• edits flow.yaml, nodes/*.yaml, edges/*.yaml, code/*.ts directly
• or writes a patch file into .workflow/patches/

4. then you run:

neitn validate .
neitn code:test .
neitn build .

5. if you are using patch files as history:

neitn migrate .
neitn build .

This means the current model is already usable for small AI tasks, but patch generation itself still belongs to the external agent layer, not to the CLI.

Notes

• DSL internal edges use node ids
• final n8n JSON connections use node names
• dist/*.workflow.json is generated output, not the editable source format