Packages
What each Crux package does and when to install it.
Crux is split into focused packages. Everyone needs @use-crux/core. Pick an adapter for your SDK, then add storage, React hooks, and the local runtime as needed.
You usually do not install every package. Start with @use-crux/core, add the
adapter for your SDK, then add storage, React, local devtools, or telemetry
only when you need them.
Quick reference
| Package | What it does | Install when |
|---|---|---|
@use-crux/core | Prompts, contexts, memory, plans, tasks, compaction, scoring, agents, index contracts, lint contracts, runtime bridge, observability, request-scoped defer() | Always: this is the base |
@use-crux/next | Next.js host wrapper for request-scoped defer() via after() | Next.js App Router / route handlers using inline defer |
@use-crux/react | React provider, hooks, transports, and SSE server helper | You render Crux plans/tasks/memory in React |
@use-crux/ai | Vercel AI SDK adapter (generate, stream), @use-crux/ai/agent, and stream integration for plans/tasks | You use ai / @ai-sdk/* |
@use-crux/openai | OpenAI SDK adapter (createOpenAI) | You use the openai package directly |
@use-crux/google | Google GenAI adapter (createGoogle) | You use @google/genai |
@use-crux/anthropic | Anthropic SDK adapter (createAnthropic) | You use @anthropic-ai/sdk directly |
@use-crux/convex | Convex RecordStore adapter, dense VectorStore adapter, workspace AssetStore, server boundaries, Agent bridge, compaction, swarm component | Your backend is Convex |
@use-crux/upstash | Upstash VectorStore and Redis RecordStore adapters | You need managed vector search or Redis-backed storage |
@use-crux/otel | OpenTelemetry spans for production observability | You need traces in Datadog, Honeycomb, Grafana, etc. |
@use-crux/local | Local Go runtime, dev server, web UI host, TUI, eval runner, index, lint, and trace services | Development and debugging |
@use-crux/devtools | React web devtools UI bundle | Usually installed through @use-crux/local |
@use-crux/core
The base package. Contains all SDK-agnostic primitives, organized into subpath exports:
| Subpath | Exports |
|---|---|
@use-crux/core | prompt, context, createPrompts, createContexts, config, when, match, defer |
@use-crux/core/defer/node | withNodeDefer, createNodeDeferHost for Node HTTP |
@use-crux/core/defer/serverless | withWaitUntilDefer, withAfterDefer, withNamedOnlyDefer, lifetime factories |
@use-crux/core/memory | memory, workingState, episodes, facts, procedures |
@use-crux/core/storage | RecordStore, VectorStore, AssetStore, storage, inMemoryStorage |
@use-crux/core/compaction | createSlidingWindow, createBudgetManager, extractKeyFacts, summarizeMessages |
@use-crux/core/scoring | judge, metrics |
@use-crux/core/agent | agent, blackboard, handoff, delegate, composition factories |
@use-crux/core/flow | flow, signalFlow, cancelFlow, createFlowId |
@use-crux/core/plan | plan, plan handles, plan listing, plan creation tools |
@use-crux/core/tasks | tasks, task, task-ledger handles, task workers, task creation tools |
@use-crux/core/skill | skill.inline, skill.fromRegistry |
@use-crux/core/skill/node | skill.fromFile, fileSkill for Node.js filesystem skill loading |
@use-crux/core/safety | guardrail, constraint, safety plugins |
@use-crux/core/project-index | Project Index contracts and serializers |
@use-crux/core/lint | Authored-graph lint contracts |
@use-crux/core/runtime-bridge | Runtime bridge command-plane contract |
@use-crux/core/eval | evaluate, caseFile, and Eval authoring types |
@use-crux/core/eval/node | runEval and Node coordination |
@use-crux/core/feedback | durable feedback for a canonical run id |
Adapter packages
All adapters run the same Crux prompt and policy layer. OpenAI, Google, and Anthropic are single-turn adapters: Crux owns the tool loop and the adapter translates one provider turn at a time. @use-crux/ai is a loop-owned adapter because the Vercel AI SDK owns the multi-step model/tool loop natively. The public execution shape stays the same either way.
@use-crux/ai and its root transcription operation are portable. Import
@use-crux/ai/transcription/node only when Crux must securely materialize an
HTTPS audio source; portable runtimes should provide bytes, a Blob, or a data
URL instead. Core follows the same explicit split for defer/node,
observability/node, transcription/node, and skill/node.
// Vercel AI SDK
import { generate, stream } from "@use-crux/ai";
// OpenAI SDK
import { createOpenAI } from "@use-crux/openai";
const openai = createOpenAI(client);
await openai.generate(prompt, { model: "gpt-4o", input });
// Anthropic SDK
import { createAnthropic } from "@use-crux/anthropic";
const anthropic = createAnthropic(client);
await anthropic.generate(prompt, { model: "claude-haiku-4-5-20251001", input });
// Google GenAI
import { createGoogle } from "@use-crux/google";
const google = createGoogle(client);
await google.generate(prompt, { model: "gemini-2.5-flash", input });You can use multiple adapters in the same project. Prompts are SDK-agnostic: the same prompt works with any adapter.
Storage packages
Persistent storage is split by capability. RecordStore holds JSON records, VectorStore handles dense/sparse/hybrid search, and AssetStore holds workspace bytes.
// Convex
import {
convexRecordStore,
convexStorage,
convexAssetStore,
} from "@use-crux/convex";
// Upstash Vector + Redis
import { upstashRedisRecordStore, upstashVectorStore } from "@use-crux/upstash";For Convex runtime setup and boundary rules, see the Convex guide.
Plugin packages
// OpenTelemetry
import { withTelemetry } from "@use-crux/otel";
config({
plugins: [withTelemetry({ serviceName: "my-app" })],
});Supports two export paths: standard OTel TracerProvider (Node.js servers) and lightweight HTTP/callback exporters (Lambda, Convex, Cloudflare Workers).
Devtools
// Only when app runtime code should send records to a known server/tunnel
config({
observability: {
serverUrl: process.env.DEVTOOLS_URL,
token: process.env.CRUX_DEVTOOLS_TOKEN,
},
});crux dev # start server + open web UI
crux dev --tui # interactive terminal dashboard
crux traces # list recent traces
crux eval list # list discovered Evals
crux eval # run all Evals
crux eval --offline # exact evidence only; no network
crux eval --plan # inspect admitted work without writesTypical setups
Minimal (prototyping)
pnpm add @use-crux/core @use-crux/ai zodProduction with Convex
pnpm add @use-crux/core @use-crux/react @use-crux/ai @use-crux/convex @use-crux/local @use-crux/otel zodMulti-provider
pnpm add @use-crux/core @use-crux/ai @use-crux/openai @use-crux/google @use-crux/anthropic zod