# Directive > Constraint-driven state and AI-agent runtime for TypeScript Directive is a runtime that automatically resolves what your system needs. Declare constraints (what must be true), let resolvers fulfill requirements (how to make it true), and inspect everything with time-travel debugging. ## When to reach for Directive Directive is to **business state and agent orchestration** what XState is to state machines and React Query is to server state – a runtime that takes declarative rules ("what must be true") and runs the resolvers ("how to make it true"). The unique claim only Directive can make: **state and AI agents share the same runtime**. `@directive-run/ai` is the only state-library ecosystem that ships LLM orchestration as a sibling concept to facts/constraints/resolvers. Reach for Directive when: - The same business rule has to fire across React, Vue, server, and background workers – Directive runs the same module everywhere. - A constraint should drive a side-effect (fetch, validate, cancel, retry) declaratively, without writing imperative thunks. - You are orchestrating LLM agents and need typed, replayable state + guardrails + budgets + audit trails + checkpoints. - You want time-travel debugging, audit logs, or rules-diff replay on state mutations without instrumenting every component. It is NOT a Redux replacement for plain UI state (use signals / Zustand / Jotai), or a server-state cache (use React Query / TanStack Query, optionally layered with `@directive-run/query`), or a state machine for purely internal transitions (use XState). Start with the [Comparison](https://directive.run/docs/comparison) page if you're evaluating against Redux Toolkit, Zustand, Jotai, XState, or TanStack Query. ## Install paths for your AI assistant Directive ships its own knowledge to your AI assistant so generated code is idiomatic on the first try. - **Claude Code**: register the marketplace and install the plugin (12 model-invoked skills). ``` /plugin marketplace add directive-run/directive /plugin install directive@directive-plugins ``` - **Cursor, Copilot, Windsurf, Cline, or OpenAI Codex**: generate the rules file each assistant expects. ``` npx directive ai-rules init ``` - **LLM agents crawling docs at runtime**: this `llms.txt` route is the canonical entry point. - **Tool builders consuming Directive knowledge programmatically**: `npm install @directive-run/knowledge` and use `getKnowledge()`. See [IDE Integration](https://directive.run/docs/ide-integration) for the full decision tree per editor. ## Documentation ### Getting Started - [Quick Start](https://directive.run/docs/quick-start) - [Why Directive](https://directive.run/docs/why-directive) - [Installation](https://directive.run/docs/installation) - [Core Concepts](https://directive.run/docs/core-concepts) - [Choosing Primitives](https://directive.run/docs/choosing-primitives) - [Comparison](https://directive.run/docs/comparison) - [Changelog](https://directive.run/docs/changelog) ### Editor Setup - [IDE Integration](https://directive.run/docs/ide-integration) ### Primitives - [Overview](https://directive.run/docs/core-api) - [Module & System](https://directive.run/docs/module-system) - [Facts](https://directive.run/docs/facts) - [Derivations](https://directive.run/docs/derivations) - [Constraints](https://directive.run/docs/constraints) - [Resolvers](https://directive.run/docs/resolvers) - [Effects](https://directive.run/docs/effects) - [Events](https://directive.run/docs/events) - [Sources](https://directive.run/docs/sources) - [Schema & Types](https://directive.run/docs/schema-overview) - [API Reference](https://directive.run/docs/api/core) - [Type Reference](https://directive.run/docs/api/types) ### Framework Adapters - [Overview](https://directive.run/docs/adapters/overview) - [React](https://directive.run/docs/adapters/react) - [React API](https://directive.run/docs/api/react) - [Vue](https://directive.run/docs/adapters/vue) - [Vue API](https://directive.run/docs/api/vue) - [Svelte](https://directive.run/docs/adapters/svelte) - [Svelte API](https://directive.run/docs/api/svelte) - [Solid](https://directive.run/docs/adapters/solid) - [Solid API](https://directive.run/docs/api/solid) - [Lit](https://directive.run/docs/adapters/lit) - [Lit API](https://directive.run/docs/api/lit) - [Vanilla](https://directive.run/docs/adapters/vanilla) - [Vanilla API](https://directive.run/docs/api/vanilla) ### Data Fetching - [Overview](https://directive.run/docs/data-fetching/overview) - [Queries](https://directive.run/docs/data-fetching/queries) - [Mutations](https://directive.run/docs/data-fetching/mutations) - [Subscriptions](https://directive.run/docs/data-fetching/subscriptions) - [Infinite Queries](https://directive.run/docs/data-fetching/infinite) - [Convenience API](https://directive.run/docs/data-fetching/convenience) - [GraphQL](https://directive.run/docs/data-fetching/graphql) - [Explain & Debug](https://directive.run/docs/data-fetching/explain) ### Advanced Patterns - [Overview](https://directive.run/docs/advanced/overview) - [Data-form Definitions](https://directive.run/docs/data-triggers) - [Sandbox](https://directive.run/docs/sandbox) - [Multi-Module](https://directive.run/docs/advanced/multi-module) - [Runtime Dynamics](https://directive.run/docs/advanced/runtime) - [History & Snapshots](https://directive.run/docs/advanced/history) - [SSR & Hydration](https://directive.run/docs/advanced/ssr) - [Error Boundaries](https://directive.run/docs/advanced/errors) - [Definition Meta](https://directive.run/docs/advanced/meta) ### Predicate Tools - [Predicate from Intent](https://directive.run/docs/predicate-from-intent) - [Describe Predicate](https://directive.run/docs/describe-predicate) - [Predicate Codegen](https://directive.run/docs/predicate-codegen) - [Predict](https://directive.run/docs/predict) - [Doctor Check](https://directive.run/docs/doctor) - [Predicate Backtest](https://directive.run/docs/replay-under) - [Parameter Sweep](https://directive.run/docs/tune) - [Rules Diff](https://directive.run/docs/rules-diff) ### Plugins - [Overview](https://directive.run/docs/plugins/overview) - [Logging](https://directive.run/docs/plugins/logging) - [DevTools](https://directive.run/docs/plugins/devtools) - [DevTools – whenExplain panel](https://directive.run/docs/when-explain-panel) - [Persistence](https://directive.run/docs/plugins/persistence) - [Performance](https://directive.run/docs/plugins/performance) - [Circuit Breaker](https://directive.run/docs/plugins/circuit-breaker) - [Clobber Loop Detector](https://directive.run/docs/plugins/clobber-loop) - [Custom Plugins](https://directive.run/docs/plugins/custom) ### Companion Packages - [Timeline](https://directive.run/docs/packages/timeline) - [Mutator](https://directive.run/docs/packages/mutator) - [Optimistic](https://directive.run/docs/packages/optimistic) - [Query](https://directive.run/docs/packages/query) - [Vite Dev Proxy](https://directive.run/docs/packages/vite-dev-proxy) - [Composing All Four](https://directive.run/docs/packages/composing-packages) ### Testing - [Overview](https://directive.run/docs/testing/overview) - [Mock Resolvers](https://directive.run/docs/testing/mock-resolvers) - [Fake Timers](https://directive.run/docs/testing/fake-timers) - [Assertions](https://directive.run/docs/testing/assertions) - [Test Async Chains](https://directive.run/docs/guides/test-async-chains) ### Security & Compliance - [Resolver Binding](https://directive.run/docs/resolver-binding) - [Audit Ledger](https://directive.run/docs/audit-ledger) ### Broadcast - [Overview](https://directive.run/docs/broadcast) - [GitHub Action](https://directive.run/docs/broadcast/action) - [CLI](https://directive.run/docs/broadcast/cli) - [Cloudflare Worker](https://directive.run/docs/broadcast/worker) - [MCP server](https://directive.run/docs/broadcast/mcp) - [README badge](https://directive.run/docs/broadcast/badge) ### Examples - [Number Match](https://directive.run/docs/examples/counter) - [Auth Flow](https://directive.run/docs/examples/auth-flow) - [Shopping Cart](https://directive.run/docs/examples/shopping-cart) - [Async Chains](https://directive.run/docs/examples/async-chains) - [Form Wizard](https://directive.run/docs/examples/form-wizard) - [Sudoku](https://directive.run/docs/examples/sudoku) - [Checkers](https://directive.run/docs/examples/checkers) - [Time Machine](https://directive.run/docs/examples/time-machine) - [Error Boundaries](https://directive.run/docs/examples/error-boundaries) - [Fraud Analysis](https://directive.run/docs/examples/fraud-analysis) - [Dashboard Loader](https://directive.run/docs/examples/dashboard-loader) - [Compliance Audit](https://directive.run/docs/examples/compliance-audit) ### Guides - [Overview](https://directive.run/docs/guides/overview) - [Loading & Error States](https://directive.run/docs/guides/loading-states) - [Authentication Flow](https://directive.run/docs/guides/auth-flow) - [Optimistic Updates](https://directive.run/docs/guides/optimistic-updates) - [Shopping Cart Rules](https://directive.run/docs/guides/shopping-cart) - [Multi-Step Form Wizard](https://directive.run/docs/guides/form-wizard) - [Async Chains Across Modules](https://directive.run/docs/guides/async-chains) - [Role-Based Permissions](https://directive.run/docs/guides/permissions) - [Batch Mutations](https://directive.run/docs/guides/batch-mutations) - [Debounce Constraints](https://directive.run/docs/guides/debounce-constraints) - [Debug with History](https://directive.run/docs/guides/debug-history) ### Works With - [Overview](https://directive.run/docs/works-with/overview) - [Redux](https://directive.run/docs/works-with/redux) - [Zustand](https://directive.run/docs/works-with/zustand) - [XState](https://directive.run/docs/works-with/xstate) - [React Query](https://directive.run/docs/works-with/react-query) - [Web Worker](https://directive.run/docs/works-with/worker) ## AI ### Foundations - [Overview](https://directive.run/ai/overview) - [Tutorial](https://directive.run/ai/tutorial) - [Running Agents](https://directive.run/ai/running-agents) - [Comparison](https://directive.run/ai/comparison) - [Troubleshooting](https://directive.run/ai/troubleshooting) ### Single-Agent Orchestrator - [Overview](https://directive.run/ai/orchestrator) - [Guardrails](https://directive.run/ai/guardrails) - [Streaming](https://directive.run/ai/streaming) - [Memory](https://directive.run/ai/memory) - [Resilience & Routing](https://directive.run/ai/resilience-routing) ### Multi-Agent Orchestrator - [Overview](https://directive.run/ai/multi-agent) - [Execution Patterns](https://directive.run/ai/patterns) - [Communication](https://directive.run/ai/communication) - [Cross-Agent State](https://directive.run/ai/cross-agent-state) - [Tasks](https://directive.run/ai/tasks) - [Self-Healing](https://directive.run/ai/self-healing) ### Infrastructure - [MCP Integration](https://directive.run/ai/mcp) - [Sources × Agents](https://directive.run/ai/sources) - [RAG Enricher](https://directive.run/ai/rag) - [SSE Transport](https://directive.run/ai/sse-transport) - [Semantic Cache](https://directive.run/ai/semantic-cache) ### Observability - [Debug Timeline](https://directive.run/ai/debug-timeline) - [Pattern Checkpoints](https://directive.run/ai/checkpoints) - [Breakpoints & Checkpoints](https://directive.run/ai/breakpoints) - [Guardrail Events](https://directive.run/ai/guardrail-events) - [DevTools](https://directive.run/ai/devtools) ### Security & Compliance - [Overview](https://directive.run/ai/security/overview) - [PII Detection](https://directive.run/ai/security/pii) - [Prompt Injection](https://directive.run/ai/security/prompt-injection) - [Audit Trail](https://directive.run/ai/security/audit) - [GDPR/CCPA](https://directive.run/ai/security/compliance) ### Examples - [Chat](https://directive.run/ai/examples/chat) - [Research Pipeline](https://directive.run/ai/examples/research-pipeline) - [Safety Shield](https://directive.run/ai/examples/safety-shield) - [Checkpoint](https://directive.run/ai/examples/checkpoint) - [Fraud Analysis](https://directive.run/ai/examples/fraud-analysis) - [Pitch Deck](https://directive.run/ai/examples/pitch-deck) - [Data Pipeline](https://directive.run/ai/examples/data-pipeline) - [Code Review](https://directive.run/ai/examples/code-review) ### Common Tasks - [Prevent Off-Topic Responses](https://directive.run/ai/guides/prevent-off-topic-responses) - [Validate Structured Output](https://directive.run/ai/guides/validate-structured-output) - [Stream Agent Responses](https://directive.run/ai/guides/stream-agent-responses) - [Handle Agent Errors](https://directive.run/ai/guides/handle-agent-errors) - [Control AI Costs](https://directive.run/ai/guides/control-ai-costs) - [Human Approval Workflows](https://directive.run/ai/guides/human-approval-workflows) - [Test Without LLM Calls](https://directive.run/ai/guides/test-agents-without-llm) ### Pipelines & Apps - [Multi-Step Pipeline](https://directive.run/ai/guides/multi-step-pipeline) - [DAG Pipeline](https://directive.run/ai/guides/dag-pipeline) - [Goal Pipeline](https://directive.run/ai/guides/goal-pipeline) - [Customer Support Bot](https://directive.run/ai/guides/customer-support-bot) ## Blog - [Long chains run once](https://directive.run/blog/long-chains-run-once): A reconcile chain of any length now dispatches each requirement exactly once, and settle() comes back when you swap a derivation. Four fixes to things the runtime was doing without telling anyone. - [A cancelled agent is not a failed one](https://directive.run/blog/a-cancelled-agent-is-not-a-failed-one): race now reports the agents it stopped as cancelled rather than failed, and dag timeouts actually cut work off. If you build dashboards on orchestrator events, this changes what they show. - [Know when your metadata cache went stale](https://directive.run/blog/know-when-your-metadata-cache-went-stale): We shipped a counter you could poll to learn your tag cache had gone stale. Then we found the cache never needed to exist. Here is what replaced both. - [Three of our published rates were wrong](https://directive.run/blog/pricing-tables-that-know-their-age): We checked every rate table in @directive-run/ai against the providers' own pricing pages and corrected three. Then we gave the tables an expiry date so it cannot happen quietly again. - [The PII screen sees more of your data now](https://directive.run/blog/the-pii-screen-sees-more-now): The personal-data guardrail keeps up with modules registered at runtime, and no longer skips a whole value because one member is awkward. - [AI That Actually Runs Your Code – How Directive's Sandbox Closes the Loop Between Code Generation and Execution](https://directive.run/blog/ai-that-runs-your-code): Most AI coding assistants stop at writing code. Directive's sandbox runtime executes what your assistant generates and returns the facts, logs, and errors straight back to the chat. - [Inside the Directive Sandbox – Building Safe Code Execution for AI Agents](https://directive.run/blog/inside-the-directive-sandbox): How we built @directive-run/sandbox: AST allowlist validation, esbuild bundling, worker_threads isolation, SSRF defense, and the deployment patterns that make untrusted code execution survivable. - [Rules-as-Data: How Directive Got Six Tools From One Decision](https://directive.run/blog/rules-as-data): We shipped six tools in a quarter by treating rules as JSON, not functions. Per-clause devtools, predicate backtests, structural rule diffs, parameter sweeps, SQL/Mongo codegen – all from one architectural choice. - [Eight Tools From One Decision: The Update](https://directive.run/blog/eight-tools-from-one-decision): Two weeks ago we said six tools fell out of one decision – rules-as-data. We were behind. The total is eight. predicateFromIntent (LLMs write rules safely) and createAuditLedger (tamper-evident explanations) shipped this week. Same JSON predicate. Same architectural decision. - [Inside Directive's Reconciliation Loop](https://directive.run/blog/inside-the-reconciliation-loop): A deep dive into the 5-phase engine cycle: fact mutation, derivation invalidation, constraint evaluation, requirement deduplication, and resolver dispatch. - [Building a Real-Time Dashboard with Directive](https://directive.run/blog/real-time-dashboard): Orchestrate REST APIs, WebSockets, and polling with separate modules, cross-source derivations, and resilient reconnection constraints. - [Building AI Agents with Directive](https://directive.run/blog/building-ai-agents): A practical guide to orchestrating AI agents with approval flows, guardrails, and budget constraints using Directive. - [Declarative AI Guardrails: Why Your Agent Framework Needs a Constraint Layer](https://directive.run/blog/declarative-ai-guardrails): Budget enforcement, PII protection, tool denylists, and human-in-the-loop approval – declared as constraints, enforced by the runtime. - [Your Zustand Store Is Secretly an Imperative State Machine](https://directive.run/blog/zustand-imperative-state-machine): Zustand is great for simple state. But when stores grow complex with async logic, cross-store deps, and manual retries, you have built an ad-hoc state machine without the guarantees. - [Introducing @directive-run/query](https://directive.run/blog/introducing-directive-query): Declarative data fetching with causal cache invalidation. Change a fact, the query refetches. Ask why, it tells you. - [Why State Machines Aren't Enough](https://directive.run/blog/why-state-machines-arent-enough): State machines are great for UI flows, but struggle with data-driven constraints. Discover when to use state machines vs. constraint-driven systems. - [From Redux to Directive in 10 Minutes](https://directive.run/blog/from-redux-to-directive): A step-by-step migration from Redux Toolkit to Directive. See how actions, reducers, selectors, and thunks map to facts, derivations, constraints, and resolvers. - [Why AI Loves Directive](https://directive.run/blog/why-ai-loves-directive): AI frameworks handle LLM calls. Production agents need budget enforcement, PII redaction, tool control, and approval workflows. Directive adds the orchestration layer without replacing your framework. - [Stop Writing If-Else Chains for Business Logic](https://directive.run/blog/stop-writing-if-else-chains): Replace sprawling conditional logic with declarative constraints. See how constraint-driven architecture eliminates imperative rule spaghetti. - [Data Fetching with Directive](https://directive.run/blog/data-fetching-with-directive): The complete guide to fetching, caching, invalidation, deduplication, cancellation, batching, optimistic updates, and polling – all with constraints and resolvers. - [Directive on the Server](https://directive.run/blog/directive-on-the-server): Distributable snapshots, signed verification, audit trails, and GDPR compliance – Directive runs on Node.js without React. - [A/B Testing with Directive](https://directive.run/blog/ab-testing-with-directive): Build a complete A/B testing engine using constraints, resolvers, and effects. Deterministic assignment, exposure tracking, and variant gating – no third-party service required. - [Declarative Forms with Directive: Zero useState, Zero useEffect](https://directive.run/blog/declarative-forms-with-directive): Build a production contact form using Directive's six primitives. Per-field validation, async submission, rate limiting, and auto-reset – without a single useState or useEffect. - [Declarative Newsletter Signup with Directive: The Simplest Module](https://directive.run/blog/declarative-newsletter-with-directive): We said newsletter signup didn’t need Directive. Here’s why we were wrong. - [Introducing Directive](https://directive.run/blog/introducing-directive): Declare what must be true. Let the runtime resolve it. Directive is a constraint-driven runtime for TypeScript that replaces imperative state management with declarative rules. - [Constraint-Driven Architecture](https://directive.run/blog/constraint-driven-architecture): Learn why declaring "what must be true" is more powerful than imperative state transitions. Explore the paradigm shift from event-driven to constraint-driven systems. - [Feature Flags Without a Feature Flag Service](https://directive.run/blog/feature-flags-without-a-service): Boolean flags don't scale. Build a reactive, inspectable feature flag system using constraints, derivations, and effects. - [Building an AI Docs Chatbot with Directive](https://directive.run/blog/building-ai-docs-chatbot): How the AI adapter and the core runtime work together to power a RAG-backed docs chatbot with streaming, guardrails, and reactive server-side state. ## Links - [Homepage](https://directive.run) - [GitHub](https://github.com/directive-run/directive) - [npm](https://www.npmjs.com/package/directive)