Flow Agent

CLI, OpenAI-compatible API, Chrome extension bridge, and MCP server for Google Flow image and video generation.

Flow Agent uses your existing, logged-in Google Flow browser session. The CLI, HTTP API, and MCP clients all share one backend and one extension bridge.

Features

• Text-to-image and reference-image generation
• Text-to-video, image-to-video, first/last-frame, reference-to-video, and video editing
• 4, 6, 8, and 10-second video generation
• Reusable generated and uploaded media IDs, including after backend restarts
• Exact --output paths with real PNG, JPEG, and WebP conversion
• Signature-based MIME and extension detection
• Persistent idempotency for safe paid-generation retries
• OpenAI-compatible HTTP endpoints and pollable video jobs
• MCP v2 tools for generation, upload, download, history, status, and credits
• One shared backend on port 8001; an already healthy backend is reused

Requirements

• Python 3.10 or newer
• uv for source installation
• Chrome or another Chromium browser
• Google Flow access and an active signed-in session

Quick start

Clone the repository and enter the Python application directory:

git clone https://github.com/kodelyx/flow-agent.git
cd flow-agent/flow-agent

macOS or Linux setup

The setup script installs the flow command and configures the backend to start on login:

./scripts/setup.sh

To install only the CLI without creating a background service:

uv tool install --force .

Windows setup

From PowerShell in flow-agent\flow-agent:

powershell -ExecutionPolicy Bypass -File .\scripts\setup-windows.ps1

Chrome extension

• Open chrome://extensions.
• Enable Developer mode.
• Click Load unpacked.
• Select the repository's flow-extension directory.
• Open Google Flow, sign in, and keep the tab open.
• Run flow status and confirm both readiness fields are True.

Extension-specific details are in flow-extension/README.md.

Backend and readiness

Start the backend manually when it is not managed by the setup service:

flow

Running flow again while a healthy Flow backend is already listening on port 8001 reuses that backend instead of starting a second bridge.

Check readiness with:

flow status

Generation begins only after both of these values are true:

extension_connected: True
hasflowkey:        True

CLI

Run flow <command> --help for every available option.

Images

flow image "a cinematic neon city" --model gempix2 --aspect landscape
flow image "restyle this character" --ref character.png --count 2
flow image "a product photo" --output /absolute/path/result.png
flow image "a product photo" --output /absolute/path/result.jpg
flow image "a product photo" --output /absolute/path/result.webp

For .png, .jpg, .jpeg, and .webp outputs, the suffix is a format contract. If Google Flow returns another image format, Flow Agent decodes and atomically converts it while preserving dimensions. It never writes JPEG bytes under a .png filename.

Videos

flow video "a dragon flying over mountains" --aspect landscape --duration 8
flow video "the character starts walking" --start character.png
flow video "transition between scenes" --start first.png --end last.png
flow video "keep this character consistent" --ref character.png

--start, --end, and --ref accept either local image paths or exact media IDs stored in history.json:

flow video "animate this generated image" --start GENERATEDIMAGEMEDIA_ID
flow video "use these existing references" --ref GENERATEDID UPLOADEDID

Upload and edit

flow upload character.png
flow upload clips --batch
flow edit "transform into a dark anime style" --media-id VIDEOMEDIAID

Uploads return a reusable media_id. Generated media IDs are printed after the saved output path.

Safe retries

Use one idempotency key when retrying the same paid request:

flow image "a lighthouse at sunset" --idempotency-key lighthouse-v1
flow video "waves moving slowly" --idempotency-key waves-v1

The same key and payload reuse the original result or job. Reusing a key with a different payload returns a conflict instead of starting another generation.

Output files and media history

Without --output, files are saved in an output directory beside the installed flow executable. Override this location before starting the backend:

export FLOWOUTPUTDIR="$HOME/FlowOutput"

An explicit path is resolved to an absolute path and used exactly. Multiple results keep the first requested path and add 2, 3, and so on for later files. The CLI prints the final absolute path and detected format.

history.json in the configured output directory is the only persistent media registry. It stores filename, media ID, media type, MIME type, prompt, timestamp, project ID, and local/served location metadata when available.

• Generated and uploaded IDs remain reusable after backend restarts.
• Exact media IDs are matched before filename lookup.
• A stale remote ID is re-uploaded only after Google Flow confirms it is unavailable.
• The refreshed ID is written back atomically to the same history record.
• An older media-id.js or media-ids.json registry is migrated once and removed.
• Missing history and local assets return a clear Media not found error.

Flow Agent does not create a second media registry.

MCP setup

Copy this portable configuration into your MCP client. It intentionally uses the flow command from PATH instead of a machine-specific executable path:

{
  "mcpServers": {
    "flow": {
      "command": "flow",
      "args": ["mcp"]
    }
  }
}

The backend must be running before MCP tools can generate media. flow mcp is the stdio MCP transport; it does not create a second backend bridge.

If a desktop client cannot find flow, locate the installation with:

command -v flow

Use that result in your local client configuration or add its directory to the client's PATH. Do not commit machine-specific executable paths to the repository.

Claude Desktop

Create or edit ~/Library/Application Support/Claude/claudedesktopconfig.json and add the flow entry shown above inside mcpServers. Restart Claude Desktop after saving.

Cursor

Open Settings → MCP → Add new MCP server, or add the same configuration to ~/.cursor/mcp.json.

Cline

