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

1. Open chrome://extensions.
2. Enable Developer mode.
3. Click Load unpacked.
4. Select the repository's flow-extension directory.
5. Open Google Flow, sign in, and keep the tab open.
6. 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
has_flow_key:        True

CLI

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

Images

flow image "a cinematic neon city" --model gem_pix_2 --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 GENERATED_IMAGE_MEDIA_ID
flow video "use these existing references" --ref GENERATED_ID UPLOADED_ID

Upload and edit

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

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 FLOW_OUTPUT_DIR="$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/claude_desktop_config.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

• get_flow_status — backend, extension, and Flow-key readiness
• get_flow_credits — credits across connected browser sessions
• list_flow_models — available models and the active default
• get_flow_history — generated and uploaded media history
• generate_flow_image — text/reference image generation
• generate_flow_video — text, start-image, and reference video generation
• upload_flow_media — upload a local path, URL, or base64 media payload
• download_media_from_url — download media and optionally upload it to Flow
• edit_flow_video — 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 SERVER_API_KEY is configured, send it as:

Authorization: Bearer YOUR_SERVER_API_KEY

Configuration

Environment variables take precedence over values in .env.

Variable	Default	Purpose
OPENAI_API_HOST	127.0.0.1	Backend bind/client host
OPENAI_API_PORT	8001	Backend HTTP port
FLOW_OUTPUT_DIR	beside flow	Generated files and history.json
FLOW_HISTORY_FILE	<output>/history.json	Optional history path override
DEFAULT_PROJECT	bundled default	Google Flow project ID
IMAGE_MODEL	gem_pix_2	Default image model
PUBLIC_BASE_URL	http://localhost:8001	URLs returned for local media
SERVER_API_KEY	unset	Optional backend bearer authentication
FLOW_READY_TIMEOUT	30	CLI readiness wait in seconds
FLOW_VIDEO_POLL_TIMEOUT	900	CLI video-job polling timeout
MAX_CONCURRENT_REQUESTS	5	Maximum concurrent Flow requests
REQUEST_MIN_INTERVAL	3	Minimum seconds between request starts

Image model aliases:

• harbor_seal / lite
• narwhal / standard
• gem_pix_2 / 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 has_flow_key=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.