The feedback loop problem

Reflex emerged from a basic question: how should a mobile app be built when agents write most of the code? The main bottleneck was feedback. An agent can write a screen in minutes, but proving it works requires an emulator, a build, a tap script and patience. Simulator tooling investments hit a ceiling on how fast that could get.

The resulting architecture runs the app's logic headlessly, has every screen expose its state and actions through one small contract, and provides a CLI that drives that contract on both platforms from the same test file.

Four pillars

Reflex is an MVVM-based architecture that shapes the app so an agent can build, test and drive it without rendering UI.

  • No-UI core module: everything except views lives in a module with no UI imports and no device-dependent code, so logic runs headlessly on macOS or the JVM.
  • Strict ViewModel contract: each screen's ViewModel has the same Elm-style shape, with actions in, state out and a single place where state changes.
  • Introspection: each ViewModel is exposed through a JSON contract carrying a name, its state and the actions it accepts, so an outside process can read and act on a screen.
  • Platform-agnostic CLI: agents interact with the app through that contract without launching a simulator or emulator, and one test case can cover both platforms.

Because the same test file runs against iOS and Android, a feature can't ship on one platform without the other following.

Driving a screen

The agent's whole interface is two commands:

  • ls prints the current screen's name, its state as JSON and the actions it accepts.
  • do Action [json] invokes one of them, modeling a user interaction.

The CLI can run against a headless core process or a real build; either way it talks only to ViewModels, never to rendered UI. No TUI, colors or spinners were built — effort went into the feedback loop instead.

Share the test, not the code

Two native apps mean two implementations of every screen, and something must keep them equivalent. The governing principle became: the code is written twice, the tests once. That rests on two decisions.

  1. No shared code. Swift on iOS and Kotlin on Android, each using its own UI toolkit and concurrency model with no cross-platform layer between them. With agents writing most code, a second native implementation costs less than before, while an abstraction layer keeps its full cost: more maintenance, hidden platform behavior needed for performance work, and a two-step migration per platform upgrade. Writing the same ViewModel twice is cheaper than maintaining a bridge.
  2. Parity enforced by tests. Every behavior test runs against both platforms and a PR can't merge if it passes on only one. The test is the shared artifact.

Why not the usual test types

  • Cross-platform end-to-end tests: one test covers both apps, and a few specific flows still use them. Despite high stability with Shopify's own E2E framework, they aren't fast enough for agentic loops and CI checks, they need a simulator or emulator, and debugging means inspecting video or screenshots.
  • Native UI tests (XCUITest, Espresso): faster and more reliable, but still simulator- or emulator-bound and written once per platform, so every test is duplicated and one platform's pass says nothing about the other.
  • Unit tests: fast, but they test a mock of the app rather than the app, must be written twice, and suites drift like codebases do. Comparing the Swift and Kotlin suites says little about whether both apps cover the same journeys.

Reflex lands in the middle, closer to grey box testing. The test sees exactly what the UI sees: the ViewModel's state and the actions it accepts. Underneath is the real thing — real reducers, services, GraphQL client and navigation — with fixtures swapped in at the edges where the app would otherwise reach the network or the device. No mocking frameworks anywhere in the suite.

Two Modules and a CLI: How the Contract Is Enforced

The architecture can be illustrated with a minimal Inventory Management app: the user selects a product, opens its detail screen, and changes its stock count. The example is deliberately incomplete — enough to show the shape. Code is Swift; the Kotlin version has the same structure and reads almost identically.

Each platform app is split into two modules, with a third for the CLI:

  • Core holds everything that isn't UI: ViewModels, services, navigation state, GraphQL, persistence, deep links. On iOS it's a plain Swift package, on Android a plain JVM module — no UIKit, no android.*.
  • Mobile holds the UI and platform integrations: SwiftUI/Compose views, Keychain, push, camera, share sheet. It depends on Core; Core never knows about Mobile.
  • CLI depends on Core exactly as Mobile does, but runs on macOS or the JVM. That is what lets it drive the app without a screen.
Inventory detail CLI test

Core imports nothing from Mobile. It declares protocols for everything it needs from the platform and receives implementations through its constructor — dependency inversion without a DI framework. The mobile app and the CLI are simply hosts that construct Core; the CLI supplies fixtures in place of real platform services.

The payoff of this split:

  • Navigation is a Core concern. Pushing a screen is a state change on a navigator, so the CLI can traverse the whole app without creating a view. Deep links work the same way.
  • Core runs wherever the language runs. The Swift core builds on macOS (and in principle Linux); the Kotlin core is pure JVM. Android behavior tests need a JVM, not an emulator.
  • Tests are fast because nothing renders. No layout pass, no animation, no waiting for a view. An action is a function call followed by a JSON read. More importantly, execution is headless: 1,700+ behavior tests complete in roughly four minutes on CI, on both platforms.
  • Fixtures are constructor arguments. Anything that would normally come from outside the process — a GraphQL response, a Keychain entry, biometrics availability, a feature flag — is passed to the constructor. Testing an edge case means supplying a different fixture, not patching a mock mid-test.

