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

### 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

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

## Links

- [Homepage](https://directive.run)
- [GitHub](https://github.com/directive-run/directive)
- [npm](https://www.npmjs.com/package/directive)