Reflex is an application control protocol that makes behavior inspectable and executable
with or without a UI. An app exposes a graph of stateful nodes; a client (the reflex
CLI, a test, or a coding agent over MCP) reads their state, discovers their typed
actions, runs them, and watches what changes. The same commands work against the app running headless or live
through a bridge. The inventory example proves the same behavior journey with fixtures
headless and a real local HTTP API plus device storage in the Expo app; see
real services setup.
It is inspired by Shopify's Reflex, as described in their engineering post. This is an independent project, not affiliated with or endorsed by Shopify.
Agents and tests usually learn what an app does from screenshots and source code, and drive it through a simulator. Both are slow and lossy. If behavior lives in a headless core with an explicit control surface, an agent can run most checks with no UI at all, then confirm selected behavior against the real app through the same commands. Reflex is that control surface for applications, with adapters for existing stores and Effect v4. Expo is the first platform binding; the runtime and live bridge need no React, React Native or Expo.
reflex CLI ─┐ ┌─► headless session ──► app core (store/Effect)
MCP client ─┼─► session socket ─► CLI ─┤
journeys ───┘ (JSON-RPC) daemon └─► device bridge ──WebSocket──► app on a device
(any framework, same core)
- Protocol and runtime: JSON contracts, a registry of nodes, operations and events, and type-bearing store definitions with Standard Schema inputs.
- Effect integration:
Screen,defineService,defineFixture,defineNavigation,defineApp. - CLI: background sessions, the device bridge and the MCP server.
- Live serving:
@reflex/liveconnects any JS app to the bridge with a global WebSocket. - React bindings:
createReflex(app)from@reflex/reactbinds a Provider and typed hooks without a router dependency. - Router-neutral projection:
@reflex/navigationowns the pure rules and port controller. - React Router binding:
@reflex/react-routerreports focus for existing routes; apps/web proves live CLI/MCP control without Effect. - Expo binding:
@reflex/expoprojects core navigation into Expo Router.
Behavior is declared once; validation, JSON Schema, availability and input generators
derive from it. From examples/inventory/src/features/inventory-detail.ts:
SetQuantity: action.when("editing").reduce({
input: Schema.Struct({ quantity: Quantity }),
reducer: ({ quantity }, state) => ({ ...state, quantity }),
}),A journey drives the app through the real protocol, with inferred inputs and state. From
examples/inventory/test/journey.test.ts:
import { createTestAppPool } from "@reflex/test"
import app from "@reflex/example-inventory/scenarios.ts"
import { InventoryList, InventoryDetail } from "@reflex/example-inventory/screens.ts"
const pool = createTestAppPool()
const session = await pool.open(app, { scenario: "inventory-with-products" })
const list = await session.focused(InventoryList, { _tag: "ready" })
await list.actions.OpenProduct({ productId: "product-123" })
const detail = await session.focused(InventoryDetail, { _tag: "editing" })
await detail.actions.SetQuantity({ quantity: 12 })
await detail.actions.Save()
await pool.disposeAll()- Architecture: the map, the runtime flows and the rules. Read this first.
- Adopting in an existing app: Zustand, Standard Schema and selected screens without Effect.
- Development: set up, run, test, debug and make common changes.
- Domain: what nodes, operations, sessions, cursors and the rest mean.
- Decisions: why it is built this way.
- Roadmap: what is not built yet.
- Security: the trust model.
You need Bun 1.4.4 on macOS, Linux or Windows. See the PowerShell notes for JSON arguments and environment variables.
$ bun install --frozen-lockfile
$ bun install --frozen-lockfile --cwd apps/mobile
$ bun install --frozen-lockfile --cwd apps/web
$ bun run check
$ bun run reflex start examples/inventory/src/scenarios.ts
$ bun run reflex do OpenProduct '{"productId":"product-123"}'
$ bun run reflex ls
$ bun run reflex stopThis is an experimental workspace to clone, not a set of published npm packages: every package is private, at version 0.0.0, and exports its TypeScript sources directly.
The original design's milestones are built: the headless core, introspection and the CLI, navigation and journey tests, the live Expo bridge, and the MCP adapter. Evidence and its limits are in Development; what is still to do is in the roadmap. It has not run on iOS or on a physical phone.
The live counter runs in a plain Bun process, with no React, React Native, Expo, Effect or store library:
bun run reflex --target device start
REFLEX_BRIDGE='ws://127.0.0.1:8790#<printed-token>' bun examples/live-counter/src/serve.ts
# In another terminal:
bun run reflex --target device tree
bun run reflex --target device do Increment
bun run reflex --target device wait '{"name":"Counter","match":{"count":1}}'
bun run reflex --target device reset
bun run reflex --target device stopdevice is the existing target name for any bridged app, including a server process.
React apps bind a real app with createReflex(app) from @reflex/react. Expo and
React Router use createReflexExpo and createReflexRouter. Their bound hooks infer
contracts and scenario names. Custom host adapters use createRouteAdapter from @reflex/react/advanced.