Reflex itself carries no third-party dependencies: a base ViewModel class, one small introspection protocol, and the discipline to keep platform imports out of Core. That discipline is the hard part for humans; for agents it's a pattern to repeat, and repetition is what they do well.

The Object Tree Inside Core

Inside Core, the app is a tree of plain objects. The root app object owns the network client, the current session, and persistence. Beneath it sit navigators (Tab, Push, Modal), each holding the routes currently on screen. At the leaves there is one ViewModel per screen. Nothing in the tree is aware of UI.

Views live in Mobile. A view binds to a single ViewModel, reads its state, and calls send(action:). That is the entire relationship between a view and the rest of the app.

Introspection Kit is a separate module defining the contract between ViewModels and the CLI. Each ViewModel gets a small extension describing it as a node: a name, its state as JSON, and the actions it accepts. The CLI and the test SDK talk only to that layer; the app never calls it.

Core module

ViewModel Anatomy: Action In, State Out

Every screen is backed by a ViewModel shaped after the Elm architecture:

  • State — everything the screen displays, owned by the ViewModel. The View reads it and nothing else.
  • Action — the public surface, an enum of everything a View or the CLI can ask the ViewModel to do, dispatched via send(action:).
  • Message — the internal surface: Action wrapped in .viewAction, mostly carrying results returned from services. Only the ViewModel sees these.
  • update(state, message) — the reducer and the only place state ever changes. Every path converges here.
  • Services — network, storage, anything with a side effect, supplied as protocols through the constructor so the CLI can swap in fixtures.

The View's contract is limited to reading state and calling send(action:); it never invokes a ViewModel method or writes state. Because the shape is this strict, an agent can reproduce it correctly hundreds of times.

Introspection Kit: The ViewModel From Outside

The CLI needs to read a ViewModel and send actions to it. A ViewModel satisfies the contract by returning a node from its +Introspection extension, which holds a reference back to the ViewModel. On Android the idea is identical with one wrinkle: Kotlin extensions can't add protocol conformance to a type, so the node is a separate InventoryDetailViewModelIntrospectionNode class alongside the ViewModel. The app never calls any of this — delete the file and the app builds and runs unchanged; only terminal-driven control is lost.

A node has four parts:

  1. name — a stable identifier for the screen, letting tests know where they are.
  2. state — the ViewModel's state encoded as JSON, covering every user-visible field.
  3. actions — one entry per Action case: a title and a closure that calls send(action:). Actions may take a parameter: SetQuantity declares an input type, and the CLI decodes a JSON object into that type before running the closure. The @IntrospectionInput macro generates the input's JSON schema from its properties, so the CLI can show what an action expects and reject malformed payloads before they reach the ViewModel — with no hand-maintained schema.
  4. child — an optional link to the node below. Following child from the root is how the CLI finds the focused node and how actions propagate downward.

Writing nodes by hand (with agents) is viable, since agents reproduce the shape reliably — but the strictness also allows generation: a macro or annotation on the ViewModel suffices to produce the node at build time.

Three rules govern nodes:

  1. If a user can see it, it's in state; if a user can do it, it's in actions. The node is a plain JSON view of the ViewModel.
  2. The node never repeats UI logic. It lists every action, every time, with no conditionals. Whether Decrement does anything at zero stock is the ViewModel's decision, made in update, exactly where it's made for a button tap. An if in a node means the rule belongs in the ViewModel and the result in state.
  3. Actions go through send(action:) and nothing else. The node never calls methods on the ViewModel or mutates state, so the CLI can't do anything a View couldn't.

The contract is not test-only. The app is meant to be agentic-first, and the same state-and-actions surface is what Sidekick, Shopify's AI assistant, uses to act inside the app — no separate integration layer. Anything an agent can do from the terminal, an in-app agent can do too.

The Tree and Its Transport

Introspection nodes mirror the object tree one-to-one, linked through child: the app root's node has the navigator as its child, the navigator's node has the top route's ViewModel as its child. The CLI always focuses the deepest node in the chain, just as a user only interacts with what's on top.

Containers can deliberately lend actions to the focused child: a stack navigator propagates goBack, a tab navigator propagates selectTab, while a plain ViewModel propagates nothing. Ask the CLI to run an action that is neither on the focused node nor lent by an ancestor, and it refuses, listing the available actions.

In the headless CLI, the core process reads newline-delimited JSON from stdin and writes it to stdout. In a real build, a small socket server provides the same pipe over a port, connected to the same ViewModels the screen binds to. That is why the simulator updates as you type commands — zero interaction with the rendered UI, merely views observing state. The server is compiled out of release builds and does not exist in what ships.

The Test Trophy

