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:
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.
3. OAuth sign-in
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
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 | 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 |
