squadcue

Flow Canvas — User Manual

What the canvas is

The canvas is a drag-and-drop pipeline editor (built on Drawflow) for wiring repeatable agent workflows out of typed nodes: fetch a page, summarize with Claude, pause for human approval, push to Telegram. The canvas is just a view over a graph JSON — hitting Run converts the graph you currently see into a staged run (topological sort; independent nodes execute in parallel). Every run stores a snapshot of the flow definition (runs/<id>/flow_snapshot.json) plus per-node params, output, duration, and errors (runs/<id>/steps.json), so any run can be replayed or audited later.

Quick start

1. Open the Canvas tab and pick Demo: fetch → AI summary → approve → notify (flows/demo_daily_digest.json) from the flow selector.
2. The demo has 4 nodes wired in a line:
   • n1 · fetch — downloads the Hacker News front page, strips HTML.
   • n2 · claude — prompts Claude (sonnet) to summarize the 5 most interesting stories, injecting the page text via ``.
   • n3 · gate — pauses the run and shows the digest for human approval (1-hour timeout).
   • n4 · tg — pushes the approved digest to your Telegram.
3. Hit Run. When the gate fires, a Telegram card with Approve / Reject buttons arrives on your phone — first response wins, no need to open the cockpit.
4. Single-click a node to see its live result panel; double-click to edit its params (JSON) and label.

Node reference

Parameter names below are exactly what flow_engine.py reads from params. Any string param marked templatable accepts `` (see next section).

action

Runs a predefined console action (a registered local command) and captures its output.

• Params: action_id — id of a registered action (picked from the palette).
• Output: last 4000 chars of stdout.
• Example: a nightly “rebuild portal” action followed by a tg node.

claude

Spawns a one-shot headless Claude CLI (claude -p) with your prompt on stdin.

• Params: prompt (templatable, required), model (e.g. sonnet; optional), allow_tools (boolean — adds --dangerously-skip-permissions).
• Output: trimmed stdout, last 4000 chars.
• Example: {"model":"sonnet","prompt":"Summarize:\n"}.
• Security: keep allow_tools off for flows that ingest untrusted input (web/file content flows into the prompt — prompt injection is your risk to accept). ANTHROPIC_API_KEY is stripped from the child env so the CLI stays on subscription billing.

codex

Spawns Codex CLI as a read-only red team (codex exec --sandbox read-only) — it can inspect the workroot but cannot write files. Use it for second opinions and reviews, not for making changes.

• Params: prompt (templatable, required).
• Output: trimmed stdout, last 4000 chars.
• Example: prompt "Red-team this plan for failure modes:\n".

gate

Human approval checkpoint. Pauses the run, pushes a Telegram button card (Approve / Reject), and waits. Anything other than approve stops the flow.

• Params: message (templatable; shown in the approval card), timeout (seconds, default 7200).
• Output: the string approved (on the approve path only).
• Example: {"message":"Send this?\n","timeout":3600}.
• Security: decisions are single-writer — first response (web or Telegram) wins, enforced at the SQLite layer and audited. Timeout means deny, never approve.

shell

Runs a PowerShell command (powershell -NoProfile -Command <cmd>).

• Params: cmd (required), timeout (seconds, default 600).
• Output: last 4000 chars of stdout.
• Example: {"cmd":"Get-ChildItem C:\\Users\\me\\reports | Select -Last 5"}.
• Security: `` interpolation is refused in cmd — upstream data templated into a command string is an injection surface. The node raises an error if the template appears; pass data between nodes via readfile/writefile instead.

fetch

Downloads an http/https URL (2 MB cap, 30 s timeout) and optionally strips HTML tags.

