Chef AI App Builder

In Chef apps, the Vite server injects code during development to allow an app running inside an iframe to listen to postMessage messages from its parent Chef window.

The injected code performs two steps:

1. Verifies that the incoming message is from the parent Chef window.
2. Loads a response script from https://chef.convex.dev/scripts/worker.bundled.mjs to handle the message.

This mechanism allows Chef to manage dependencies and updates for the worker script independently of the user's application code.

The Chef repository is organized into several key directories:

• app/: Client-side code and serverless APIs. Includes components/ (UI), lib/ (client-side state syncing), and routes/ (client/server routes).
• chef-agent/: Manages the agentic loop, system prompts, tool definitions, and model provider calls.
• chefshot/: CLI interface for interacting with the Chef webapp.
• convex/: The database schema and functions for storing chats and user metadata.
• template/: The base template used to initialize new Chef projects.
• test-kitchen/: A test harness specifically for the Chef agent loop.

Use the Convex CLI to push your functions to a deployment.

• To see all available commands: npx convex -h
• To launch the documentation: npx convex docs

Run these commands from your project root directory.

To run evaluations using Braintrust, install dependencies with pnpm i and execute the evaluation script using npx braintrust eval. You must provide both BRAINTRUST_API_KEY and ANTHROPIC_API_KEY as environment variables.

pnpm i

BRAINTRUST_API_KEY=<..> ANTHROPIC_API_KEY=<..> npx braintrust eval initialGeneration.eval.ts

To enable authentication for local development, you must create an OAuth application in the Convex dashboard.

1. Go to the Convex dashboard OAuth apps settings.
2. Create a new OAuth application.
3. The team used to create this application is the only team that can sign in to your local Chef instance.
4. Set a Redirect URI (e.g., http://127.0.0.1:5173) to allow form submission.

To run the development environment, you need two separate terminal sessions:

1. Frontend/Vite Server: Run pnpm run dev.
2. Convex Backend: In a second terminal, run npx convex dev.

Important Access Instructions:

• Access the application at http://127.0.0.1:5173.
• Do not use localhost; you must use 127.0.0.1 as the hostname to match the WorkOS application configuration.
• If hot-reloading does not work immediately, manually reload the page.

To run Chef on your local machine, follow these steps to clone the repository, set up the environment, configure OAuth, and deploy the Convex backend.

Note: Chef must be accessed via http://127.0.0.1:{port}/ rather than http://localhost:{port}/ to function correctly. This setup uses the hosted Convex control plane to provision projects, but Chef tokens used in this environment do not count towards your Convex account usage.

# 1. Clone the project
git clone https://github.com/get-convex/chef.git
cd chef

# 2. Set up local environment
nvm install
nvm use
npm install -g pnpm
pnpm i
echo 'VITE_CONVEX_URL=placeholder' >> .env.local
npx convex dev --once

# 6. Run Chef backend and frontend
pnpm run dev

## in another terminal
npx convex dev

Chefshot requires username/password dashboard login credentials to function. It reads these from the following environment variables:

• CHEF_EVAL_USER_PASSWORD
• CHEF_EVAL_USER_EMAIL

You can retrieve these credentials by running npx vercel env pull from the root repository directory.

You can verify these credentials by attempting to log into the Convex dashboard at: https://dashboard.convex.dev/api/auth/login?useEmail=true

The worker script is served from https://chef.convex.dev/scripts/worker.bundled.mjs. Because WebContainers cannot make requests to localhost, you must use a proxy if you are updating this script live during development.

To enable this, you must add the proxy host to the server.allowedHosts configuration in your vite.config.ts file.

Before submitting a Pull Request, run the following commands to ensure code quality and pass the commit queue:

• Linting and Formatting: pnpm run lint:fix
• Tests: pnpm run test
• Typechecking: pnpm run typecheck

If you want to run the Test Kitchen without Braintrust integration, you can run main.ts directly using bun. This requires the ANTHROPIC_API_KEY environment variable.

ANTHROPIC_API_KEY=<..> bun run main.ts

Note: This workflow is intended for Convex employees and is not a supported workflow for external users.

To set up the development environment, follow these steps:

1. Clone the repository.
2. Install the required Node.js version using nvm.
3. Install pnpm globally.
4. Install project dependencies.
5. Link to Vercel and pull environment variables.
6. Configure a placeholder VITE_CONVEX_URL to prevent the Convex CLI from incorrectly using CONVEX_URL as the client environment variable.
7. Configure the existing Convex project to populate environment variables automatically.

git clone git@github.com:get-convex/chef.git
cd chef
nvm install
nvm use
npm install -g pnpm
pnpm i
npx vercel link --scope convex-dev --project chef -y
npx vercel env pull
echo 'VITE_CONVEX_URL=placeholder' >> .env.local
npx convex dev --configure existing --team convex --project chef --once