` to Flutter code in
+> `./generated_app`.
+
+Code export uses the standard FlutterFlow CLI export workflow rather than the
+AI project-editing workflow. See [Exporting Projects](./exporting-projects.md)
+for export options, branch selection, and `.flutterflowignore` behavior.
+
+## What the plugin checks before applying changes
+
+For project edits, the plugin guides Codex through these safety checks:
+
+- Work inside an initialized workspace containing
+ `.flutterflow/config.yaml`.
+- Read the workspace's version-matched `AGENTS.md` before authoring changes.
+- Confirm the active FlutterFlow branch and its project ID.
+- Inspect the current project and use its typed SDK rather than guessing names.
+- Run `flutterflow ai test` before applying changes.
+- Apply changes with an explicit commit message.
+- Inspect history, trace information, and project context after the operation.
+
+Validation failures do not push a change. Failures later in the create, network,
+conflict, push, or post-push phases may have remote effects, so Codex inspects
+the result before retrying an operation.
+
+## FlutterFlow MCP in Codex
+
+FlutterFlow MCP is project-scoped. When the CLI initializes a workspace, it can
+write Codex configuration to `.codex/config.toml` for that workspace's vendored
+FlutterFlow MCP server.
+
+Open a new Codex task from the initialized workspace after this configuration is
+written so the tools load. If MCP tools are unavailable, the plugin can continue
+through the FlutterFlow CLI instead of blocking the workflow.
+
+## Update the plugin
+
+### Update in Codex CLI
+
+Refresh the FlutterFlow marketplace and reinstall the terminal plugin from the
+updated snapshot:
+
+```bash
+codex plugin marketplace upgrade flutterflow
+codex plugin add flutterflow@flutterflow
+```
+
+Exit and relaunch Codex CLI, then start a new task. Existing CLI sessions and
+tasks do not reload an updated plugin bundle.
+
+### Update in the ChatGPT desktop app
+
+Open **Plugins** in the ChatGPT desktop app and manage the installed FlutterFlow
+plugin from there. After installing an updated version, start a new task;
+already-open tasks do not reload plugin updates.
+
+Update the FlutterFlow CLI separately:
+
+```bash
+dart pub global activate flutterflow_cli
+```
+
+## Troubleshooting
+
+
+The plugin is not available in Codex CLI
+
+Enter `/plugins` and look for `flutterflow@flutterflow`. Confirm that it is
+installed and enabled. If you installed or updated it while Codex CLI was
+running, exit and relaunch Codex, then start a new task.
+
+
+
+
+The plugin is not available in the ChatGPT desktop app
+
+Open **Plugins** from the main Codex sidebar, not from Settings. Open the
+**Create** menu and select **Add marketplace**, then add the
+[FlutterFlow Codex GitHub marketplace](https://github.com/FlutterFlow/flutterflow-codex):
+
+```text
+https://github.com/FlutterFlow/flutterflow-codex
+```
+
+Open the FlutterFlow plugin details and select the plus button to install it.
+Then start a new task so the FlutterFlow skill loads.
+
+
+
+
+The flutterflow command is not found
+
+Install or update the CLI:
+
+```bash
+dart pub global activate flutterflow_cli
+```
+
+Restart your terminal or Codex if the Dart global executable directory was
+added to `PATH` during installation.
+
+
+
+
+Authentication is missing or rejected
+
+Copy a current token from your
+[FlutterFlow account](https://app.flutterflow.io/account), return to Codex, and
+type `copied` when the plugin asks. Do not paste the token into the chat.
+
+If FlutterFlow rejects a saved credential, generate a replacement token and
+repeat the secure clipboard hand-off.
+
+
+
+
+Codex cannot find the FlutterFlow workspace
+
+Run the task from the initialized workspace directory. Its root contains:
+
+```text
+.flutterflow/config.yaml
+```
+
+Do not initialize a new workspace inside a populated, unrelated directory. If a
+workspace already exists for the project, open that folder instead of creating
+another one.
+
+
+
+
+MCP tools do not appear
+
+Confirm that the workspace contains `.codex/config.toml`, then start a new Codex
+task from that workspace. Codex loads project-scoped MCP configuration at the
+start of a task.
+
+
+
+
+The visual builder changed after Codex inspected the project
+
+Ask Codex to refresh the project context before applying another edit:
+
+> Refresh the FlutterFlow project context, then re-check the planned change.
+
+FlutterFlow uses optimistic concurrency to prevent Codex from silently
+overwriting a newer visual-builder or teammate edit. See
+[Concurrent Edits with Builder](./flutterflow-mcp.md#concurrent-edits-with-builder)
+for details.
+
+
+
+## Support
+
+- Review the
+ [FlutterFlow Codex plugin source and release notes](https://github.com/FlutterFlow/flutterflow-codex).
+- Report plugin bugs through
+ [FlutterFlow Codex GitHub issues](https://github.com/FlutterFlow/flutterflow-codex/issues).
+- Run `flutterflow ai docs [topic]` inside an initialized workspace for
+ version-matched FlutterFlow AI reference material.
diff --git a/docs/ff-concepts/advanced/flutterflow-cli/flutterflow-mcp.md b/docs/ff-concepts/advanced/flutterflow-cli/flutterflow-mcp.md
index b4175002..81def5fa 100644
--- a/docs/ff-concepts/advanced/flutterflow-cli/flutterflow-mcp.md
+++ b/docs/ff-concepts/advanced/flutterflow-cli/flutterflow-mcp.md
@@ -9,10 +9,14 @@ keywords: [CLI, Agentic AI, Projects, Local Management, MCP]
# Build with AI Agents
-The [FlutterFlow CLI](https://pub.dev/packages/flutterflow_cli) lets you create and edit FlutterFlow apps from the terminal using your own AI coding agent — Claude Code, Gemini CLI, Codex, or any MCP-compatible client. You describe what you want in plain English, the agent plans and applies the changes, and the result lands as a real FlutterFlow project you can open in the visual builder.
+The [FlutterFlow CLI](https://pub.dev/packages/flutterflow_cli) lets you create and edit FlutterFlow apps from the terminal using your own AI coding agent, such as Claude Code, Gemini CLI, Codex, or any MCP-compatible client. You describe what you want in plain English, the agent plans and applies the changes, and the result lands as a real FlutterFlow project you can open in the visual builder.
A FlutterFlow project is the source of truth. The CLI is how you create or edit it from your local workspace.
+If you use Codex, see [Build with Codex](./build-with-codex.md) for the
+FlutterFlow plugin installation, secure authentication flow, and Codex-specific
+troubleshooting.
+
## Architecture
@@ -41,7 +45,7 @@ Before you start, make sure you have:
- **FlutterFlow CLI installed.** See [**Installation**](./overview.md).
- **A FlutterFlow API key.** See [**generating an API token**](../../../accounts-billing/account-management.md#how-do-i-generate-an-api-token).
-- **An MCP-compatible AI agent installed locally** — for example, [**Claude Code**](https://www.claude.com/product/claude-code), [**Gemini CLI**](https://github.com/google-gemini/gemini-cli), or [**Codex**](https://github.com/openai/codex).
+- **An MCP-compatible AI agent installed locally**, such as [**Claude Code**](https://www.claude.com/product/claude-code), [**Gemini CLI**](https://github.com/google-gemini/gemini-cli), or [**Codex**](https://github.com/openai/codex).
- **A FlutterFlow project ID** (only if you're editing an existing project).
:::
@@ -88,7 +92,7 @@ This launches an interactive setup wizard. Walk through the prompts:
```
Ready to create:
Workspace: mindfly
- Project ID: (none — unlinked)
+ Project ID: (none, unlinked)
API key: set (***abcd)
Base URL: https://api.flutterflow.io (built-in for prod)
MCP CLIs: claude, gemini, codex
@@ -98,9 +102,9 @@ This launches an interactive setup wizard. Walk through the prompts:
When the wizard finishes, you'll have a workspace folder ready for your agent. Depending on which CLIs you registered, the folder will contain one or more of:
-- `.mcp.json` — for Claude Code
-- `.gemini/settings.json` — for Gemini CLI
-- `.codex/config.toml` — for Codex
+- `.mcp.json` for Claude Code
+- `.gemini/settings.json` for Gemini CLI
+- `.codex/config.toml` for Codex
Each file points the corresponding agent at the FlutterFlow AI MCP server.
@@ -132,14 +136,17 @@ Each file points the corresponding agent at the FlutterFlow AI MCP server.
## Launch your Agent
-Move into the workspace and start your agent. The example below uses Claude Code; the same pattern applies to any agent you registered in the wizard — `cd` into the workspace and launch the agent's CLI.
+Move into the workspace and start your agent. The example below uses Claude Code; the same pattern applies to any agent you registered in the wizard. `cd` into the workspace and launch the agent's CLI.
+
+Codex users who installed the FlutterFlow plugin should start a new Codex task
+from this workspace. See [Build with Codex](./build-with-codex.md#choose-your-codex-surface).
```bash
cd mindfly
claude
```
-The first time the agent opens the workspace, it detects the new MCP server and asks you to approve it. The exact prompt varies by agent — Claude Code's looks like this:
+The first time the agent opens the workspace, it detects the new MCP server and asks you to approve it. The exact prompt varies by agent. Claude Code's looks like this:
```
New MCP server found in .mcp.json: flutterflow_ai
@@ -190,7 +197,7 @@ With the agent connected, describe the app you want at the prompt:
> create a minimalist meditation app
```
-Phrase it however you like — `a recipe-sharing app with a social feed`, `a habit tracker with streaks`, `a tip calculator for restaurants`. The agent plans the app, generates the changes, pushes them to FlutterFlow through the MCP server, and reports back. Open FlutterFlow in your browser and navigate to the project — the generated app will be reflected in the visual builder. From there you can keep refining visually or send another prompt to the agent.
+Phrase it however you like: `a recipe-sharing app with a social feed`, `a habit tracker with streaks`, `a tip calculator for restaurants`. The agent plans the app, generates the changes, pushes them to FlutterFlow through the MCP server, and reports back. Open FlutterFlow in your browser and navigate to the project. The generated app will be reflected in the visual builder. From there you can keep refining visually or send another prompt to the agent.
Once the app exists, the workspace is bound to it. Follow-up prompts in the same session are treated as edits, not new generations, you'll see the agent acknowledge the switch with something like:
@@ -233,14 +240,14 @@ From that point on, the same rules apply as when [editing an existing project](#
Have your **project ID** ready. Open the project in the FlutterFlow editor. The project ID is the path segment after `/project/` in the URL.
:::
-Editing an existing project follows the same flow as [creating a new one](#setup-workspace) — you run `flutterflow ai init` to scaffold a workspace, then drive changes from your agent. The only difference is one step in the wizard: when it asks for an **existing project ID**, paste yours instead of pressing Enter:
+Editing an existing project follows the same flow as [creating a new one](#setup-workspace). You run `flutterflow ai init` to scaffold a workspace, then drive changes from your agent. The only difference is one step in the wizard: when it asks for an **existing project ID**, paste yours instead of pressing Enter:
```
Existing project ID to edit (press Enter to create a new app)
> mindfly-c9lbgr
```
-The workspace is now bound to that project. `cd` into the workspace folder, [launch your agent](#launch-your-agent), and describe the changes you want — "add a profile screen", "switch the primary color to teal", "wire up the login form to Firebase Auth". The agent reads the current project, plans the change, and pushes it through the MCP server. Open FlutterFlow in your browser to verify.
+The workspace is now bound to that project. `cd` into the workspace folder, [launch your agent](#launch-your-agent), and describe the changes you want, such as "add a profile screen", "switch the primary color to teal", or "wire up the login form to Firebase Auth". The agent reads the current project, plans the change, and pushes it through the MCP server. Open FlutterFlow in your browser to verify.
diff --git a/src/css/custom.css b/src/css/custom.css
index e43be52d..cb0dcb80 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -499,6 +499,41 @@ code {
margin-bottom: 2px !important;
}
+.codex-github-card {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ flex-wrap: wrap;
+ gap: 0.75rem;
+ margin: 1rem 0 1.5rem;
+ padding: 0.75rem 1rem;
+ border: 1px solid var(--ifm-color-emphasis-300);
+ border-radius: 8px;
+ color: var(--ifm-font-color-base);
+ text-decoration: none;
+ transition:
+ background-color 140ms ease,
+ border-color 140ms ease,
+ transform 140ms ease;
+}
+
+.codex-github-card:hover {
+ border-color: var(--ifm-color-primary);
+ background-color: var(--ifm-color-emphasis-100);
+ color: var(--ifm-font-color-base);
+ text-decoration: none;
+ transform: translateY(-1px);
+}
+
+.codex-github-card:focus-visible {
+ outline: 2px solid var(--ifm-color-primary);
+ outline-offset: 2px;
+}
+
+.codex-github-card__action {
+ color: var(--ifm-color-primary);
+ font-weight: 600;
+}
.default})
+
+2. On the Plugins page, open the **Create** menu and select
+ **Add marketplace**.
+
+.default})
+
+3. Enter the
+ [FlutterFlow Codex marketplace GitHub URL](https://github.com/FlutterFlow/flutterflow-codex):
+
+```text
+https://github.com/FlutterFlow/flutterflow-codex
+```
+
+4. Complete the marketplace setup, then open the FlutterFlow plugin's details.
+
+5. Select the plus button on the plugin details page to install it.
+
+6. Start a new Codex task so the FlutterFlow skill loads.
+
+7. Choose the parent folder where Codex should create a
+ new FlutterFlow workspace, or choose an existing FlutterFlow AI workspace if
+ you are continuing work on a project.
+
+8. Describe the FlutterFlow outcome you want in the task composer.
+
+After adding the GitHub marketplace, follow OpenAI's
+[plugin installation flow](https://learn.chatgpt.com/docs/plugins) to open the
+plugin details, select the plus button, and start a new task.
+
+:::note
+
+The plugin does not replace the FlutterFlow CLI. It gives Codex a supported
+workflow for driving the CLI and the workspace-specific FlutterFlow tools.
+
+:::
+
+## Authenticate securely
+
+:::info[API token and API key]
+
+The FlutterFlow account page calls this credential an **API token**. The
+FlutterFlow AI workflow also refers to it as an **API key** and uses the
+`FF_API_KEY` environment variable. Code export and Firebase deployment use the
+`FLUTTERFLOW_API_TOKEN` environment variable.
+
+:::
+
+Authentication works the same way in Codex CLI and the ChatGPT desktop app. You
+do not need to paste your FlutterFlow API token into the Codex task.
+
+When Codex needs authentication, it will ask you to:
+
+1. Open your [FlutterFlow account](https://app.flutterflow.io/account) and copy
+ the API token.
+2. Return to Codex and type only `copied`.
+
+The plugin then runs its secure clipboard hand-off. It reads the clipboard
+once, validates the credential format, stores it in a private configuration
+file with restricted permissions, and clears the live clipboard without
+displaying the credential.
+
+:::warning
+
+Never paste a FlutterFlow API token into the chat. Avoid passing it with the
+`--api-key` command-line option because command arguments can be visible to
+other processes and the CLI persists that value to credential files.
+
+Clipboard-history applications and cross-device clipboard services may retain
+a copy that the plugin cannot clear. Clear those histories separately if you
+use them.
+
+:::
+
+## Create a new FlutterFlow app
+
+In Codex CLI or the ChatGPT desktop app, start the task from the parent folder
+where you want the local FlutterFlow workspace, then describe the app you want.
+For example:
+
+> Create a new FlutterFlow app called `habit_tracker`. Make it a minimalist
+> habit tracker with daily check-ins, streaks, and a weekly progress view.
+
+Codex will:
+
+1. Check FlutterFlow authentication.
+2. Initialize a version-matched FlutterFlow AI workspace.
+3. Read the workspace's generated instructions and typed project SDK.
+4. Plan and validate the app before creating the remote FlutterFlow project.
+5. Return a link to open the project in FlutterFlow.
+
+After the first successful creation, use follow-up prompts in the same workspace
+to edit the project rather than trying to create it again.
+
+## Edit an existing project
+
+If you know the project ID, include it in the prompt:
+
+> Edit my FlutterFlow project `