AI Agent

The AI agent is the heart of Botflow. It has full access to your project’s file system: it reads files, writes diffs, installs packages, and runs terminal commands — all in response to plain-English instructions.

How the agent works

When you send a message, the agent:

Reads context — it inspects your file tree and loads the files most relevant to your request.
Plans — it decides which files need to change and how.
Executes tool calls — each action (read, edit, command, preview refresh) is shown in the chat as a collapsible step.
Replies — it summarises what it did and explains any tricky choices.

You can see every tool call in real time as it happens. Click any step to expand it and read the raw diff or command output.

Models

Botflow supports a curated selection of frontier models. Switch between them at any time using the model selector in the top-left of the workspace.

Model	Provider	Context window	Images
GPT-5.3 (default)	OpenAI	400k tokens	✓
GPT-5.4	OpenAI	400k tokens	✓
Claude Sonnet 4	Anthropic	200k tokens	✓
Claude Opus 4.7	Anthropic	200k tokens	✓
Gemini 3.1 Pro	Google	1M tokens	✓
MiniMax-M2.5	Fireworks	32k tokens	—
GLM-5.1	Fireworks	202k tokens	—
Kimi K2.6	Fireworks	131k tokens	—

The token counter at the bottom of the agent panel shows your estimated usage against the selected model’s limit. When you approach the limit, start a new session with Reset or break your work into smaller tasks.

Provider setup

The agent needs credentials to call a model. You can supply these three ways:

1. Platform credits (Pro / Max)

Pro and Max plans include a monthly allotment of platform-managed credits. Credits are normalised across models — 1 MiniMax token = 1 credit, for example, while cached input tokens cost less. No API key required.

2. Bring your own API key

In Settings → Connections, paste your key for any of these providers:

OpenAI (sk-...)
Anthropic (sk-ant-...)
Google AI Studio (AIza...)
Fireworks AI
Moonshot

Your key is stored encrypted and never exposed to the frontend. For OpenAI and Anthropic you can sign in via OAuth instead of pasting a key:

Claude OAuth — authorise Botflow to use your Anthropic account. Click Connect with Claude in Settings → Connections and follow the PKCE flow.
Codex OAuth — authorise Botflow to use your OpenAI account via a device-code flow. You’ll be shown a short code to enter at openai.com/device.

OAuth tokens are refreshed automatically and never exposed in the UI.

Writing good prompts

Be specific about what you want

Vague	Better
”Fix the login"	"The login form doesn’t show an error when the password is wrong. Show a red message below the input."
"Make it look nicer"	"Use a dark background (#0f0f0f), white text, and Inter font. Increase the card border radius to 12px."
"Add a feature"	"Add a sidebar that lists all users from the /api/users endpoint and highlights the currently selected one.”

Ask for explanations

Explain what the useKanban hook does and why the state is structured that way

The agent will walk through the code in plain English — useful when you inherit an AI-generated project and want to understand it before editing.

Scope your requests

The agent works best when asked to do one thing at a time. Instead of “refactor the entire app”, try “refactor the card component to use a compound-component pattern”.

Example prompts by task

Adding new features

Add a new page at /pricing with three pricing tiers: Free, Pro, and Max. Use a card layout with feature comparison checkboxes.

Create a contact form that sends submissions to a Convex HTTP endpoint. Include validation for email format and required fields.

Add dark mode support using Tailwind's dark variant. Add a toggle in the navbar that persists the preference in localStorage.

Fixing bugs

The app crashes with "Cannot read properties of undefined" when loading the dashboard. Find the issue and fix it.

The submit button stays disabled even when all fields are filled. Check the form validation logic and fix it.

Memory leak warning in the console when navigating away from the chart page. Find and clean up the subscription.

Refactoring code

Extract the user card into a separate component at components/UserCard.tsx. Keep the same props interface.

Convert this class component to a functional component with hooks. Preserve all existing behavior.

