Getting Started

ContextChef solves the most common context engineering problems in AI agent development: conversations too long for the model to remember, too many tools causing hallucinations, having to rewrite prompts when switching providers, and state drift in long-running tasks. It doesn't take over your control flow — it just compiles your state into an optimal payload before each LLM call.

Packages

Package	Description
@context-chef/core	Core context compiler — history compression, tool pruning, memory, VFS offloading, multi-provider adapters
@context-chef/ai-sdk-middleware	Vercel AI SDK middleware — drop-in context engineering with zero code changes
@context-chef/tanstack-ai	TanStack AI middleware — compression, truncation, and dynamic state via ChatMiddleware

Installation

npm install @context-chef/core zod

Quick Start

import { ContextChef } from "@context-chef/core";
import { z } from "zod";

const TaskSchema = z.object({
  activeFile: z.string(),
  todo: z.array(z.string()),
});

const chef = new ContextChef({
  janitor: {
    contextWindow: 200000,
    compressionModel: async (msgs) => callGpt4oMini(msgs),
  },
});

const payload = await chef
  .setSystemPrompt([
    {
      role: "system",
      content: "You are an expert coder.",
      _cache_breakpoint: true,
    },
  ])
  .setHistory(conversationHistory)
  .setDynamicState(TaskSchema, {
    activeFile: "auth.ts",
    todo: ["Fix login bug"],
  })
  .withGuardrails({
    enforceXML: { outputTag: "response" },
    prefill: "<thinking>\n1.",
  })
  .compile({ target: "anthropic" });

const response = await anthropic.messages.create(payload);

Zero-config AI SDK integration

If you use the Vercel AI SDK, you can get transparent history compression and tool result truncation with just 2 lines:

import { withContextChef } from '@context-chef/ai-sdk-middleware';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const model = withContextChef(openai('gpt-4o'), {
  contextWindow: 128_000,
  compress: { model: openai('gpt-4o-mini') },
  truncate: { threshold: 5000 },
});

// Everything below stays exactly the same
const result = await generateText({ model, messages, tools });

See the @context-chef/ai-sdk-middleware package page for full documentation.

TanStack AI middleware

If you use TanStack AI, drop in the middleware for transparent context management:

import { contextChefMiddleware } from '@context-chef/tanstack-ai';
import { chat } from '@tanstack/ai';
import { openaiText } from '@tanstack/ai-openai';

const stream = chat({
  adapter: openaiText('gpt-4o'),
  messages,
  middleware: [
    contextChefMiddleware({
      contextWindow: 128_000,
      compress: { adapter: openaiText('gpt-4o-mini') },
      truncate: { threshold: 5000 },
    }),
  ],
});

See the @context-chef/tanstack-ai package page for full documentation.

Core concepts: building the context

For direct control over the compilation pipeline — dynamic state injection, tool namespaces, memory, snapshot/restore — use the core library directly.

new ContextChef(config?)

const chef = new ContextChef({
  vfs?: { threshold?: number, storageDir?: string, maxAge?: number, maxFiles?: number, maxBytes?: number, onVFSEvicted?: (entry, reason) => void },
  janitor?: JanitorConfig,
  pruner?: { strategy?: 'union' | 'intersection' },
  memory?: MemoryConfig,
  transformContext?: (messages: Message[]) => Message[] | Promise<Message[]>,
  onBeforeCompile?: (context: BeforeCompileContext) => string | null | Promise<string | null>,
});

Removed in 4.0 — each has a direct replacement: TokenUtils → estimate / estimateObject, XmlGenerator → objectToXml, AdapterFactory → getAdapter / adapterRegistry, JanitorConfig.onBudgetExceeded → onBeforeCompress. See the migration guide.

chef.setSystemPrompt(messages): this

Sets the static system prompt layer. Cached prefix — should rarely change.

chef.setSystemPrompt([
  {
    role: "system",
    content: "You are an expert coder.",
    _cache_breakpoint: true,
  },
]);

_cache_breakpoint: true tells the Anthropic adapter to inject cache_control: { type: 'ephemeral' }.

chef.setHistory(messages): this

Sets the conversation history. Janitor compresses automatically on compile().

chef.setDynamicState(schema, data, options?): this

Injects Zod-validated state as XML into the context.

const TaskSchema = z.object({
  activeFile: z.string(),
  todo: z.array(z.string()),
});

chef.setDynamicState(TaskSchema, { activeFile: "auth.ts", todo: ["Fix bug"] });
// placement defaults to 'last_user' (injected into the last user message)
// use { placement: 'system' } for a standalone system message

chef.compile(options?): Promise<TargetPayload>

Compiles everything into a provider-ready payload. Triggers Janitor compression. Registered tools are auto-included.

const payload = await chef.compile({ target: "openai" }); // OpenAIPayload
const payload = await chef.compile({ target: "anthropic" }); // AnthropicPayload
const payload = await chef.compile({ target: "gemini" }); // GeminiPayload

Where to go next

• History Compression (Janitor) — the compression pipeline, quality gates, and the v4 pipeline v2
• Tool Management (Pruner) — pruning, blocklists, and the two-layer namespace architecture
• Memory — persistent cross-session key-value memory
• Adapters — input and target adapters for OpenAI / Anthropic / Gemini and beyond

Blog series

1. Why "Compile" Your Context
2. Janitor — Separating Trigger Logic from Compression Policy
3. Pruner — Decoupling Tool Registration from Routing
4. Offloader/VFS — Relocate Information, Don't Destroy It
5. Core Memory — Zero-Cost Reads, Structured Writes
6. Snapshot & Restore — Capture Everything That Determines the Next Compile
7. The Provider Adapter Layer — Let Differences Stop at Compile Time
8. Five Extension Points in the Compile Pipeline

Claude Code skills

ContextChef ships Claude Code Skills that help you integrate the library into your project interactively. Each skill analyzes your existing codebase and generates tailored integration code.

Skill	Description
context-chef-core	Integrate @context-chef/core — full control over compilation pipeline, multi-provider support
context-chef-middleware	Integrate @context-chef/ai-sdk-middleware — drop-in AI SDK middleware, zero code changes

Install only what you need:

# Core library (OpenAI / Anthropic / Gemini direct SDK usage)
npx skills add MyPrototypeWhat/context-chef --skill context-chef-core

# AI SDK middleware (Vercel AI SDK v7+)
npx skills add MyPrototypeWhat/context-chef --skill context-chef-middleware

# All
npx skills add MyPrototypeWhat/context-chef

Then open Claude Code in your project and type /context-chef-core or /context-chef-middleware.