Directive

The constraint-driven runtime for TypeScript. Declare what must be true. The runtime makes it happen.

• Constraint-Driven Resolution – declare requirements, resolvers fulfill them automatically with retry, batching, and error boundaries
• AI Guardrails – prompt injection detection, PII redaction, cost tracking, multi-agent orchestration with 4 LLM adapters (zero SDK dependencies)
• Auto-Tracking Derivations – computed values that track their own dependencies, no manual dep arrays
• Typed Inbound Sources – declare external event streams (Supabase, WebSocket, polling, browser events) as first-class module fields; engine owns the subscription lifecycle
• 5 Framework Adapters + 1 Vanilla – React, Vue, Svelte, Solid, Lit, plus el() for plain DOM – from a single state layer
• Zero Runtime Dependencies – nothing to audit, nothing to break
• Time-Travel Debugging – snapshot, rewind, replay, export/import system state

---

---

How It Works

Other state libraries react to what happened. Directive enforces what must be true.

// Traditional: describe HOW to change state
dispatch({ type: 'FETCH_USER', id: 123 });
// then write a thunk, saga, or effect to handle it...

// Directive: declare WHAT must be true
constraints: {
  needsUser: {
    when: (facts) => facts.userId > 0 && !facts.user,
    require: { type: "FETCH_USER" },
  },
}
// The runtime handles when, how, retry, and error recovery.

Set userId = 123 and the constraint fires, the resolver fetches the user, and the system settles – automatically.

---

Quick Start

npm install @directive-run/core

import { createModule, createSystem, t, type ModuleSchema } from '@directive-run/core';

const userModule = createModule("user", {
  schema: {
    facts: {
      userId: t.number(),
      user: t.object<{ id: number; name: string } | null>(),
    },
    derivations: { isLoggedIn: t.boolean() },
    events: {},
    requirements: { FETCH_USER: {} },
  } satisfies ModuleSchema,

  init: (facts) => {
    facts.userId = 0;
    facts.user = null;
  },

  constraints: {
    needsUser: {
      when: (facts) => facts.userId > 0 && facts.user === null,
      require: { type: "FETCH_USER" },
    },
  },

  resolvers: {
    fetchUser: {
      requirement: "FETCH_USER",
      resolve: async (req, context) => {
        const res = await fetch(`/api/users/${context.facts.userId}`);
        context.facts.user = await res.json();
      },
    },
  },

  derive: {
    isLoggedIn: (facts) => facts.user !== null,
  },
});

const system = createSystem({ module: userModule });
system.start();

system.facts.userId = 123;       // Constraint fires automatically
await system.settle();            // Wait for resolution
console.log(system.facts.user);   // { id: 123, name: "John" }

---

AI Guardrails and Orchestration

The same constraint-driven model powers AI agent safety. Guardrails are constraints. Agent runs are resolvers. The runtime enforces them automatically.

npm install @directive-run/ai

import { createAgentOrchestrator } from '@directive-run/ai';
import { createAnthropicAdapter } from '@directive-run/ai/anthropic';

const orchestrator = createAgentOrchestrator({
  agent: {
    name: "assistant",
    model: createAnthropicAdapter({ model: "claude-sonnet-4-5-20250514" }),
    systemPrompt: "You are a helpful assistant.",
  },
  guardrails: {
    input: [promptInjectionGuardrail(), piiGuardrail()],
    output: [contentModerationGuardrail()],
  },
  budget: { maxTotalCost: 1.00 },
});

• 4 LLM adapters – OpenAI, Anthropic, Ollama, Gemini (pure fetch, zero SDK deps)
• Built-in guardrails – PII redaction, prompt injection, content moderation, rate limiting
• Multi-agent patterns – parallel, sequential, supervisor, debate, DAG, goal-driven
• Cost tracking + budget enforcement – per-agent and per-system limits
• Streaming with backpressure – real-time token streaming with inline constraint evaluation

AI Documentation →

---

AI tooling: your assistant speaks Directive

Directive ships its own knowledge to your AI assistant, so generated code is idiomatic on the first try.

In Claude Code — two commands install the plugin (12 model-invoked skills):

/plugin marketplace add directive-run/directive
/plugin install directive@directive-plugins

In Cursor, Copilot, Windsurf, Cline, or OpenAI Codex — one command generates the rules file each assistant expects:

npx directive ai-rules init

For LLM agents that crawl docs at runtime — point at directive.run/llms.txt for the comparison framing + full sitemap.

The knowledge ships from a single source (@directive-run/knowledge). See the IDE Integration guide for the decision tree across all install paths.

---

React Integration

npm install @directive-run/react

import { useFact, useDerived } from '@directive-run/react';

function UserProfile({ system }) {
  const user = useFact(system, "user");
  const isLoggedIn = useDerived(system, "isLoggedIn");

  if (!isLoggedIn) return <p>Please log in</p>;
  return <p>Hello, {user?.name}!</p>;
}

Framework Support

Framework	Package	Style
React	@directive-run/react	Hooks with useSyncExternalStore
Vue	@directive-run/vue	Composables with reactive refs
Svelte	@directive-run/svelte	Stores with $ syntax
Solid	@directive-run/solid	Signals with fine-grained reactivity
Lit	@directive-run/lit	Reactive Controllers for Web Components

---

Why Directive?

	Redux	Zustand	XState	Directive
Constraint-driven resolution				Yes
Auto-tracking derivations				Yes
AI guardrails + orchestration				Yes
Retry, batching, error boundaries	Manual	Manual	Manual	Built-in
Time-travel debugging	Extension		Partial	Built-in
Framework-agnostic (6 adapters)	React only	React only	Any	Any
Zero runtime dependencies		Yes		Yes
explain() – why does this state exist?				Yes

---

Packages

Package	Description
@directive-run/core	Core runtime – modules, systems, plugins, testing
@directive-run/react	React hooks (useFact, useDerived, useSelector, etc.)
@directive-run/vue	Vue composables with reactive refs
@directive-run/svelte	Svelte stores with $ syntax
@directive-run/solid	Solid signals with fine-grained reactivity
@directive-run/lit	Lit reactive controllers
@directive-run/ai	AI orchestration, guardrails, multi-agent
@directive-run/el	Vanilla DOM adapter (el(), JSX, htm)
@directive-run/query	Declarative data fetching with causal cache invalidation
@directive-run/cli	directive CLI – init, new, rules, tune, and more
@directive-run/mutator	Transactional fact mutations with rollback
@directive-run/optimistic	Optimistic UI updates layered over Directive systems
@directive-run/timeline	Time-travel debugging panel
@directive-run/vite-plugin-api-proxy	Vite dev-server proxy for AI providers (CORS + key handling)
@directive-run/knowledge	Knowledge files consumed by AI assistants and editors
@directive-run/claude-plugin	Claude Code plugin – 12 skills built from the knowledge package

Documentation

• Getting Started
• Core Concepts
• AI Guardrails
• API Reference
• Examples
• Pricing

Contributing

See CONTRIBUTING.md for development setup and architecture overview. A CLA signature is required for all contributions.

License

MIT OR Apache-2.0 – your choice.