Skip to content
tamesystemsPublic

About

An application control protocol for apps, built on Effect: inspect and drive app behavior headless, live on a device, or over MCP

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Reflex

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.

Why it exists

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.

System at a glance

 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/live connects any JS app to the bridge with a global WebSocket.
  • React bindings: createReflex(app) from @reflex/react binds a Provider and typed hooks without a router dependency.
  • Router-neutral projection: @reflex/navigation owns the pure rules and port controller.
  • React Router binding: @reflex/react-router reports focus for existing routes; apps/web proves live CLI/MCP control without Effect.
  • Expo binding: @reflex/expo projects core navigation into Expo Router.

What it looks like

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()

Start here

Quick start

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 stop

This 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.

Status

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.

License

MIT

Live without a UI framework

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 stop

device 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.

About

An application control protocol for apps, built on Effect: inspect and drive app behavior headless, live on a device, or over MCP

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages