Getting Started

Crux does not have to become your AI framework. You can start with one typed prompt, add context when the prompt gets hard to reason about, bring in memory or retrieval when the product needs it, and only adopt the full harness story when the system is ready for it.

Pick the problem you are feeling first. Each starting point still leads back to the same shape: define the AI part in code, compose it into the model request, inspect what happened, and test the behavior you care about.

Crux is in alpha. The install commands below are the intended package set for the first public npm alpha; until that release lands, consume Crux from this repository workspace.

Start with the problem in front of you

Prompt strings are spreading

Use typed prompts for inputs, outputs, shared IDs, provider settings, and adapter-safe execution.

Context is hard to control

Use contexts for reusable instructions, conditional inclusion, priority, caching, token budgets, and inspection.

The assistant needs memory

Add working state, episodes, facts, procedures, proposals, or policy memory without changing the model SDK.

Answers need sources

Load, index, sync, retrieve, and ground documents so source-aware context can join the request.

Safety must compose with the call

Use guardrails and constraints for blocking, redaction, transforms, validation, retries, and safer boundaries.

Model choice is becoming policy

Declare routing, cascades, fallback, cost metadata, and provider differences instead of hiding them in call sites.

Regressions are slipping through

Use quality suites, targets, experiments, cassettes, baselines, and feedback records to protect behavior.

You need the whole run explained

Use local devtools and observability to see the request setup, related runtime events, quality results, and source links.

Those starting points are intentionally modular. Starting with prompts does not force you into memory. Starting with retrieval does not force you into a new agent runtime. The value grows because the pieces compose through the same prompt setup and become visible in the same debugging and quality workflow.

Crux can be 5% of your AI system or the organizing layer for the whole model turn. The throughline is the same: keep your SDK, make the setup explicit, and test more than the final text.

Pick your stack

Once you know the first Crux piece you want, choose the walkthrough that matches where your model call runs. Each guide is self-contained.

Next.js

App Router with Server Actions and streaming Route Handlers.

Node.js

Plain Node/TS — scripts, CLIs, background jobs, any backend.

Convex

Run prompts inside Convex actions, persist memory in the crux component.

Expo / React Native

Call prompts from your mobile app via a Node backend.

What you'll install

Every Crux project needs @crux/core plus exactly one adapter for your SDK of choice:

bash npm install @crux/core zod npm install @crux/ai # Vercel AI SDK (most common)

bash pnpm add @crux/core zod pnpm add @crux/ai # Vercel AI SDK (most common)

bash yarn add @crux/core zod yarn add @crux/ai # Vercel AI SDK (most common)

bash bun add @crux/core zod bun add @crux/ai # Vercel AI SDK (most common)

@crux/ai is the Vercel AI SDK adapter. You can also use @crux/openai, @crux/google, or @crux/anthropic directly — pick whichever SDK you already have in the project.

A 30-second taste

If you just want to see the smallest piece in isolation, start with a typed prompt:

hello.ts

import { prompt } from '@crux/core'
import { generate } from '@crux/ai'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

const greet = prompt({
  id: 'greet',
  input: z.object({ name: z.string() }),
  system: 'You are a friendly assistant.',
  prompt: ({ input }) => `Say hello to ${input.name}`,
})

const result = await generate(greet, {
  model: openai('gpt-4o'),
  input: { name: 'World' },
})

console.log(result.text) // string

Set OPENAI_API_KEY in your environment and run it. That's a complete Crux program.

From there, the same prompt can add contexts, memory, retrieval, tools, safety, routing, quality suites, and devtools without rewriting the original model call around a new framework.

How the pieces connect

Crux is most useful when the pieces stop feeling like separate features.

Typed prompts give the model call a stable shape.
Context composition controls what gets added to that shape.
Memory and retrieval contribute state and sources when the task needs them.
Guardrails, constraints, routing, and fallback make important choices explicit.
Quality suites and devtools let you inspect and protect the behavior.

Some of this is shipped today: prompts, contexts, memory, retrieval, guardrails, routing, quality foundations, local devtools, and observability are real. Some of the deeper "why did this happen?" workflow is still in progress: the full turn decision report, richer rationale artifacts, unified freshness vocabulary, and polished harness-decision matchers are active roadmap work.