opencode Flutter: a practical guide for Flutter developers

opencode is a command-line coding agent that you start inside a Flutter project folder with opencode. It reads project instructions from AGENTS.md and can edit Dart, widget, test, and platform channel files, then run the usual Flutter verification commands. This guide covers a practical setup and working loop for Flutter teams, including how to keep several agents from stepping on each other. For a general introduction, see opencode.

Why Flutter teams benefit from opencode

Flutter projects have a predictable shape: lib/ for Dart code, test/ for tests, pubspec.yaml for dependencies, and platform folders for Android and iOS. opencode can use that shape because it works directly in the terminal with the same commands you already run: flutter pub get, dart format, flutter analyze, and flutter test. That matters more than model specifics: the agent can edit a widget, format the file, run the analyzer, and run affected widget tests without leaving the project.

The second reason is that Dart code often needs coordinated edits across a feature: a model, a provider or bloc, a widget, and a test. opencode can plan those edits across files instead of returning a single code suggestion. When you add AGENTS.md rules for naming, state management, and generated code, it can follow the project’s actual conventions rather than inventing its own. For a deeper general workflow, see How to use opencode: a step-by-step guide.

Preparing your Flutter repo for opencode

Before starting a long task, create or update AGENTS.md in the repository root. opencode reads this file at the start, so use it to encode the commands and rules that a new Flutter developer would need. Keep it short and specific; it is not a design document.

A realistic AGENTS.md for a Riverpod-based Flutter app looks like this:

# AGENTS.md

## Commands
- Install dependencies: flutter pub get
- Analyze: flutter analyze
- Test: flutter test
- Format: dart format lib test
- Run a single test file: flutter test test/path/file_test.dart

## Folder conventions
- lib/features/<feature>/presentation: widgets and screens
- lib/features/<feature>/application: Riverpod providers and notifiers
- lib/features/<feature>/domain: entities and repository interfaces
- lib/features/<feature>/data: repository implementations
- test/features/<feature>/: mirrors lib/features structure

## Rules
- Use Riverpod for state; do not introduce Bloc or Provider patterns.
- Do not edit generated files: *.g.dart, *.freezed.dart, *.gr.dart.
- Do not add or remove dependencies without asking.
- Keep widgets small; no business logic in build methods.
- Use const constructors where possible.
- Fix all analyzer warnings before finishing a task.

The file names concrete commands instead of approximations, and it tells the agent not to touch generated files or add packages. That alone removes a large share of Flutter-specific mistakes.

A repeatable Flutter editing loop

Do not hand opencode a whole feature and wait. Use a tight loop: describe the smallest useful change, let the agent plan and edit, then run verification, read the diff, and either accept or narrow the next prompt. For Flutter, the verification loop is usually:

1. dart format --set-exit-if-changed lib test
2. flutter analyze
3. flutter test
4. Review git diff for unintended changes, especially pubspec.yaml, generated files, and platform folders.

Example prompts that fit this loop:

• Add a ProductCard widget under lib/features/catalog/presentation/ with loading, error, and data states, using the existing AppText and AppButton widgets. Add a widget test in test/features/catalog/.
• Refactor AuthService to use Riverpod’s AsyncNotifier instead of the current ChangeNotifier. Update all call sites in lib/ and fix any widget tests that break.
• Add a method channel wrapper in lib/platform/battery_service.dart that reads battery level from Android and iOS. Implement the native Kotlin and Swift sides and add a Dart unit test with a mocked MethodChannel.
• Find every use of BuildContext across an async gap in lib/features/checkout/ and fix the unsafe patterns by checking mounted or using the provider’s ref instead. Add a regression test for one case.

Where opencode excels and stumbles in Flutter

opencode is strongest at tasks with a clear diff and a clear check: extracting widgets, adding tests, converting a state management pattern, updating models, and writing platform channel boilerplate. It is weaker when the correct answer depends on runtime behavior, animation feel, or platform-specific quirks that only show up on a device.

Watch closely in these Flutter-specific areas:

• Generated files: *.g.dart, *.freezed.dart, *.gr.dart, and localization output should not be hand-edited. Add an AGENTS.md rule for this and check the diff for generated files before committing.
• State management cohesion: if the project uses Riverpod or Bloc, the agent may take the shortest path and call a repository directly from a widget. Verify that the change still respects the existing provider/bloc layer.
• BuildContext and async gaps: an agent can introduce use_build_context_synchronously warnings or setState after dispose when it moves code around. Run flutter analyze after every change and treat these warnings as failures.
• Platform channels: the Dart side is easy, but the agent can silently skip the Kotlin or Swift side or edit only one platform. Review android/ and ios/ diffs together.
• Pubspec and dependency changes: the agent may add a package to solve a small problem. Tell it in AGENTS.md to ask before modifying pubspec.yaml, and never accept a new dependency without checking its maintenance and platform support.
• Golden tests: if your project uses goldens, the agent may update baseline images too eagerly. Prefer that it only run flutter test --update-goldens when you explicitly ask.

A short task-to-prompt table can help keep the work tight:

Verifying Flutter changes with the agent

Make verification part of the prompt contract. For every non-trivial change, ask opencode to run the commands and show the output. Do not rely on the agent’s summary; run the same commands yourself before merging.

The minimum gate for a Flutter change is:

• dart format --set-exit-if-changed lib test
• flutter analyze
• flutter test

If the change touches platform channels, add at least one Dart-side test with a mocked MethodChannel and then run flutter build apk --debug on Android and, where available, flutter build ios --simulator to catch native compile errors. If the change touches generated code, run dart run build_runner build --delete-conflicting-outputs only when the source annotations changed, and never commit the generated files if they are ignored by the project.

Ask the agent to fix any analyzer or test failure before moving on. If the agent tries to weaken a lint rule or delete a failing test to make the suite pass, reject that diff immediately. Flutter’s analyzer rules often encode real bugs, such as unsafe context use or missing const constructors.

Parallel Flutter work with AgentVera

When you have multiple Flutter tasks in flight, AgentVera lets you run several opencode CLI agents side by side, each in its own real terminal panel and usually its own git worktree. For Flutter this matters because two agents editing lib/ at once can overwrite each other’s widget changes; worktrees isolate those edits until they are ready to merge. Automatic code review after each turn catches Dart-specific issues like unsafe context use or broken provider wiring, and checkpoints let you undo a bad refactor in one click. Token budgets prevent an agent from burning a full session on endless flutter run loops or build command churn.

Final notes

opencode becomes much more reliable on Flutter when the project tells it exactly how to build, test, and follow conventions. Start with a concise AGENTS.md, keep tasks small, make analyzer and tests the definition of done, and review every diff for generated files, state management, and platform channel changes. For parallel work, isolate agents in worktrees and use review plus checkpoints. With that loop, opencode handles a lot of the mechanical Flutter work without turning a widget refactor into a debugging session.