Skip to main content

AI Agent

AI Agent lets you work with AI coding agents directly from the FlutterFlow desktop app. Instead of manually opening a terminal, navigating to your project, and configuring command-line tools yourself, FlutterFlow checks the required setup and helps prepare the tools needed to work with your project.

After you choose an agent, FlutterFlow launches it with the correct project context. Depending on your selected agent, FlutterFlow may also install or verify the required CLI, initialize or reuse a local FlutterFlow AI workspace, register the FlutterFlow MCP server, and guide the agent through authentication. Once connected, you can describe the change you want, review the agent's plan, and apply updates to your project.

The agent works with your FlutterFlow project through the FlutterFlow CLI and the same agent workflow described in Build with AI Agents.

Desktop app only

AI Agent is available only in the FlutterFlow desktop app. It is not available in browser-based FlutterFlow. To use AI Agent, download the FlutterFlow desktop app.

Different from in-app AI Agents

This page is about using external AI coding agents to build and edit your FlutterFlow project. If you want to create AI-powered chat, text-to-speech, speech-to-text, image generation, or video generation experiences inside your app, see AI Agents.

AI Agent is useful for project editing tasks such as:

  • Creating or updating pages and components
  • Adjusting widget properties, layout, styling, and responsiveness
  • Wiring actions, action blocks, app state, and app events
  • Updating theme values, design tokens, and navigation
  • Reviewing project structure and finding issues
  • Applying focused changes to a specific widget with Copy AI Selector

For more details about what agents can and cannot edit, see Agent Edit Scope.

Prerequisites​

Before using AI Agent, make sure you have:

  • The FlutterFlow desktop app installed and signed in.
  • An account with the provider of your selected agent, such as a ChatGPT account for Codex or an Anthropic account for Claude.

Set Up AI Agent​

When you open AI Agent for the first time, FlutterFlow checks whether the required tools are ready for the selected agent.

info

You do not need to download a separate AI agent desktop app before getting started. The setup panel checks the required CLI tools for the selected agent and lets you install missing tools from the AI Agent setup panel.

To set up AI Agent:

  1. Open your project in the FlutterFlow desktop app.
  2. Select the brain icon in the toolbar.
  3. In the Set up your AI agent panel, choose Claude or Codex.
  4. Review the setup checklist. FlutterFlow checks the selected agent's CLI, Flutter SDK, FlutterFlow CLI, local workspace, and sign-in status.
  5. If any required CLI tools are missing, click Install required tools.
  6. After installing tools or signing in, click Re-check to refresh the setup status.
  7. When prompted, sign in with the account for the selected agent, such as your Anthropic account for Claude or your ChatGPT account for Codex.

The selected agent runs on your own account and follows that account's usage and limits. The coding CLI runs locally on your Mac and sends prompts, relevant project context, and model responses through your selected agent provider. Data handling and retention follow your provider account's policies and data controls. FlutterFlow does not receive or store your conversations.

Use AI Agent​

After setup is complete:

  1. Describe what you want the agent to do, such as "Create a profile settings page," "Fix the login button action," or "Update this card to match the new design."
  2. Review the agent's proposed changes before applying them.
  3. Verify the result visually.
tip

For targeted widget updates, right-click the widget in the builder and select Copy AI Selector. Paste the selector into your prompt so the agent can locate the exact widget you want to update.

Read the Agent's Steps​

While the agent works, the panel groups its steps by the file or screen they relate to. For longer tasks, related steps appear in grouped rows. Each project change appears in a separate row. Select a row to see the full details of the step, such as the command the agent ran.

Follow the Agent's Plan​

When the agent makes a plan for a task, the panel shows it as a checklist that the agent updates as it works. The header reads Plan followed by the progress, such as 2 of 5 done.

While the agent works, the checklist stays in view above the status line next to the spinner. Each step shows its status:

  • Not started: An empty circle.
  • In progress: A dot, with the step in bold on a tinted row.
  • Done: A green check, with the step struck through.

When the agent finishes, the checklist returns to its original position in the conversation and collapses to one line, such as Plan 3 of 5 done. Select the line to expand the steps. Plans in earlier conversations appear the same way.

The checklist appears only when the agent sends a plan, so not every task has one. If the agent drops a step from its plan, the step is removed from the checklist and the total step count is updated.

See What the Agent Is Doing​

The status line next to the spinner describes what the agent is doing instead of only showing Working…. For example:

  • Writing pages/home_page.dart… while the agent edits a file. The path is relative to the agent's workspace.
  • Checking the project… while the agent validates your project.
  • Saving to FlutterFlow… while the agent pushes its changes to your project.
  • Saved, with a green check, after a push finishes successfully. The line stays until the agent starts its next step.

The status line also describes steps such as reading files, searching the project, and running tests. When a tool doesn't have a specific status message, the line reads Using a tool…. While the agent is thinking or writing its reply, it reads Working….