Split the large utils.ts file into smaller modules: date.ts, string.ts, and validation.ts. Update all imports.

Integrating APIs

Add Stripe checkout for the Pro plan. Create a Convex action that creates a checkout session and returns the URL.

Integrate the GitHub API to fetch the user's repositories. Display them in a grid with star count and description.

Add Resend email integration. Create a Convex function that sends a welcome email when a new user signs up.

Working with Convex

Add a Convex schema for a blog with posts and comments. Each post has a title, content, authorId, and publishedAt.

Create a real-time query that shows online users. Update the presence every 30 seconds.

Add a scheduled job that runs every hour and sends a digest email with new posts.

Debugging assistance

I'm getting a CORS error when calling the API from the frontend. What's causing this and how do I fix it?

The build is failing with a TypeScript error in the auth module. Here's the error: [paste error]. Fix it.

Why is this useEffect running twice on mount? Is this normal in React 18?

Undoing changes

Undo that last change — it broke the layout. Revert to the previous version.

You deleted the wrong file. Restore the components/Button.tsx file from before your last edit.

Stop what you're doing and go back to the version before you started refactoring.

The agent can only work with files in your current project. If you reference external code or documentation, paste the relevant snippets into the chat or attach a screenshot.

Attaching images

Models that support vision (GPT-5.3, GPT-5.4, Claude, Gemini) can accept images alongside your message. Click the paperclip icon in the input bar to attach a screenshot, mockup, or design file. Use cases:

“Make the UI look like this design” (attach a Figma export or screenshot)
“What’s wrong with this error?” (attach a browser screenshot)
“Recreate this chart component” (attach a reference image)

Context window and Reset

Every message you send adds to the conversation context. When the token counter approaches the model’s limit, responses may become slower or less accurate. Click Reset in the toolbar to start a fresh conversation — your files are untouched, only the chat history is cleared.

Reset clears the entire chat history permanently. There is no undo. If you want to save a particularly useful exchange, copy it before resetting.

Tool calls reference

The agent uses a set of built-in tools to interact with your project. These are shown in the chat as expandable steps.

Tool	What it does
`read`	Reads the contents of a file
`write`	Writes an entire file
`edit`	Makes a targeted edit to a file
`applyDiff`	Applies a patch-style edit to a file
`bash`	Runs a shell command in the project’s sandbox
`glob`	Finds files matching a glob pattern
`grep`	Searches for a pattern across the project
`listFiles`	Lists files in a directory
`startDevServer` / `refreshPreview`	Starts the dev server or reloads the live preview
`askQuestion`	Asks you a question when it needs a decision
`endTurn`	Signals the agent has finished its task

Get Started

Features

Community

Plans

How the agent works

Models

Provider setup

1. Platform credits (Pro / Max)

2. Bring your own API key

Writing good prompts

Be specific about what you want

Ask for explanations

Scope your requests

Example prompts by task

Adding new features

Fixing bugs

Refactoring code

Integrating APIs

Working with Convex

Debugging assistance

Undoing changes

Attaching images

Context window and Reset

Tool calls reference

​How the agent works

​Models

​Provider setup

​1. Platform credits (Pro / Max)

​2. Bring your own API key

​3. OAuth sign-in

​Writing good prompts

​Be specific about what you want

​Ask for explanations

​Scope your requests

​Example prompts by task

​Adding new features

​Fixing bugs

​Refactoring code

​Integrating APIs

​Working with Convex

​Debugging assistance

​Undoing changes

​Attaching images

​Context window and Reset

​Tool calls reference

How the agent works

Models

Provider setup

1. Platform credits (Pro / Max)

2. Bring your own API key

3. OAuth sign-in

Writing good prompts

Be specific about what you want

Ask for explanations

Scope your requests

Example prompts by task

Adding new features

Fixing bugs

Refactoring code

Integrating APIs

Working with Convex

Debugging assistance

Undoing changes

Attaching images

Context window and Reset

Tool calls reference