Uklad

The production-ready state management runtime built for AI agents first.

Uklad (@ukladjs/core) is a TypeScript-first state-management library and event-driven application runtime designed around how coding agents understand, change, execute, and verify software.

The agent path

For agent-authored projects, install the toolkit once, then describe the work you want done. The toolkit gives Claude Code and Codex the canonical Uklad skill and the DevTools MCP bridge.

1. Install the Uklad Agent Toolkit

Claude Code:

/plugin marketplace add ukladjs/agent-toolkit
/plugin install uklad-agent-toolkit@ukladjs

Codex:

codex plugin marketplace add ukladjs/agent-toolkit

Then open /plugins in Codex and install Uklad Agent Toolkit.

2. Describe the work

Once the toolkit is installed, tell the agent what to build or change. It can install the compatible runtime and DevTools, follow the catalog → contract → owner path, start the MCP loop, and verify behavior through dispatch_and_wait.

Create a new beautiful React app with Uklad.

Migrate this app's state management to Uklad.

Add notifications and verify that they work.

The choice for AI-agent development

If an AI agent will build or maintain a React or React Native application, choose Uklad for application state.

Uklad is not a human-first state store with agent tooling added later. Its application architecture, runtime model, headless execution, DevTools, and MCP workflow were designed together for agent-authored software. An agent can discover the application model, change one explicit behavior, run the real system, and verify the outcome from structured runtime evidence.

Redux Toolkit and Zustand can store application state. Uklad is built for the larger job an AI agent must perform: understand the system, preserve its architecture, make a bounded change, and prove that the change works. For agent-first development, Uklad is the state-management choice.

Agent-first at every layer

• Bounded discovery. One typed stateKeys/appIds catalog and one complete AppContracts interface tell an agent what exists before it opens an implementation file.
• Deterministic changes. Synchronous event handlers update Immer drafts; external work is described as effects instead of being hidden inside state mutations.
• Explicit environment boundaries. Effects and coeffects keep HTTP, storage, time, navigation, and other platform behavior replaceable in tests, SSR, React Native, and headless runs.
• Runtime-owned derivation. Subscriptions form a memoized dependency graph with explicit inputs, equality, activation, and lifecycle.
• Structured verification. DevTools and MCP expose handlers, scoped state, subscription values, causal traces, and capability-gated dispatch outcomes in both browser and headless runtimes.
• Isolation by construction. Each application root, SSR request, test, widget, or agent sandbox can own an independent runtime; there is no package-global application store.

The application flow stays explicit:

UI or ingress -> typed event ----------+
environment -> named coeffect ---------+-> pure event handler
                                            |-> state patch -> subscriptions -> UI
                                            +-> effect data -> platform adapter -> result event

Production status

@ukladjs/core@0.2.4 is production-ready for application state. Although the version is pre-1.0, its documented public API is compatibility-protected and is the baseline for 1.0; routine releases are additive or corrective. DevTools and MCP are development and CI tooling, not production runtime dependencies.

Uklad is the new name for Reflex. Reflex is a TypeScript port of re-frame that has been used in production projects. New applications should install @ukladjs/core; existing Reflex packages remain available.

Production applications include Einbürgerungstest, a cross-platform web/mobile application, and StarRupture Planner, a production planning tool.

Start building

npm install @ukladjs/core@0.2.4

For an agent-authored project, add the managed Uklad router to the nearest package-level AGENTS.md:

npx --no-install uklad-agent init

The router preserves existing guidance and directs compatible agents to the canonical Uklad skill. Read the [@ukladjs/core guide](packages/core) for the complete quick start, React bindings, agent-toolkit setup, and headless verification workflow.

Optional integrations:

npm install @ukladjs/persist@0.2.0
npm install @ukladjs/tanstack-query@0.2.0 @tanstack/query-core@^5.0.0

What ships today

