Skip to main content

AI-friendly Flutter state management

More Flutter code is now written with a coding agent in the loop than ever before. Whether the assistant is in your editor or in Claude Code, the same thing decides whether its output is mergeable: how much it has to infer, and how many ways it can be subtly wrong. State management is where most of that risk lives, because it is where control flow, data flow, and lifecycle meet.

utopia_hooks is built so an agent has the least to infer and the fewest ways to go wrong. Three properties do the work: the hook model is linear and explicit, a screen is a handful of files with almost no ceremony, and the package ships an authoritative AI skill that tells an agent exactly how the library is meant to be used. This page makes the case for each, and keeps the comparisons honest.

The hook model is what an agent reasons about best​

A coding agent is strongest when it can read code top to bottom and recover the data flow without holding hidden context. A hook is exactly that shape. It is called from build, in order; each line declares a piece of state or a derived value; dependencies are passed explicitly as a keys array; and the value a hook returns is the value the next line uses. There is no event bus, no dispatcher, no generated layer between the call and its effect. When an agent reads:

final user = useProvided<AuthState>().user;
final orders = useAutoComputedState(() => api.orders(user.id), keys: [user.id]);

it can see the whole story: orders re-fetches when user.id changes, and nothing else moves. The dependency is right there in keys. Nothing reaches in from off-screen.

Contrast that, fairly, with the two most common alternatives.

BLoC routes every change through an event, a handler, and an emit. To follow what happens when a button is tapped, an agent has to connect the widget that adds the event, the event class, the on<Event> handler that catches it, and the emit that publishes the next state - four artifacts in three places, linked by type rather than by call. Each link is a place to emit the wrong state, forget a handler, or mismatch an event. The indirection is deliberate and has real benefits for humans; it just gives an agent more moving parts to track and more ways to get it subtly wrong.

Riverpod is closer in spirit - reactive state read from anywhere - but its idiomatic path leans on code generation. The provider an agent should reference often lives in a .g.dart file the agent never sees, so it reasons about a declaration whose generated counterpart is out of view, and it has to keep provider kinds (Provider, NotifierProvider, FutureProvider, StreamProvider, family, autoDispose) straight to pick the right one. That is more surface to get right than "it is a hook, and the async loading is a hook too."

With hooks there is no generated file to be out of sync with, and no event-to-state indirection to trace. The code the agent reads is the code that runs.

Fewer files and less ceremony means less to get wrong​

Every screen in utopia_hooks is the same three pieces: a State class that holds the data, a hook that builds it, and a View that renders it. The Screen / State / View pattern is uniform across the whole app, so an agent does not rediscover the structure per feature - it fills in a shape it already knows.

That uniformity shrinks the context an agent must hold. A new screen is a small, predictable diff in known places, not a scattering of providers, event classes, and generated parts. Loading and pagination, the two states most likely to be hand-rolled wrong, are single hooks - useAutoComputedState and usePaginatedComputedState - rather than a bool isLoading plus a try/catch/finally, or a List plus hasMore plus a cursor that an agent has to assemble correctly each time. Fewer files and less boilerplate mean less for the agent to read, fewer names to keep consistent, and fewer empty slots where it can hallucinate something plausible but wrong.

The same property that makes hooks easy for a person to review - all of a screen's logic in one testable place, no base class, no ceremony - is what makes them safe for an agent to write.

The skill: authoritative guidance instead of guesswork​

Left to its training data, an agent writing Flutter state management produces an average of everything it has seen, which means it reaches for whichever pattern was most common in its corpus, not the one this library intends. utopia_hooks closes that gap with a first-class AI skill, /utopia-hooks, that an agent loads as authoritative, project-correct reference instead of guessing.

The skill is not a one-page cheat sheet. It is a priority-ordered set of reference files covering, among other things:

  • the Screen / State / View pattern and its lightweight tier
  • the full hook catalog: useState, useMemoized, useEffect, useProvided, useInjected, and the computed-state hooks
  • async patterns - useSubmitState, useAutoComputedState, useMemoizedStream - and cursor-based pagination
  • global state registration, app bootstrap and ordering, error handling, and navigation conventions
  • dependency injection, unit-testing hook states with SimpleHookContext, and the project's Flutter conventions

It also ships a set of non-negotiable rules and a self-audit checklist - the View never calls hooks, the Screen is pure wiring, no manual loading state, no hand-rolled pagination - so the agent does not just write code, it checks its own output against the same rules a human reviewer would apply.

Crucially, the same conventions are machine-checked. The canonical analyzer lives in utopia_cli, so the rules an agent follows are the rules CI and pre-commit enforce - guidance and validation do not drift apart. An agent working in Claude Code has its edits validated against utopia hooks analyze as it goes, which turns "looks plausible" into "passes the gate."

The effect is that the agent has a correct answer to reach for. It produces idiomatic utopia_hooks code on the first try far more often, because it is following the library's own guidance rather than reconstructing it from memory.

The utopia-hooks skill covers what it encodes and how it changes an agent's output; installation is a one-line marketplace add in Claude Code, on that page.

Why it adds up​

These three properties compound. Less indirection means the agent reasons correctly about the code it reads. Less boilerplate means there is less code for it to get wrong in the first place. An authoritative skill plus a machine-checked gate means it writes to the library's actual conventions and catches its own slips. Together they make an agent's first draft of a utopia_hooks screen far more likely to be correct, idiomatic, and mergeable - which matters more every month, as more real Flutter apps are built with an agent doing the typing.

If you are evaluating state management for a codebase that an AI will help maintain, this is the case for utopia_hooks: it was designed to be read, written, and verified by a machine, without giving up anything that makes it good for the humans reviewing the result.

See also​



Crafted for you by UtopiaSoftware 👾