Open Cline → MCP Servers → Configure MCP Servers and add the same flow server configuration.

Windsurf

Add the same configuration to ~/.codeium/windsurf/mcp_config.json.

Google Antigravity

Open Antigravity's MCP settings and add a stdio server with command flow and arguments mcp.

Claude Code

claude mcp add flow -- flow mcp

SSE/HTTP-only MCP clients

Use the backend's SSE endpoint:

http://127.0.0.1:8001/sse

JSON-RPC messages are sent to http://127.0.0.1:8001/messages.

MCP tools

• getflowstatus — backend, extension, and Flow-key readiness
• getflowcredits — credits across connected browser sessions
• listflowmodels — available models and the active default
• getflowhistory — generated and uploaded media history
• generateflowimage — text/reference image generation
• generateflowvideo — text, start-image, and reference video generation
• uploadflowmedia — upload a local path, URL, or base64 media payload
• downloadmediafrom_url — download media and optionally upload it to Flow
• editflowvideo — edit a video by media ID or local video path

HTTP API

Default base URL: http://127.0.0.1:8001

| Endpoint | Purpose | |---|---| | GET /health | Backend, extension, and Flow-key health | | GET /v1/models | Available image/video models | | GET /v1/credits | Connected-account credits | | GET /v1/history | Persistent generated/uploaded media history | | POST /v1/images/generations | Generate images | | POST /v1/videos/generations | Submit video generation | | GET /v1/videos/generations/{job_id} | Poll a video job | | POST /v1/upload | Upload an image or video reference | | GET /download/{filename} | Download a managed media file | | GET /sse | MCP over SSE | | POST /messages | MCP over SSE JSON-RPC messages |

Send an Idempotency-Key header when an HTTP generation request may be retried. Video submission returns a structured result containing a job_id, status, creation timestamp, and media data. Poll the job endpoint until it is succeeded or failed.

If SERVERAPIKEY is configured, send it as:

Authorization: Bearer YOURSERVERAPI_KEY

Configuration

Environment variables take precedence over values in .env.

| Variable | Default | Purpose | |---|---|---| | OPENAIAPIHOST | 127.0.0.1 | Backend bind/client host | | OPENAIAPIPORT | 8001 | Backend HTTP port | | FLOWOUTPUTDIR | beside flow | Generated files and history.json | | FLOWHISTORYFILE | <output>/history.json | Optional history path override | | DEFAULT_PROJECT | bundled default | Google Flow project ID | | IMAGEMODEL | gempix_2 | Default image model | | PUBLICBASEURL | http://localhost:8001 | URLs returned for local media | | SERVERAPIKEY | unset | Optional backend bearer authentication | | FLOWREADYTIMEOUT | 30 | CLI readiness wait in seconds | | FLOWVIDEOPOLL_TIMEOUT | 900 | CLI video-job polling timeout | | MAXCONCURRENTREQUESTS | 5 | Maximum concurrent Flow requests | | REQUESTMININTERVAL | 3 | Minimum seconds between request starts |

Image model aliases:

• harbor_seal / lite
• narwhal / standard
• gempix2 / pro

Exit codes

The unified CLI uses stable non-zero codes for actionable failures:

| Code | Meaning | |---|---| | 2 | Invalid CLI arguments | | 3 | Backend unavailable | | 4 | Extension or Flow key not ready | | 5 | Backend/API generation error | | 6 | Media conversion, download, or output-writing error |

Development

Install dependencies and run the regression suite:

cd flow-agent/flow-agent
uv sync --extra test
uv run pytest -q
uvx ruff check . --select F,E9

Build a standalone executable with the same Python environment used by the project:

uv run --with pyinstaller python -m PyInstaller --clean --noconfirm flow.spec

The generated binary is written to dist/flow (dist/flow.exe on Windows). build/ and dist/ are ignored build artifacts and should not be committed.

Troubleshooting

• flow is not found — reinstall from flow-agent/flow-agent with

uv tool install --force ., then ensure the directory printed by command -v flow is available to your shell or MCP client.

• Backend reports extension_connected=False — open Google Flow in Chrome,

enable the extension, and refresh the Flow tab.

• Backend reports hasflowkey=False — keep the signed-in Flow tab open

and trigger a refresh so the extension can capture the current key.

• Port 8001 is already in use — flow reuses a healthy Flow backend. Stop

or reconfigure an unrelated service occupying that port.

• Media not found — regenerate or upload the asset if neither its history

record nor local managed file still exists.

• A retry might have reached Flow — repeat it with the same idempotency key;

do not create a new key for the same paid request.

• MCP tools appear but fail — verify flow status, then restart the MCP

client after correcting its command/PATH configuration.

Project layout

flow-agent/
├── README.md             # All installation, CLI, API, and MCP documentation
├── flow-agent/           # Python CLI, backend, and MCP implementation
│   ├── main.py           # Unified flow entry point
│   ├── flow.spec         # Single-executable PyInstaller build
│   ├── flow_server/      # API, MCP/SSE, media registry, and server state
│   ├── flow_engine/      # Flow bridge, generators, polling, and uploads
│   ├── scripts/          # Setup and uninstall scripts
│   └── tests/            # Regression and acceptance tests
├── flow-extension/       # Chrome extension bridge
└── .github/workflows/    # Cross-platform test/build workflow

License

Use Google Flow and generated media according to Google's applicable terms.