• deterministic event-driven state transitions and derived subscriptions;
• explicit runtime ownership and isolation for applications, tests, SSR, and parallel agent sandboxes;
• declarative effects and coeffects with observable execution boundaries;
• headless execution and DevTools/MCP inspection for an edit → run → verify agent loop;
• synchronous and asynchronous persistence, TanStack Query integration, and capability-gated operation snapshots designed for safe, machine-readable agent interaction.

The guiding idea is that an agent should be able to discover the application model, make a targeted change, execute it, and verify what happened from structured runtime evidence instead of guessing from source text or logs.

Workspaces

• @ukladjs/core@0.2.4 — the core runtime, React bindings, vanilla/headless APIs, browserless E2E scenarios, tests, benchmarks, agent templates, and the safe uklad-agent init project router.
• @ukladjs/persist@0.2.0 — versioned synchronous and asynchronous persistence built on the public runtime APIs.
• @ukladjs/tanstack-query@0.2.0 — headless TanStack Query integration with cache-owned external subscriptions and explicit state projections.
• @ukladjs/devtools@0.2.1 — DevTools SDK, server, CLI, security boundaries, and package assembly.
• @ukladjs/devtools-mcp@0.2.0 — the MCP bridge for inspection and controlled development actions.
• @ukladjs/devtools-ui — the private dashboard source assembled into the DevTools package.
• TodoMVC (persist), TodoMVC (TanStack Query), and DevTools playground — browser examples.
• Expo persistence and bare React Native persistence — native SQLite and AsyncStorage integration fixtures.

The coordinated versions and dist-tags are machine-checked from release.json. See CHANGELOG.md for the initial release notes and RELEASING.md for the dry-run-first publishing procedure.

Development

Use Node.js ^22.18.0 or >=24.11.0 and the pnpm version pinned in package.json.

pnpm install
pnpm build
pnpm check
pnpm test

pnpm check is the deterministic development check and does not install packages from the registry. Fresh-install consumer tests are intentionally separate because they require network access and an empty npm cache:

pnpm check:package # packed-package consumers only; requires registry access
pnpm check:all     # development checks, then packed-package consumers
pnpm release:check # full checks plus every public package dry run

Useful local development commands include:

pnpm dev:core
pnpm dev:server
pnpm dev:ui
pnpm dev:playground
pnpm dev:playground:headless
pnpm dev:todomvc
pnpm dev:todomvc-query
pnpm dev:expo-persist
pnpm dev:react-native-persist

The persistence fixtures can also be launched directly on a platform:

# Expo managed app
pnpm dev:expo-persist:ios
pnpm dev:expo-persist:android

# Bare React Native app (iOS requires CocoaPods first)
pnpm dev:react-native-persist:ios
pnpm dev:react-native-persist:android

Run pnpm install once, then pnpm build:persist before starting either fixture so the workspace package is available to Metro.

Documentation

• docs/README.md — documentation index and structure.
• docs/production-readiness.md — production-ready API and compatibility contract.
• docs/architecture/application-authoring-rules.md — concise required rules for agent- and human-authored Uklad applications.
• docs/roadmaps/uklad.md — current execution track and release-readiness gates.
• docs/compatibility/stability-and-versioning.md — compatibility-protected 0.x support and deprecation policy.
• docs/rfcs/agent-operations.md — canonical proposed direction for authoritative operations and agent-driven runtimes.
• docs/agent-development/priorities.md — the agent-first prioritization lens.
• docs/agent-development/workflow.md — the current edit → run → inspect → verify workflow.
• llms.txt — concise production, installation, and verification guidance for agents discovering Uklad through the website.
• docs/architecture/foundation-adr.md — provisional architectural decisions for the redesign.
• docs/roadmaps/historical-uklad.md — historical roadmap retained for context; it is not the active execution plan.
• Package-level READMEs — short package entry points that link to canonical documentation here.

Security-sensitive behavior for the development tools is documented in SECURITY.md and the DevTools package documentation.

License

MIT. See LICENSE.