Attach Images​

You can send images to the agent along with your message, such as a screenshot of a design you want to match or a screenshot showing an issue. FlutterFlow supports PNG, JPEG, GIF, and WebP images.

To attach an image, use any of these methods:

  • Paste an image from your clipboard into the prompt box.
  • Drag an image file onto the prompt box.
  • Click Attach files (the paperclip icon) and select an image.

Each image appears in the prompt as an attachment. In the conversation, hover over the attachment to preview the image.

Work with Branches​

The agent works on the branch you have open in the editor. When you switch to another branch, the agent follows you. When the agent wants to work on a different branch, it asks you first. The agent never moves the editor to another branch on its own.

Switch Branches in the Editor​

When you open another branch from the branches menu, create a branch, or close a branch, the AI Agent panel stays open and keeps the same conversation. The panel shows Moving the agent to branch … while it moves the agent's workspace to the branch. When the move finishes, the conversation shows a Now on branch … marker, and a Branch … chip appears in the prompt box. The chip identifies the current branch and is included with your next message to the agent.

Respond to a Branch Request​

When the agent wants to switch to another branch, a prompt appears above the prompt box. It reads The agent wants to switch to branch …. If the agent also asks to create the branch, it reads The agent wants to create and switch to branch …. Choose one of the following:

  • Switch: FlutterFlow creates the branch if the agent requested a new one and it doesn't exist yet. It opens the branch in the editor and moves the conversation there. New branches start from the latest commit of your current branch and include your uncommitted changes. This matches creating a branch from the branches menu. A Branch … chip confirms the switch and is included with your next message to the agent.
  • Not now: The agent stays on the current branch. A Branch switch declined chip records your decision and is included with your next message to the agent.

Unpushed Edits​

If the agent has edited page files in its workspace and hasn't pushed them to your project, switching branches would discard those edits. In that case, the prompt reads The agent has unpushed edits and lists the affected files. The editor stays on the current branch until you choose one of the following:

  • Not now: Stay on the current branch. You can ask the agent to push its edits first, and then switch.
  • Discard and switch: Discard the unpushed edits and move to the other branch.
  • Try again: Check the workspace for unpushed edits again, for example after the agent has pushed them, and then switch.

If FlutterFlow can't switch, the prompt reads Couldn't switch to branch … with the reason. Select Try again to retry, or Not now to stay where you are.

note

If the AI Agent panel is open in a separate window, you can see and decline a branch request, but Switch is unavailable. Dock the panel back into the editor to switch branches. Switching branches in the editor while the panel is in a separate window closes that window.

Move the Panel​

By default, the AI Agent panel is docked on the right side of the editor. To move it, follow these steps:

  1. Click the Open in separate window icon in the panel header.
  2. Click and hold the header of the separate window, then drag it to the position you want.

When Test Mode is open, it makes room beside the panel instead of opening underneath it. If the support chat bubble is visible, it moves beside the panel while the panel is open.

Settings​

Select the Settings icon in the AI Agent panel to manage how FlutterFlow connects to local agents, stores workspaces, and opens sessions.

  • Workspace location: Shows where FlutterFlow creates local MCP workspaces on your Mac and displays the current workspace for the open project.
  • Claude: Lets you sign in to Claude and review the permissions that control which tools Claude can run without asking each time. You can open the Claude permissions file at ~/.claude/settings.json.
  • Codex: Shows your signed-in ChatGPT account, plan, and current usage limits as reported by the Codex CLI. You can also log out from here.
  • Codex permissions: Lets you review the permissions that control which tools Codex can run without asking each time. You can open the Codex permissions file at ~/.codex/config.toml.
  • Terminal: Selects which terminal app FlutterFlow uses when you choose Open in terminal to resume an agent session.
  • Show conversation recap: Turns the conversation recap on or off. When enabled, FlutterFlow shows a one-line recap above the prompt after a few exchanges in a thread.
  • Troubleshooting: Lets you download diagnostic logs for AI Agent setup and conversations, including tool installs, workspace initialization, CLI launches, and errors. Conversations and personal data are not included in these logs.
  • Privacy: Confirms that the coding CLI runs locally and that conversations are handled according to your selected agent provider's policies and data controls. FlutterFlow does not receive or store your conversations.
tip

If the setup status does not update after installing tools or signing in, click Re-check. If it still does not update, restart the FlutterFlow desktop app and open the AI Agent panel again.

Best Practices​

  • Be specific about the outcome you want, not just the widget you want changed.
  • Use Copy AI Selector when multiple widgets look similar or when the target widget is deeply nested.
  • Ask the agent to inspect the current project before making broad changes.
  • Review changes in the visual builder before continuing with additional prompts.
  • Keep a Live Session running only while you are actively using it.