• Params: url (templatable, required, must start with http:///https://), strip_html (boolean, default true).
• Output: page text, first 8000 chars. Chain a claude node for finer cleanup.
• Example: {"url":"https://news.ycombinator.com/","strip_html":true}.
• Security (SSRF guard): the hostname is resolved first and loopback / private / link-local / reserved addresses are rejected; redirects are never followed (use the final URL).

tg

Sends a Telegram message via the configured bot.

• Params: text (templatable, required; truncated to 3800 chars on send).
• Output: sent or failed.
• Example: {"text":"📰 Daily digest:\n"}.

wait

Sleeps for a fixed interval — useful to space out API calls or wait for a file drop.

• Params: seconds (default 10, capped at 600).
• Output: none.

readfile

Reads a local text file via Python (UTF-8 first, falling back through utf-8-sig / cp950 / big5 — avoids console codepage mangling). The path supports glob patterns; with a glob it auto-picks the newest match by lexicographic sort, so dated filenames like report_2026-08-03.json resolve to the latest one.

• Params: path (templatable, required; glob allowed).
• Output: file text, first 8000 chars.
• Example: {"path":"Z:\\daily_info\\digest_*.json"}.
• Security: can read any file your user can — treat flow definitions as trusted config.

writefile

Writes (or appends) text to a local file as UTF-8 via Python.

• Params: path (templatable, required), content (templatable), append (boolean, default false; append mode adds a trailing newline).
• Output: wrote <resolved path>.
• Example: {"path":"C:\\Users\\me\\out\\digest.md","content":"","append":false}.
• Security: the resolved path is contained to your home directory root via resolve().relative_to(home) — substring tricks and .. traversal don’t work; writes outside home are refused.

kb

BM25 full-text search (CJK-friendly) over your locally indexed markdown folders.

• Params: query (templatable, required), k (number of hits, default 5).
• Output: matched snippets joined with ---, first 6000 chars, each prefixed [source].
• Example: {"query":"warrant liquidity rules","k":5} feeding a claude node.

swarm ⚠ experimental

Runs N parallel Claude calls on the same prompt from different angles (default angle set: optimistic / critical fault-finding / data-driven / user perspective / contrarian), then optionally merges them into one balanced conclusion with a final Claude call.

• Params: prompt (templatable, required), n (default 3, capped at 5), model (default sonnet), angles (list of strings, optional), merge (boolean, default true).
• Output: the merged synthesis, or all angle answers joined with --- if merge is false (4000-char cap).

tournament ⚠ experimental

Runs N parallel attempts at the prompt, then a judge call scores them on your criteria and the winning attempt’s text is passed downstream.

• Params: prompt (templatable, required), n (default 3, capped at 5), model (default sonnet), criteria (default "correctness, completeness, actionability").
• Output: the winning attempt (falls back to attempt 1 if the judge’s JSON is unparseable), 4000-char cap.

pipeline (advanced)

Inlines the stages of a registered server-side pipeline into the flow.

• Params: pipeline_id. Only useful if you have pipelines registered; most users won’t need this node.

Wiring data between nodes

Every node stores its output under its node id in a shared results map. Downstream nodes reference it with double-brace templating, exactly:

• The id is the node’s canvas id (n1, n2, … — visible in the exported/saved flow JSON; ids match [A-Za-z0-9_-]). Whitespace inside the braces is tolerated: `` also works.
• Each substitution is truncated to 4000 chars. An unknown id substitutes as an empty string — it does not error, so typos fail silently. Check the node’s stored result in the run detail if a prompt looks empty.
• Templatable fields: prompt (claude/codex/swarm/tournament), message (gate), text (tg), url (fetch), path (readfile/writefile), content (writefile), query (kb). Not cmd (shell) — deliberately refused, see above.
• Edges only decide execution order. Data does not flow along edges; it flows through `` references. You must still draw an edge from producer to consumer so the producer runs first.
• Scheduling: nodes whose dependencies are satisfied run in parallel (up to 4 at a time); ties are ordered by canvas y-position (higher runs first). Gate nodes always run alone as a barrier. Cycles are rejected at run time.

Runs, retry, and approval

• Every run is snapshotted. flow_snapshot.json records the exact graph that ran; steps.json records per-node status, params, result (4000-char cap), duration, and error.
• Retry has two buttons (n8n-style), via POST /api/runs/<id>/retry?mode=…:
  • original — rerun from that run’s snapshot: guaranteed-reproducible, even if the flow was edited or deleted since.
  • current — rerun from the currently saved version of the same flow id: picks up your fixes. Fails with an explanation if the run was an unsaved canvas version or the flow was deleted (retry with original instead).
  • The new run records retry_of lineage back to the source run, and reports whether the current version differs from the snapshot.
• Approval gates: default state is undecided. First response wins across web UI and Telegram (single-writer, enforced at the SQLite layer); every decision is audited. On timeout the gate denies and the flow stops — a silent phone never approves anything.

This site is open source. Improve this page.