Test distribution ended up closer to a trophy with a very wide middle than to a pyramid:

  • Unit tests cover primitives and shared components: formatters, parsers, the base ViewModel, pagination helpers. Small and few.
  • CLI behavior tests cover everything else: business logic, validation, navigation, error handling, full user journeys. They are the bulk of coverage, run on both platforms from one file, and back Helix's behavior gate — a checkpoint doesn't advance until its CLI tests pass on both platforms.
  • A thin top layer holds a handful of live integration journeys plus a performance suite that drives real builds through the same protocol.
Our test trophy

Network Access Blocked by Design

A behavior session installs a guard that blocks every HTTP request in the host process and fails the test if one was attempted — even if the app caught the error and recovered. Every network call and external dependency therefore needs a fixture. The suite gains no I/O and no flakiness; the cost is bulky fixtures. One journey can carry a dozen GraphQL responses — tedious for a human to maintain, but fine for an agent.

Readable Failures, Journey-Style Tests

A failing grey box test states plainly which assertion failed, giving an agent enough to act on without a debugger.

A small test SDK for Introspection Kit sits on Bun's test runner. It speaks the same JSON protocol as the CLI, has no runtime dependencies, and adds two helpers to bun:test: precondition, which waits until the focused node is the expected one, and do, which runs an action and waits for an expectation on the fresh state. A detail-screen test written with them runs unchanged on iOS and Android, with the harness picking the platform.

Both helpers poll for a couple of seconds, then fail with the last state they saw — no sleeps, no wait-for-element helpers. The test reads as a transcript of what a user did and saw.

Tests could be arbitrarily granular, but deliberately aren't. Incremental unit tests pinpoint breakage; here the failure message already identifies the journey step, the action, and the expected versus observed state. Agents can read that and find the cause without a pinpoint test, so journey steps are folded into one test, spending the savings on execution time and maintenance. Scenarios needing distinct fixtures — a save failure, say — stay separate because the setup differs, not the assertion.

Four steps

After a warm-up step, the example test runs in a couple hundred milliseconds without a device, on both platforms.

Test case run speed

The same test on an iOS simulator takes around two seconds.

iOS simulator test

Bringing Reflex to another codebase

The architecture is the artifact, not the code. Introspection Kit is welded to Shopify's session model, its navigators and its fixture formats, so packaging it for outside use would carry across none of the value. What does carry across is Reflex itself, which a capable coding agent can implement in your own language and style from the published description. The result should fit your codebase better than any distributed library could.

The prerequisites, as Shopify frames them:

  • Split platform out of the core. A single module with no UI imports, receiving every platform capability through its constructor. If the core can't build on macOS or the JVM, the split isn't finished.
  • Give every ViewModel the same shape. An action in, state out, one update, services injected via the constructor.
  • Attach introspection as an extension. State serialized as JSON and every action exposed as a closure over send(action:), with no conditionals; agents can generate these directly from the ViewModel.
  • Assemble a tree and scope to the leaf. The app root and navigators are nodes as well, and containers may lend a few actions downward. Everything else stays out of reach, much as off-screen UI is out of reach for a user.
  • Cut the network entirely. Fixtures for every dependency are the only way a large suite remains deterministic.
  • Write skills instead of documentation. The agents need to be taught to run the CLI, add a fixture, name a test; the tool is only as useful as the agent's ability to invoke it.
  • Drop human-facing complexity. No TUI, no styled output, no interactive wizards. The audience is agents, so keep the tool minimal and fast.

The payoff Shopify reports is a feedback loop that runs at agent speed and a single suite keeping two native apps aligned. That suite now serves as the shared source of truth between the iOS and Android apps, agents author most of it, and a terminal running ls is still the quickest way to learn what the app does.

Objections and trade-offs

Logic coverage without UI assertions

Shopify argues that screen failures are mostly logic failures, which is where the tests sit; confirming a button calls send(action:) is rarely the source of bugs. UI checking lives in two other places: each Helix checkpoint gets a visual review against the reference app before landing, and screenshot tests remain for the handful of components where pixels matter. Daily use of the app supplies further organic testing. Shipping decisions rest on ViewModel behavior tests plus those two layers.

Compared with unit tests, XCUITest and Espresso

Unit tests and native UI tests share a limitation: each is written once per platform and neither establishes parity between them. The comparison also omits exploration. Conventional test tooling gives an agent no way to walk the app outside a pre-written test, and exploration proved as valuable as the tests themselves — an agent that can ls through the app debugs and ships features faster. That same agent-facing surface is what makes the app agentic-first for Sidekick, which otherwise would have been bolted on separately.

Why not Appium or device automation

Shopify uses such tools where appropriate. Owning the codebase allows a grey-box interface in which the agent reads state directly rather than inferring it from an accessibility tree or a screenshot, saving round trips spent reading the screen. Headless execution matters more: thousands of tests complete in a few minutes on CI, whereas end-to-end coverage at that breadth would take hours and substantial parallel infrastructure.