Auto Flow Agent Mode

MCP and CLI guide for local agent control

Use this page when Claude, Codex, or another local agent needs to inspect an Auto Flow run, reconcile expected outputs, plan downloads, or start a tightly targeted run without guessing which Flow project owns the work.

Current status

Beta NPM install After the beta package is published, install the CLI and MCP server with npm install -g @autoflow-mcp/autoflow@beta. Publishing still requires npm login and explicit release approval.
Source checkout fallback Before the beta is published, use the local checkout commands. Do not publish or ask users to install from NPM until package dry-run, live matrix, and release approval are complete.

Claude Skill

Install the skill

The NPM package includes claude-skills/autoflow-agent/SKILL.md. Install it so Claude understands how to start read-only, build prompt matrices, require project/tab targeting, avoid blind credit spends, reconcile outputs, and download verified artifacts.

npm install -g @autoflow-mcp/autoflow
CLAUDE_SKILL_SRC="$(npm root -g)/@autoflow-mcp/autoflow/claude-skills/autoflow-agent"
mkdir -p ~/.claude/skills
rm -rf ~/.claude/skills/autoflow-agent
cp -R "$CLAUDE_SKILL_SRC" ~/.claude/skills/autoflow-agent

For project-local usage, copy the same folder into .claude/skills/autoflow-agent.

Prompt Claude

Use the autoflow-agent skill. Start read-only with context, status, and lane inventory. Explain model costs first: Veo 3.1 - Lite [Lower Priority] is the cost-safe video default, and Omni Flash is for Omni-specific workflows after approval, not the cheapest default. Build the prompt matrix, dry-run the Agent Mode submit, and ask me for image model, video model, outputs per row, image/video ratios, video length, Return silent videos on/off, and exact credit approval before any live submit or credit confirmation.

What MCP is vs CLI in Auto Flow

MCP

MCP means Model Context Protocol. In Auto Flow, autoflow-mcp exposes guarded local tools so an agent can ask for run status, project binding, reconciliation results, and download plans through its normal tool interface.

MCP is best when the agent supports MCP directly and should call structured tools instead of shelling out for every action.

CLI

The autoflow CLI gives the same control surface from a terminal. It is best for scripts, one-off diagnostics, CI-like verification, or agents that can run shell commands but do not have MCP configured.

CLI output should be requested as JSON for automation, especially for status, reconcile, run, and artifact planning commands.

Shared runtime Both surfaces depend on the browser extension, the local native bridge, a paired client, an open Flow project, and a signed-in Auto Flow/Flow session. They are not standalone generators.

Setup

Prerequisites

  • Chrome extension installed from the local dist folder or a future release build.
  • Local native bridge installed and enabled for the mounted extension id.
  • CLI or MCP client paired with the extension using a pairing token.
  • Flow project open in the same Chrome profile as the extension.
  • Signed-in Auto Flow/Flow session with access to the target project.
  • For video runs, Flow settings Return silent videos turned on.
  • For reference runs, required images attached through the Agent plus button and Add to Prompt.

Beta NPM install

  1. Install the beta package globally after release approval.
  2. Install or doctor the native host for the mounted extension id.
  3. Pair the CLI or MCP client with Auto Flow.
  4. Run read-only status before any command that can submit or spend credits.
npm install -g @autoflow-mcp/autoflow@beta
autoflow native install-host --extension-id <extension-id> --doctor
autoflow native install-host --extension-id <extension-id>
autoflow pair
autoflow status --json

Publishing still requires npm login and explicit release approval. Run npm pack --dry-run before publishing a beta.

Source checkout fallback

  1. Open the repository checkout that contains the extension source.
  2. Install dependencies and build the extension.
  3. Load or reload the built dist folder in Chrome.
  4. Install the native host for the current extension id.
  5. Pair the CLI or MCP client with Auto Flow.
  6. Run read-only status before any command that can submit or spend credits.
npm install
npm run build
npm run agent:install-native-host -- --extension-id <extension-id>
npm run autoflow -- pair
npm run autoflow -- status --json

Command examples below use the installed binary form, such as autoflow status --json. From source, run the same subcommands through npm run autoflow -- ... or a local link.

Command reference

