Auto Flow MCP and CLI

Auto Flow MCP and CLI gives local coding agents a guarded way to work with Auto Flow Agent Mode runs. It does not replace the Chrome extension or your Flow session. It connects to your local Auto Flow extension bridge, then exposes status, reconcile, retry, download, and QA tools to terminals and MCP clients.

Current channel: 10.8.22.

Install

npm install -g @autoflow-mcp/[email protected]
autoflow --help
autoflow-mcp --version

Use the pinned package that matches the installed extension. Older beta builds may lag behind the current extension bridge.

What This Adds

• CLI commands for Auto Flow Agent Mode runs from any project folder.
• MCP tools for Codex, Claude, and other MCP clients.
• A local native bridge between the terminal and the installed Chrome extension.
• Reconcile reports that map Flow outputs back to row IDs.
• Guarded retry and submit requests with explicit project/tab targeting.
• Download planning and execution through the browser session that owns Flow.
• Transcript QA helpers for deciding which rows need retry prompts.
• Stateful run profile defaults so agents show defaults first and ask only for overrides.
• Organized output folders and continuity packs for generated, uploaded, and promoted reference images.

Flow Agent creates the media. Auto Flow tracks it, reconciles it, retries it, downloads it, and gives other agents a stable interface to operate against.

Requirements

• macOS with Chrome or Chrome for Testing.
• Auto Flow Chrome extension installed and signed in.
• A Google Flow project tab open in the same Chrome profile.
• Auto Flow Bridge enabled in the extension.
• Node.js 20 or newer.
• Active Auto Flow Pro for bridge-backed live workflows. Read-only CLI/MCP setup can run before Pro, but live submit/retry/ref attach/credit confirm and execute-download actions are Pro-only.

Native Bridge Setup

Install the package, then register the native host for the extension id mounted in your Chrome profile:

autoflow native install-host --extension-id <extension-id> --doctor
autoflow native install-host --extension-id <extension-id>

Pair the terminal with the extension:

autoflow pair
autoflow pair --code <code-shown-in-extension>
autoflow status --json
autoflow context --json

If the host restarts or the extension reloads, pairing can reset. Run the pair commands again.

MCP Setup

Add the MCP server to your MCP client config:

{
  "mcpServers": {
    "autoflow": {
      "command": "autoflow-mcp",
      "args": []
    }
  }
}

Then ask the agent to start read-only:

Use Auto Flow MCP. First call autoflow_context and autoflow_status, then autoflow_reconcile_project.
Use Veo 3.1 - Lite [Lower Priority] as the cost-safe video default; do not assume Omni Flash is cheapest.
Show the stateful run profile defaults first, then ask only for overrides,
missing values, and exact credit approval. Do not submit, retry, or spend
credits unless I approve it.

Claude Skill and Codex skill

The package ships Claude and Codex skills so agents can learn the Auto Flow operating contract instead of improvising commands. Source folders in the npm package are claude-skills/autoflow-agent and codex-skills/autoflow-agent; most users should use the installer command below instead of copying those folders manually.

Install or update both skills globally after installing the package:

autoflow skill install --target both --force

Install only one agent skill if needed:

autoflow skill install --target claude --force
autoflow skill install --target codex --force

Install into the current project instead of the user profile:

autoflow skill install --target both --scope project --force

Then ask Claude or Codex:

Use the autoflow-agent skill. Start read-only with status/inventory, then build
the prompt matrix and dry-run the Agent Mode submit before any live generation.
Use the context command/tool to explain model costs first: Veo 3.1 - Lite
[Lower Priority] is the cost-safe video default; Omni Flash is for Omni-specific
workflows after approval, not the cheapest default.
Ask me for model, outputs, ratios, silent-video setting, and credit approval
before any live submit or credit confirmation only when those values override or
complete the shown defaults.

Run Profile Defaults

Unless the project, packet, or user overrides them, Agent Mode starts from this profile: Nano Banana 2 images, 1 image output, project/default image aspect, Veo 3.1 - Lite [Lower Priority] videos, 1 video output, project/default video aspect, 8 second videos, auto-download images/videos on, and outputs/<run-name>/ as the output root. Return silent videos must be confirmed for the exact video run.

Outputs and Continuity

Use one run folder per job:

outputs/<run-name>/
  images/
  videos/
  refs/
  manifests/
  qa/
  retries/

Continuity packs record generated Flow refs, local uploaded refs, and promoted refs that can be reused later. Ref reuse is valid only after Auto Flow proves the actual prompt asset chips were visible before submit.

Plan ref reuse before submit:

autoflow agent refs attach --ref HOST_001=flow:V1-S1/media-id --dry-run --json

Live ref attachment is chip-gated. If Auto Flow cannot prove the Flow Agent prompt chips are visible, it fails closed instead of submitting with missing character/product references.

Prove MCP Works

