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, managed history, request planning, memory, plans, tasks, 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, workspace AssetStore, server boundaries, Agent bridge, and swarm component | Your backend is Convex |
@use-crux/upstash | Upstash SearchStore and Redis RecordStore adapters | You need managed 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, SearchStore, AssetStore, storage, inMemoryStorage |
@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, SearchStore handles dense, sparse, and lexical retrieval search, and AssetStore holds workspace bytes.
// Convex
import {
convexRecordStore,
convexStorage,
convexAssetStore,
} from "@use-crux/convex";
// Upstash Vector + Redis
import { upstashRedisRecordStore, upstashSearchStore } 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