FlowPilot

FlowPilot is a local service that drives Google Flow (AI image and video generation) through your own logged-in Chrome, using your own Flow subscription credits. It is usable from a CLI (flowpilot), a local HTTP API (127.0.0.1 only, protected by a token) and an MCP server for AI assistants (Claude Code, Codex, Cursor and others).

Status: beta

Requirements

• Windows 10/11, or macOS/Linux (first-class Windows support)

• Node.js 22.12 or newer

• Google Chrome

• A Google account with access to Google Flow

• Google AI subscription credits for video generation (image generation with Nano Banana models costs 0 credits)

Related MCP server: google-flow-mcp

Install

npm install -g Rocco3D/FlowPilot

Or install from source:

git clone https://github.com/Rocco3D/FlowPilot.git
cd FlowPilot
npm install
npm run build
npm link

After installation, flowpilot is available in your terminal.

First sign-in

Sign in with your Google account:

flowpilot login

This opens a plain Chrome window where you can sign in with Google. If Flow shows terms to accept, accept them. Close the window when done, then verify the setup:

flowpilot doctor

This checks that Chrome is running, the API connection works, and you're signed in.

Generate

Image generation

flowpilot image --prompt "A serene landscape at sunset" --model "Nano Banana 2" --ratio 1:1

Video generation

flowpilot video --prompt "A cat walking through a sunny garden" --model "Veo 3.1 - Lite" --ratio 16:9

Read the prompt from a file instead of the command line:

flowpilot video --prompt-file prompt.md --model "Veo 3.1 - Lite"

Omni (universal generation)

flowpilot video --prompt "A flowing waterfall" --model "Omni 1.1 Flash" --resolution 720p --duration 4

Advanced options

• --ratio 16:9: Aspect ratio (image and video; default is model-dependent)

• --resolution 720p: Omni resolution, when Flow offers a choice (for example 360p or 720p)

• --duration 4: Video duration in seconds

• --outputs 2: Generate multiple outputs (1–4)

• --start-frame path.jpg: Starting frame for video continuation

• --ingredient path.jpg: Reference image for style

• --character "Character Name": Reference character

• --no-wait: Submit the job and exit immediately (by default, the CLI waits for the job to finish)

• --json: Output JSON instead of human-readable text

• --out ~/Downloads: Save results to a custom folder (default: configured output folder)

• --upscale 4k: Upscale the result (1080p or 4k)

• --max-credits 50: Per-job credit limit (overridden by --confirm)

Models and credits

Models and their credit costs as of October 2026:

Video models:

• Omni 1.1 Flash: 720p, durations 4/6/8/10 seconds, 7–15 credits (Flow sometimes also offers 360p, 4–7 credits; with a start/end frame only 720p and 4/6/8 seconds)

• Veo 3.1 - Lite: 720p, 8 seconds, 10 credits

• Veo 3.1 - Fast: 720p, 8 seconds, 20 credits

• Veo 3.1 - Quality: 720p, 8 seconds, 100 credits

All video models support audio.

Image models:

• Nano Banana Pro: 0 credits on Google AI Pro

• Nano Banana 2: 0 credits on Google AI Pro

• Nano Banana 2 Lite: 0 credits on Google AI Pro

List available models

flowpilot models

This reads the live list from Flow.

Credit guard

FlowPilot protects your account with two limits:

• Per-job limit (default 20 credits): Jobs that exceed this are rejected unless you pass --confirm

• Monthly limit (default 1000 credits): If you're approaching the monthly limit, jobs are rejected unless you pass --confirm

Check your spending:

flowpilot credits

Jobs and the service

One Flow session runs at a time. Jobs run one at a time in a queue.

The CLI automatically starts the background service if it is not running. You can also manage it manually:

flowpilot service start
flowpilot service stop
flowpilot service status

Manage jobs

List all jobs (newest first):

flowpilot jobs

Get details of a specific job:

flowpilot job <id>

Cancel a queued job:

flowpilot cancel <id>

Cancelling a job that is already running or downloading has no effect.

Service shutdown

Stop the service and close the browser window:

flowpilot service stop

The service also stops automatically after being idle for a configured number of minutes (default 30; set to 0 to disable).

Configuration

All settings can be read and changed with flowpilot config:

flowpilot config get                    # Show all settings
flowpilot config get outputDir          # Show one setting
flowpilot config set outputDir ~/Videos # Change a setting

Changes to idleMinutes and showBrowser take effect the next time the service starts (after flowpilot stop or an idle shutdown).

Languages

FlowPilot is available in English and Italian.

The interface language is chosen from:

1. flowpilot config set locale en or locale it

2. Environment variable: FLOWPILOT_LANG=en or FLOWPILOT_LANG=it

3. System language (if Italian, uses Italian; otherwise English)

Use from other apps

Local HTTP API

The local HTTP API on http://127.0.0.1:47820 lets you integrate FlowPilot with other tools. Full reference: docs/api.md

MCP server for AI assistants

Run FlowPilot as an MCP server for Claude Code, Codex, Cursor and other AI assistants:

Claude Code:

claude mcp add flowpilot -- flowpilot mcp

Full reference: docs/mcp.md

Self-test and troubleshooting

Test the setup without spending credits:

flowpilot selftest

This checks that Flow's UI is responding and that selectors are correct.

If Flow's UI changes

All DOM selectors for Flow live in one file: src/flow/selectors.ts. If Flow changes its layout, FlowPilot will fail at a specific step. The selectors can be updated without changing any other code.

Logs

Logs are written to the data folder:

• Windows: %LOCALAPPDATA%\FlowPilot\logs

• macOS: ~/Library/Application Support/FlowPilot/logs

• Linux: ~/.local/share/flowpilot/logs

Logs are organized by day. A JSON summary is written next to every job result.

Uploads and Google's rights confirmation

When a job uses reference files (start/end frame, ingredients), Flow asks you to confirm that you have the rights to each uploaded file and that you comply with Google's Prohibited Use Policy. FlowPilot clicks "I agree" automatically by default, so that queued jobs can run unattended. By using reference files you make that declaration yourself.

To turn this off, run flowpilot config set acceptUploadRights false. Jobs with uploads then stop with an explanation.

Disclaimer

FlowPilot is unofficial. It is not affiliated with or endorsed by Google. It automates your own Google Flow session in your own browser, and you are responsible for complying with Google's Terms of Service.

License

The code and documentation are released under the MIT License, see LICENSE.

Logos and names are excluded: the FlowPilot logo, the Rocco logo and the name Rocco™ (files in assets/brand/) are not covered by the MIT License. All rights reserved; they may not be reused without permission. See assets/brand/NOTICE.md.

Credits

FlowPilot started from and was inspired by gflow-cli by swissmarley (MIT License), which showed how to drive Google Flow through a real, signed-in Chrome session. Parts of the browser session and Flow automation code are derived from it; see THIRD_PARTY_NOTICES.md.