chainq

Source: README.md · repository commit df39fcf

Prompt chaining for people who live in prompts — not in dashboards.

Wire a few prompts together, run them on the CLI model you are already logged into (claude -p, or any CLI that takes its prompt on stdin), and watch every step light up on the same canvas you built it on. One YAML file. Your existing CLI login does the authenticating — no model credentials in the flow, and no hosted runtime to operate.

Why chainq

You chain prompts all day — translate then format, draft then critique, extract then assemble. But the tools for “automating” that are built for a different job:

	n8n · Make · Zapier	chainq
Where it runs	a server / their cloud	your machine, your CLI model
Credentials in the flow	API keys, OAuth, billing	none — use your existing local CLI login
Editing vs. running	build here, check the run log over there	same canvas — edit it, run it, see it
The artifact	a config locked in their UI	one YAML file you own and git it
Learning curve	a node ecosystem	5 node types, one page

If you’ve ever thought “this is just three prompts in a row, why do I need a whole platform?” — that’s the gap chainq fills.

The one thing that’s different: edit and run are the same screen

In most automation tools you build a flow, push it to run somewhere, then open a separate “executions” view to see what happened. In chainq there is no over-there.

The canvas you wire is the canvas that runs. Hit Run and each node streams its own status live — running → ran / cached / failed — with its real output rendered right on the node card. Tweak one prompt, re-run without even saving (your edit is kept as a draft; the file stays untouched until you Save or ↩ Reset), and tune one step at a time until the whole chain is right.

That’s the loop: see the flow, run the flow, read the result — in one place.

Quickstart

npm i -g @wahengchang2023/chainq    # install once, get the `chainq` command
chainq init my-flow && cd my-flow   # scaffold a runnable starter flow
chainq ui flow.yaml                 # open the editor — edit + run on one canvas

That is the whole install — @wahengchang2023/chainq on npm is the only thing chainq needs. Prefer not to install globally? Swap chainq for npx @wahengchang2023/chainq in any command. If you also want your coding agent to write flows, there is an optional agent skill — next section, nothing depends on it.

Tune your flow on the canvas, then run it from the terminal to land the output — same YAML, no extra export step:

chainq run flow.yaml    # run the whole flow; output lands in the file your write step names

Needs Node ≥ 18. ai steps call your real local model — run claude login first.

Optional: let your coding agent write the flow

chainq runs without this. But the same repository ships an agent skill that teaches Claude Code (and any agent reading the same format) what a chainq flow is — so “build me a flow that reads notes.md, pulls out the decisions and the open questions, and writes a summary to out/” produces an actual prompt chain, not a YAML file wrapped around a shell script. Take it one step at a time:

# try it on one request, installing nothing — prints the skill as a prompt
npx skills use wahengchang/chainq@chainq | claude

# keep it in this project (the default scope, committed with your repo)
npx skills add wahengchang/chainq --skill chainq

# or once, for every project on this machine
npx skills add wahengchang/chainq --skill chainq -g

That is the open skills CLI — one source, installed into Claude Code, Codex, Cursor, opencode and a dozen more. Claude Code users can use a plugin instead, tracking this repository:

/plugin marketplace add wahengchang/chainq
/plugin install chainq@chainq

What a flow looks like

A flow is a small graph of steps in one YAML file. Here a trigger fans out to a few steps, then ai + schema assembles them into guaranteed-valid JSON and write saves it — the whole thing readable top to bottom:

steps:
  trigger:                       # input — the data to feed in
    type: input
    params:
      text: { type: string, default: 'The early bird catches the worm.' }

  field_a:                       # assemble — carry the original value through, no model call
    type: assemble
    from: trigger
    prompt: '{{ $json.text }}'

  field_b:                       # ai — call the model for one value
    type: ai
    from: trigger
    prompt: 'Translate to Traditional Chinese, output only the translation: {{ $json.text }}'

  to_json:                       # ai + schema — output is parsed & validated as real JSON
    type: ai
    from: [field_a, field_b]
    schema: { original: string, zh_tw: string }
    prompt: |
      Build a JSON object copying each value verbatim:
        original: {{ $('field_a') }}
        zh_tw:    {{ $('field_b') }}

  result:                        # write — land it as a file
    type: write
    from: to_json
    path: out/result.json

Every step is one of 5 node types: ai (calls the model), cmd (a local command, executed without a shell), assemble (reshape / combine items), input (the trigger), or write (save a file). Full runnable version: examples/generate-json.yaml.

How you drive it

• Visual editor (chainq ui) — drag-to-connect, insert-a-step-on-a-wire, switch a node’s type in place, marquee-select, Space-to-pan, double-click to edit. Data-flow wires (the $json main input) and reference wires ($('id') cross-step lookups, even several steps back) read distinctly — warm-solid vs. cool-dashed, toggle to hide references. Give a slow step room with a per-node ◷ timeout so a long ai run isn’t killed mid-flight. Binds to 127.0.0.1 only.
• CLI — chainq init · new · run · validate · ls. run re-runs everything by default; add --cache to reuse unchanged steps.

Documentation

• Documentation map — choose a tutorial, guide, reference, or concept page.
• Getting started — install chainq and complete a first run.
• CLI reference and flow YAML reference — look up commands and configuration.
• Visual editor guide and common tasks — complete specific workflows.
• Agent skill — install the skill that teaches an agent to author flows.
• Troubleshooting — resolve common validation, model, cache, and output problems.
• Changelog — review released changes.

Elsewhere:

• Documentation site — every page above, hosted and searchable; the reliable route if you are reading this on npm.
• chainq on npm — the published package: versions, what ships in the tarball, install size.
• GitHub repository — source, issues, and the runnable flows in examples/.

Security

chainq runs local models you already trust; every subprocess is spawned with an argv array, never a shell string (no command injection). chainq ui binds to 127.0.0.1 on a random port — don’t expose it to an untrusted network.

License

MIT © wahengchang