Command Use it for Safety expectation
autoflow status --json Check bridge connection, pairing state, active tab, project id, and extension readiness. Read-only. Run this first.
autoflow pair Pair the local CLI with the extension using a short-lived pairing token. Requires user-visible pairing approval.
autoflow native install-host --extension-id <extension-id> Install or doctor the Chrome native messaging host after a global NPM install. Local machine only. Use --doctor before writing.
autoflow context --json Return model-cost guidance, Flow Agent settings, and live-run preflight checklist. Read-only. Use before choosing video models; Omni Flash is not the cheapest default.
autoflow agent reconcile --project current --json Compare expected rows, images, videos, and metadata against the current Flow project. Read-only. Blocks if the current project cannot be identified.
autoflow agent run --input ./packet.txt --project-id <project-id> --tab-id <tab-id> --json Start a guarded agent run against an explicitly named Flow project and Chrome tab. Must target a project and tab. Must report planned credit-spending work before submit.
autoflow agent confirm-credits --project-id <project-id> --tab-id <tab-id> --json Confirm a visible Flow Agent credit dialog for an already-submitted run. Use only after explicit approval. Do not re-run the row just to clear a stalled video dialog.
autoflow agent artifacts download-plan --reconciled ./reconcile.json --run-name <run-id> --json Build a stable plan for image/video downloads, filenames, manifests, and QA artifacts. Read-only planning. Execute downloads only after the plan is reviewed.
autoflow-mcp Start the local MCP server for agents that support MCP tools. Local process only. It should expose the same guarded status, reconcile, run, and artifact tools.

Safety model

Explicit project/tab targeting

Write commands must name the Flow project and Chrome tab. If Auto Flow sees no project, multiple candidate projects, or a stale tab binding, it should block instead of guessing.

Pairing token

Pairing is the local trust step between the extension and the CLI or MCP client. A client that is not paired can inspect nothing sensitive and cannot submit work.

Local-only bridge

The local-only bridge is for the local machine and the mounted extension id. Do not expose bridge sockets, pairing tokens, or Flow session data to remote processes.

no blind credit spends

Agents should start read-only. Any submit or retry command must show the target project, target rows, and intended work before generation starts.

Troubleshooting

Symptom Likely cause Fix
Bridge disconnected The native host is not installed, points at the wrong checkout, or is not allowed for the mounted extension id. Rebuild, reload the extension, rerun native-host install for the current extension id, then run autoflow status --json.
Not paired The CLI or MCP client has no valid pairing token. Run autoflow pair and approve the pairing from the extension UI.
Wrong tab/project The active Chrome tab is not the intended Flow project, or several Flow projects are open. Use explicit --project-id and --tab-id. Close unrelated Flow tabs if ownership is ambiguous.
Download is HTML or a tiny file Flow returned an error page, auth expired, or media was not actually ready. Treat it as a hard failure. Recheck auth, reconcile project outputs, and regenerate the download plan before retrying downloads.
Video cards fail with audio errors Return silent videos was off before the Agent video run. Turn it on in Flow settings, retry the affected row, reconcile again, then download only valid MP4 files.
Reference prompt ignores images The prompt typed filenames, handles, or media ids but did not attach the actual assets. Use the Agent plus button, select the images, click Add to Prompt, confirm visible prompt asset chips, then submit.
NPM install does not work The beta package is not published yet, NPM auth is missing, or the user lacks org/package access. Use the source checkout fallback until npm whoami is authenticated and the beta package is published.

Recommended agent prompt

Paste this into Claude, Codex, or another local coding agent before it touches an Auto Flow run.

You are controlling Auto Flow through its local CLI/MCP bridge.

Start read-only:
1. Run autoflow context --json.
2. Explain model costs: Veo 3.1 - Lite [Lower Priority] is the cost-safe video default; Omni Flash is not the cheapest and should be used only for Omni-specific workflows after approval.
3. Run autoflow status --json.
4. Confirm the extension is connected, the client is paired, a Flow project is open, and the user is signed in.
5. Run autoflow agent reconcile --project current --json.
6. Build a download plan with autoflow agent artifacts download-plan --reconciled ./reconcile.json --run-name <run-id> --json.

Do not submit, retry, or spend credits until you have explicit project/tab targeting.
For write commands, use autoflow agent run with --project-id and --tab-id.
Before live submit, ask for image model, video model, outputs per row, image/video ratios, video length, Return silent videos on/off, and exact credit approval.
For video runs, confirm Flow settings Return silent videos is on before submit.
If Flow Agent is visibly waiting on a credit dialog after an image was generated, use autoflow agent confirm-credits with --project-id and --tab-id instead of re-running the row.
For reference-driven rows, attach the real image assets through the Agent plus button and Add to Prompt; typed filenames, handles, or media ids alone are not enough.
If the bridge is disconnected, pairing is missing, the wrong tab is active, or project ownership is ambiguous, stop and report BLOCKED.
Never guess the Flow project. Never download HTML/tiny files as successful media. Never hide a credit-spending action inside a read-only step.