This verifies the published package at the MCP protocol layer, not just the CLI binary:

tmpdir=$(mktemp -d /tmp/autoflow-npm-mcp-smoke-XXXXXX)
cd "$tmpdir"
npm init -y >/dev/null
npm install @autoflow-mcp/autoflow
node - <<'NODE'
const { spawn } = require("node:child_process");
const child = spawn("./node_modules/.bin/autoflow-mcp", [], { stdio: ["pipe", "pipe", "pipe"] });
let out = "";
let err = "";
child.stdout.on("data", (d) => { out += d; });
child.stderr.on("data", (d) => { err += d; });
function send(message) {
  child.stdin.write(JSON.stringify(message) + "\n");
}
send({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "autoflow-npm-smoke", version: "0.0.0" } } });
send({ jsonrpc: "2.0", method: "notifications/initialized", params: {} });
send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
setTimeout(() => {
  child.kill();
  const messages = out.trim().split(/\n+/).filter(Boolean).map((line) => JSON.parse(line));
  const init = messages.find((message) => message.id === 1);
  const tools = messages.find((message) => message.id === 2);
  const toolNames = (tools?.result?.tools || []).map((tool) => tool.name);
  console.log(JSON.stringify({
    ok: Boolean(init?.result && toolNames.includes("autoflow_status")),
    serverInfo: init?.result?.serverInfo,
    protocolVersion: init?.result?.protocolVersion,
    toolCount: toolNames.length,
    toolNames,
    stderr: err.trim()
  }, null, 2));
}, 1200);
NODE

Expected result: ok: true, server name autoflow-mcp, and tools such as autoflow_status, autoflow_reconcile_project, autoflow_wait_for_render, autoflow_confirm_credits, autoflow_attach_refs, autoflow_retry_rows, and autoflow_download_outputs.

Common CLI Commands

autoflow status --json
autoflow agent reconcile --project current --json
autoflow agent run --input prompts.txt --project-id <project-id> --tab-id <tab-id> --lane-id <lane-id> --dry-run --json
autoflow agent run-and-wait --input prompts.txt --project-id <project-id> --tab-id <tab-id> --lane-id <lane-id> --wait-timeout-ms 1200000 --json
autoflow agent confirm-credits --project-id <project-id> --tab-id <tab-id> --lane-id <lane-id> --json
autoflow agent refs attach --ref HOST_001=flow:V1-S1/media-id --dry-run --json
autoflow agent retry V1-S3 V1-S7 --issue "wrong speaker" --project-id <project-id> --tab-id <tab-id> --json
autoflow agent artifacts download-plan --reconciled reconcile.json --run-name <run-id> --json
autoflow agent artifacts download-plan --reconciled reconcile.json --run-name <run-id> --execute --out ./outputs/<run-name> --project-id <project-id> --tab-id <tab-id> --json

Safety Model

• Read-only tools do not submit generation.
• Live submit, retry, and execute-download commands require explicit projectId and tabId targeting.
• Live bridge write commands require active Auto Flow Pro verified through Supabase license refresh. A signed-in free account can use read-only setup and dry-runs, but it cannot drive Agent Mode or execute bridge downloads.
• The extension fails closed if the resolved Flow tab does not match the target.
• Same-target live submits are locked so two agents cannot submit into the same lane at once.
• Download execution goes through the extension session that owns Flow.
• Downloaded images, videos, refs, manifests, QA notes, and retry reports should stay under the run folder named by outputs/<run-name>/.
• Reference images must be attached through the Flow Agent plus button and Add to Prompt; typed filenames alone are not enough for Flow Agent to use them.
• After a live submit or retry, wait for the expected manifest to complete. Do not stop at partial completion such as 10/12 or 11/12; inspect context and retry only missing rows.
• If the user asks for a video length such as 10 seconds, carry that into the run profile and prompt contract before live submit.
• Credit-confirming actions should only run after explicit user approval for the exact model, output count, ratio, and spend. Use autoflow agent confirm-credits for a visible stalled dialog instead of re-running a row.

Troubleshooting

If MCP starts but bridge-backed tools fail:

1. Confirm the Chrome extension is installed and signed in.
2. Confirm Auto Flow Bridge is enabled.
3. Re-run autoflow pair.
4. Run autoflow status --json.
5. Verify the target Flow project is open in the same Chrome profile.
6. Pass explicit projectId, tabId, and laneId for live submit/retry calls.

If npm shows no README, publish a new beta version. Existing npm versions are immutable, so a README cannot be added retroactively to an already-published version.

License

This package is proprietary commercial software for Auto Flow users. It is not open source. The UNLICENSED npm metadata is intentional unless the project owner chooses to publish a separate commercial license file.

Links

• Docs: https://ergophobia.info/autoflow
• Repository: https://github.com/duckflow-tools/auto-flow-nano-banana