What is Crux?

Crux is an open-source TypeScript toolkit for the parts of an AI feature that live around the model call.

You still choose your SDK, provider, model, app framework, and runtime. Crux helps with the things that usually grow messy around that call: shared instructions, changing context, memory, retrieval, tools, safety rules, routing, quality checks, and debugging.

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

const classify = prompt({
  id: 'classify',
  input: z.object({ text: z.string() }),
  output: z.object({
    sentiment: z.enum(['positive', 'negative', 'neutral']),
  }),
  system: 'Classify the sentiment of the given text.',
  prompt: ({ input }) => input.text,
})

const result = await generate(classify, {
  model: openai('gpt-4o'),
  input: { text: 'This is incredible.' },
})

result.object.sentiment // 'positive' - fully typed

The problem Crux is built for

AI features rarely fail because of one prompt string alone. They fail because the surrounding system changed in a way nobody noticed.

• The model saw stale or irrelevant context.
• A shared instruction drifted in one file but not another.
• A tool became available in a call where it should not have been.
• A fallback model changed the behavior.
• A safety rule caught the output but sensitive data was already sent somewhere else.
• An evaluation passed the final text but missed how the answer was produced.

Crux gives those surrounding pieces names, types, source locations, runtime traces, and tests so you can improve the system itself instead of guessing from the final answer.

How Crux helps

Define the AI parts as code

Prompts, contexts, memory blocks, retrievers, guardrails, routes, and quality suites live in your codebase. They can be typed, reviewed, reused, and changed deliberately.

Compose only what each call needs

Instead of manually joining strings, each prompt declares the blocks it uses. Context can be conditional, prioritized, cached, dropped under budget pressure, or inspected before the model is called.

Keep your SDK

Crux does not ask you to move into a new runtime. It resolves the prompt and surrounding context, then passes the request to the adapter you choose: Vercel AI SDK, OpenAI, Anthropic, Google GenAI, and others.

See what happened

Local devtools show what the model saw, where the pieces came from, which context was included or skipped, which tools were available, and how a run behaved. Production telemetry can flow into OpenTelemetry-compatible systems.

Test the behavior you care about

Quality suites let you keep expectations close to the prompts, retrievers, flows, or app code they protect. The goal is to catch AI regressions before users do: not only "was the answer good?", but "did the system use the right ingredients to produce it?"

When Crux is a good fit

Reach for Crux when:

• You have more than a couple prompts and they share instructions or context.
• You want structured output without JSON.parse and manual casting.
• You need reusable context, memory, retrieval, tools, safety, or routing around model calls.
• You want to compare models or providers without rewriting prompt definitions.
• You need local debugging and repeatable quality checks for AI behavior.

Raw SDK calls are still great for small scripts and simple one-off prompts. Crux starts paying for itself when the surrounding system becomes harder to reason about than the model call.

What to read next