phantom-flow

What does phantom-flow do?

phantom-flow describes itself as "A tiny, local-first YAML workflow runner for the phantom-mesh ecosystem, describe an automation as declarative blocks, run it fully offline, or expose it to a mesh of AI agents over MCP." The author's own framing is: an automation is a YAML file, each step is a block, the runner executes them in order, logs the result and writes JSON artifacts.

Nine block types ship in the alpha. The README lists HTTP requests, text filtering, conditional logic and LLM summarisation among them. Template variables let one step's output feed the next. A gate block blocks the run until a user approves, which is useful for a sensitive step such as sending an email or publishing a post. The runner has dry-run, strict and validate modes for a check without running the real actions.

Key facts

• Licence: Apache-2.0.
• Runtime: Python, with PyYAML as the only hard dependency for the base engine.
• Blocks: nine shipped, including HTTP fetch, filter, LLM summary, gate, log and others listed in the README.
• Modes: dry-run, strict, validate.
• Gate blocks: pause execution until explicit approval.
• Template variables: pass data between steps.
• Schema validation: per-block.
• LLM fallback: stubs for LLM operations when a mesh model is not reachable.
• MCP server: AI agents can call phantom-flow to run a workflow.
• Tests: 124 passing at the time it was read.
• Status: alpha (Tier 1, per the README).
• Unshipped: image and video generation blocks, outbound publish governance, long-running daemon mode.

What does it replace, and where does it fall short?

phantom-flow replaces Zapier only for a narrow case: a developer who wants a scripted, YAML-first, local-first automation runner and does not need a visual canvas or a hosted dashboard.

Where it falls short: alpha, Tier 1 by the maintainer's own label. There is no visual canvas, so workflows are written in YAML. The nine shipped blocks do not cover the long tail of SaaS integrations that Zapier and Make sell. Image generation and video generation are roadmap items, not shipped. There is no long-running daemon mode in the alpha; the runner executes a workflow and exits. A commercial, hands-off Zapier user will find this too raw.

How does phantom-flow run?

Install from source: clone the repository, create a Python environment, install PyYAML and the local requirements. Write a workflow as a YAML file with named blocks. Run phantom-flow run <workflow.yaml>, or use --dry-run to exercise the steps without hitting any external service, --strict to fail on a soft error, and --validate to check the schema without running.

For AI agents, start the MCP server. A Claude Code or Cursor session can then call phantom-flow to run a workflow and receive the JSON artifacts back. Gate blocks block the run until the user approves them in the terminal.

Who is phantom-flow for?

A developer who wants a small, text-first automation runner they can read end to end, or who wants an MCP target for an AI agent to drive. A reader who wants a Zapier-style canvas and a large connector list is better served by n8n, Activepieces or FlowForge.

What limits does the README state?

• The project is alpha, Tier 1 per the maintainer.
• Nine block types ship in the alpha; image generation, video generation, publish governance and a long-running daemon are listed as unshipped.
• PyYAML is the only hard dependency for the base engine, so installs are small.
• The runner is a one-shot CLI; no daemon or scheduler is included.
• The LLM blocks need a reachable mesh model; stubs run without one.

Questions people ask

Is phantom-flow open source?

Yes. The repository is under the Apache-2.0 licence, an OSI-approved licence. The code is Python with PyYAML as the only hard dependency for the base engine, and the README names 124 passing tests covering the block execution and schema validation.

Does phantom-flow work offline?

Yes, in the default configuration. The runner reads a YAML file from disk, runs the blocks in order on the local machine and writes results as JSON. HTTP blocks call external services only when asked, and the LLM block has a stub fallback when a mesh model is not reachable. A workflow that uses only fetch, filter, log and gate blocks runs entirely on the local machine.

Can phantom-flow be used commercially?

Yes. Apache-2.0 allows commercial use, change and distribution without a fee, as long as the licence text and the notice travel with copies. There is no "non-commercial" clause in the licence, so a commercial team can self-host phantom-flow on its own hardware without talking to the maintainer.

How does phantom-flow compare with Zapier?

Zapier is a hosted product with a visual canvas, a large connector market and billing by task. phantom-flow is a Python CLI that reads YAML and runs nine block types on the local machine, with an MCP server so AI agents can drive it. The trade is: Zapier's hosted connector library and polish against phantom-flow's zero cost, text-first format and alpha scope. A reader who wants a middle ground should look at n8n on the open-source alternatives to Zapier page.

What is a "gate" block?

The README's answer is that a gate block pauses the workflow until the user explicitly approves. This is useful for a step that is expensive or hard to undo, such as sending an email, posting to a social feed, or publishing a file. The runner prompts in the terminal when it hits a gate, and either continues on approval or stops with a clear reason.

Sources

• phantom-flow README and LICENSE: github.com/markl-a/spectyn-flow, read 2026-11-09.