Codex Flutter is the practice of using the OpenAI coding agent Codex inside an existing Flutter project. You run codex in the project folder, give it Flutter-specific guidance through AGENTS.md, and review each change with the same tools you already use. This guide covers a practical setup and working loop for Flutter developers who already know Dart, widgets, and state management. For the agent itself, see Codex.
Why Codex is a good fit for your Flutter codebase
Flutter projects are a good fit for Codex because most changes are local and testable. The agent can read your widget tree, follow your state management convention, and write Dart code that matches the existing style when AGENTS.md is clear. It can also generate widget tests, update platform channel code, and run flutter analyze or flutter test in its terminal. The value is not that it knows Flutter better than you; it is that it can do the repetitive parts, such as creating a screen, converting a setState widget to Provider, or adding a method to a platform channel, while you review the design and edge cases. For the basics of running the CLI, see How to use Codex CLI: a step-by-step guide.
Setting up AGENTS.md for a Flutter project
Before starting, create or update AGENTS.md in the project root. Codex reads this file at the start of a session, so it should contain the commands you use, your folder conventions, and Flutter-specific rules. Keep it short and actionable; do not write paragraphs about your whole architecture. The following block works well for a typical Provider-based Flutter app:
# AGENTS.md
## Commands
- flutter pub get
- flutter test
- flutter analyze
- flutter build apk --debug
## Folder conventions
- lib/features/<feature>/presentation for widgets and screens
- lib/features/<feature>/data for repositories and models
- test/ mirrors lib/
## Flutter rules
- Prefer const constructors where possible.
- Do not use BuildContext across async gaps.
- Use Provider for state management; no setState in screens.
- Add widget tests for new UI components.
- Keep platform channel code isolated in lib/platform/.
- Run flutter analyze and flutter test before finishing a task.This tells Codex exactly how to build, test, lint, and where to put files. It also prevents common mistakes such as using BuildContext across async gaps or scattering platform channel code. If you use Riverpod or Bloc, replace the state management rule with your own convention.
A practical working loop for Flutter tasks
Plan first, then ask for small changes. A good loop is: define one task, let Codex propose the change, review the diff, run the tests and analyzer yourself or in the agent terminal, and only then commit. Do not ask for a whole feature in one prompt. Use the following prompts as starting points.
| Task | Good prompt |
|---|---|
| Add a login screen | Create a new LoginScreen widget under lib/features/auth/presentation. Use Provider for the auth state and add a matching widget test. |
| Convert a StatefulWidget to Bloc | Refactor the counter screen to use Bloc instead of setState. Keep the same UI behavior and update all tests. |
| Add a platform channel method | Add a method channel in lib/platform/ to get the device battery level. Implement the Android and iOS sides and show the value in a screen. |
| Fix failing widget tests | Run flutter test, find the failing tests, and fix the smallest change needed in the widget tree or test setup. |
| Improve performance | Profile the list screen with flutter run —profile and identify rebuilds. Suggest and apply one fix using const widgets or RepaintBoundary. |
After each prompt, ask Codex to show the diff and explain the non-obvious choices. If the test suite fails, have it fix only the failing test rather than touching unrelated files. For larger features, break the work into vertical slices: one screen, one state provider, one test file at a time. When Codex edits platform channel code, ask it to show both Dart and native files in its diff, because a Dart-only change will compile but fail at runtime.
Flutter tasks Codex handles well, and pitfalls to watch
Codex is strong at mechanical Flutter work: creating simple or composite widgets, applying state management patterns, writing widget tests, updating imports after a refactor, and adding platform channel endpoints. It is also useful for converting a StatefulWidget to Riverpod or Bloc when the behavior is well understood.
Watch it closely in these areas:
- BuildContext after async: Flutter requires mounted checks before using context after await.
- Lifecycle and controllers: agents sometimes create AnimationController, TextEditingController, or streams without disposing them.
- State management boundaries: if you say use Bloc but the code already uses Provider, Codex may mix patterns unless AGENTS.md is explicit.
- Platform channels: type mismatches and missing native code on Android or iOS are common. Always test on both platforms when a channel changes.
- Generated files: if you use freezed, json_serializable, or riverpod_generator, Codex may edit generated files directly. Tell it to run build_runner instead.
- Hot reload assumptions: code that works under hot reload may fail on a cold start; ask for a full restart test when behavior changes.
Testing and verification when using Codex
Flutter gives you fast feedback if you use it. After every Codex change, run flutter analyze to catch unused imports and type errors, then flutter test to run unit and widget tests. For UI-heavy changes, add or update widget tests that pump the widget and verify the expected text or state. If you use platform channels, mock the channel in tests with TestDefaultBinaryMessengerBinding and verify the method call arguments. For golden files, review the images carefully; Codex can generate them, but a small rendering difference may be unintentional. Before merging, review the full diff with an AI code review step to catch Flutter-specific issues such as missing const, BuildContext misuse, and controller leaks. For a checklist, see AI code review: check what your agents write.
Parallel agents on one Flutter repo with AgentVera
For Flutter teams running several Codex agents on one repository, AgentVera is useful because each agent runs in its own real terminal and git worktree, so parallel work on different widgets or features does not overwrite files. The automatic code review after each turn matters for Flutter because it can flag misplaced BuildContext use or missing const optimizations with file:line links. Checkpoints let you undo a bad refactor or replay a session, which helps when state management changes ripple through many files. Token budgets stop long platform channel or widget tree tasks from consuming the whole day.
Final notes for Codex and Flutter
Codex works well in Flutter when you treat it as a fast pair programmer with a short memory: put conventions in AGENTS.md, give one small task at a time, run flutter analyze and flutter test after each change, and review diffs like you would from a colleague. Use worktrees for parallel agents and automate the review step for widget and state management changes. That discipline turns Codex from a demo into a reliable part of your Flutter workflow.