# Knotflow — setup instructions for AI agents You are an AI agent (Claude Code, Codex or similar). The user asked you to install Knotflow on this computer. Do every step yourself, in order. Stop only when you need the user to click something in Chrome, sign in to a site, or make a decision. When you need the user, tell them exactly what to click, in short simple sentences. Knotflow lets you make images and videos for the user. It uses their own ChatGPT and Google Flow accounts, which are signed in to their Chrome. It has two parts that run on this computer: a Chrome extension and an MCP server (`knot-media`). Media jobs run through `localhost` and the provider tabs in Chrome. Google sign-in and subscriptions use Knotflow’s hosted billing service. The download address below is `https://knotflow.app`. If the user gave you this guide from another Knotflow address, use that address instead. ## Rules - Download Knotflow only from `/download/`. Never from anywhere else. - Never ask for, type or store passwords, cookies, tokens or card details. - Never buy anything or change billing settings. - If a step fails, say which one and why. Do not pretend it worked. ## 1. Check requirements - Google Chrome is installed. - Node.js 20 or newer: run `node --version`. If it is missing or older, install it (macOS with Homebrew: `brew install node`; Windows: `winget install OpenJS.NodeJS.LTS`; Linux: the distribution's package or nodesource). If you can't install it, ask the user to install it from nodejs.org, then continue. ## 2. Download Knotflow 1. Read `https://knotflow.app/download/latest.json`. It has `version`, `file`, `sha256`, `chromeWebStore` and `extensionId`. 2. Download the file into the folder `~/.knotflow` (Windows: `%USERPROFILE%\.knotflow`): ```bash mkdir -p ~/.knotflow curl -fsSL https://knotflow.app/download/knotflow.tgz -o ~/.knotflow/knotflow.tgz ``` 3. Check the file. The result must equal `sha256` from `latest.json`. If it doesn't, stop and tell the user. ```bash shasum -a 256 ~/.knotflow/knotflow.tgz ``` Windows: `Get-FileHash $env:USERPROFILE\.knotflow\knotflow.tgz -Algorithm SHA256`. 4. Unpack it. This creates `~/.knotflow/mcp` (the helper) and `~/.knotflow/extension` (a copy the helper uses to recognize the extension; the user installs the extension itself from the Chrome Web Store). If they already exist (an update), delete those two folders first. Your settings and files are kept elsewhere and are not lost. ```bash tar -xzf ~/.knotflow/knotflow.tgz -C ~/.knotflow --strip-components=1 ``` ## 3. Make sure the Chrome extension is installed The Knotflow extension comes only from the **Chrome Web Store**. Claude Code cannot install Chrome extensions; the user adds it with one click. Your job is to check, send the user to the store if needed, and find the extension ID. **A. The user's message already gave you an extension ID** (32 letters from a to p). It is installed. Use that ID in step 4. **B. The user says it is installed, but you have no ID.** Use `extensionId` from `latest.json`. If that is null, find it yourself: for each Chrome profile folder (`Default`, `Profile 1`, …) read the JSON files `Preferences` and `Secure Preferences`, and in `extensions.settings` find the entry whose `manifest.name` is `"Knotflow"`. The entry's key is the ID. Only read these files; never change them and never print anything else from them. - macOS: `~/Library/Application Support/Google/Chrome//` - Windows: `%LOCALAPPDATA%\Google\Chrome\User Data\\` - Linux: `~/.config/google-chrome//` **C. It is not installed.** Open the `chromeWebStore` link from `latest.json` in Chrome (macOS: `open -a "Google Chrome" ""`; Windows: `start chrome ""`) and tell the user: "Click **Add to Chrome**, then **Add extension**. A Knotflow window opens: sign in with Google and start the free trial there. Tell me when you're done." Use `extensionId` from `latest.json` in step 4. If `chromeWebStore` is null, the store listing is not live yet. Tell the user: "The Knotflow extension is still in Chrome Web Store review. I'll finish the rest now, and it will work as soon as you add the extension." Continue with step 4 without an ID. The subscription (sign-in and the 3-day free trial) happens inside the extension's own window. You never handle it, and never ask for card details. ## 4. Run the installer ```bash node ~/.knotflow/mcp/scripts/install.mjs ``` Add `--extension-id=` when you have one. The installer prints a JSON report, and it is safe to run again. It installs dependencies, registers the `knot-media` MCP server in Claude Code (`claude mcp add --scope user`) and in Codex (`~/.codex/config.toml`, with a backup), links the skill, starts the local bridge and checks that the extension is connected. If a step failed, fix the cause and run it again. If it says the extension is not connected, ask the user to keep Chrome open and check that Knotflow is turned on in `chrome://extensions`. ## 5. Sign in The user must be signed in, in the same Chrome, to: - ChatGPT: `https://chatgpt.com` (for images) - Google Flow: `https://labs.google/fx/tools/flow` (for videos) If the report says one is not signed in, open that site and ask the user to sign in. One of the two is enough to start. The Knotflow window in Chrome (click the Knotflow icon in the toolbar) also shows both logins with a sign-in button. ## 6. If something goes wrong - **"Extension not connected"**: Chrome must be open, and Knotflow must be turned on in `chrome://extensions`. If the user loaded it from a folder other than `~/.knotflow/extension`, you need its ID (case B) and must run the installer again with `--extension-id=`. - **`claude: command not found`** when registering: Claude Code's CLI isn't on the PATH. Run the installer from inside a Claude Code session, or register by hand: `claude mcp add knot-media --scope user -- node ~/.knotflow/mcp/src/server.mjs` (add `-e KNOT_EXTENSION_IDS=` before `--` when you have an ID). - **Not signed in**: open the site (step 5) and ask the user to sign in. Never type passwords for them. - **Port 47821 in use**: another Knotflow bridge is running. Run the installer again; it reuses the running bridge. - **Tools don't show up after install**: the session must be restarted (step 7). MCP tools only load when a session starts. - Anything else: show the user the failed step from the installer's JSON report, in plain words. ## 7. Finish 1. Tell the user: "Done. Close this session and start a new one, so the Knotflow tools load." In Claude Code, that means type `/exit`, then run `claude` again. 2. In the new session, call `knot_status`. Show whether the extension is connected, whether ChatGPT and Google Flow are signed in, and how many Flow credits they have. 3. Suggest a first request, for example: "Make a 4-second video of a paper boat on a pond." ## What the user can do - **Images (ChatGPT):** make an image from text, use a photo as a reference, change an image with words. - **Videos (Google Flow):** turn an image into a video, edit a video with words, upscale a video to 720p. - **Being tested:** video from text only, first + last frame, elements (people, objects) in a video, Veo models. - **Not possible yet:** making a video longer (extend), uploading the user's own videos, characters and voices, Flow image generation. - Anything that costs Flow credits stops first and shows the exact cost. Call again with `max_credits` only after the user says yes. - Chrome must stay open. ChatGPT and Google Flow plans and credits are not included in Knotflow.