Caracara Score

Initial setup for the web app now includes Clerk authentication, Convex wiring, Clerk-to-Convex auth bridging, and the first protected frontend route.

What is implemented

• Clerk provider wired into apps/web/app/layout.tsx
• Convex client provider wired through apps/web/components/convex-client-provider.tsx
• Clerk route protection in apps/web/proxy.ts
• Clerk prebuilt auth screens in apps/web/app/sign-in/[[...sign-in]]/page.tsx and apps/web/app/sign-up/[[...sign-up]]/page.tsx
• Convex auth configuration in apps/web/convex/auth.config.ts
• A first authenticated Convex query in apps/web/convex/users.ts
• A protected placeholder projects page in apps/web/app/projects/page.tsx

Requirements

• Node.js 24 (24.15 or newer). This is the version used for validation and on Vercel. engines also allows ^22.22.2 and >=26, but those are untested.
• pnpm 12.15.0, pinned in packageManager. Global pnpm 9 and 10 cannot read the lockfile.

Node 24 ships Corepack, which runs the pinned pnpm:

corepack pnpm install --frozen-lockfile

The root scripts (dev, lint, typecheck, test, build) run through Turborepo, which looks for a pnpm binary on PATH. Put Corepack's pnpm shim on PATH once, then use pnpm as usual:

corepack enable pnpm   # writes pnpm/pnpx shims next to the active Node 24 binary
# or keep the shims elsewhere:
# corepack enable pnpm --install-directory <directory already on PATH>

Vercel builds use the same route (see apps/web/vercel.json).

Manual Clerk flow

1. Create a Clerk application for the web app.
2. Enable the sign-in methods you want for v1.
3. Put the Clerk publishable key and secret key into apps/web/.env.local.
4. In Clerk, open JWT Templates and create a new template from the Convex preset, or use Clerk's Convex integration flow if you already enabled it there.
5. Keep the template name as convex. The frontend bridge uses that template name when requesting a token for Convex.
6. Copy the Clerk Frontend API URL and store it as CLERK_FRONTEND_API_URL in apps/web/.env.local.

For local development the Frontend API URL is typically a https://...clerk.accounts.dev URL. Convex uses that URL as the auth provider domain.

Manual Convex flow

1. From the repo root, start the Convex setup flow:

pnpm --filter web convex:dev

2. Log in to Convex in the browser if prompted.
3. Create or select the development deployment for apps/web.
4. Let Convex write CONVEX_DEPLOYMENT, NEXT_PUBLIC_CONVEX_URL, and NEXT_PUBLIC_CONVEX_SITE_URL into apps/web/.env.local.
5. Set the Clerk Frontend API URL on the Convex development deployment:

pnpm --filter web exec convex env set CLERK_FRONTEND_API_URL "$CLERK_FRONTEND_API_URL"

6. Keep pnpm --filter web convex:dev running in one terminal so Convex continues to push function changes and regenerate types once the deployment is connected.

Run locally

After the manual setup above is complete, you can run everything from the repo root:

pnpm dev

That starts both:

• web#dev for Next.js
• web#convex:dev for Convex

Install the CLI

Build the caracara CLI from this checkout and install it globally:

pnpm install:cli

The script runs a frozen install, builds the CLI, and deploys its production files to ~/.local/share/caracara/cli/<commit> (or $XDG_DATA_HOME/caracara/cli/<commit>) with a BUILD-INFO.json. It then points caracara/cli/current at that deployment and runs npm install -g on it (npm resolves the symlink, so the global link follows the commit directory; current is a convenience pointer). Pass --target <dir> to deploy into an empty directory instead (without updating current), or --skip-global to skip the global npm install. Codex runs need the Codex CLI installed separately; see Codex model configuration.

Local CLI secrets

caracara init creates .caracara/secrets.env with owner-only permissions and adds it to .caracara/.gitignore. Put project-specific credentials there using names that start with CARACARA_SECRET_:

[email protected]
CARACARA_SECRET_PASSWORD=replace-me

caracara run loads the nearest project secrets automatically and makes them available only to the selected local runner. Project and scenario prompts may refer to the variable names, but must never contain their values. The CLI redacts exact secret values from runner errors and submitted result text. The local agent may still receive a secret in model context when it reads the value to enter it into the application under test.

Target environments

Define any number of named application targets in .caracara/config.json:

{
  "environments": {
    "development": "http://localhost:3000",
    "preview": "https://preview.example.com",
    "production": "https://app.example.com"
  },
  "defaultEnvironment": "development"
}

A plain caracara run uses defaultEnvironment. Override it for one run with caracara run --environment preview or CARACARA_ENVIRONMENT=preview caracara run. Environment names are lowercase slugs. Target URLs must use HTTP or HTTPS and must not contain credentials; keep credentials in .caracara/secrets.env.

Run caracara environments:list to print every configured environment and mark the default.

Each run stores the selected environment and normalized target URL so the web app can label and filter run history without changing older results when the local config changes. Runs created by older CLIs appear as untracked.

Codex model configuration

Set the Codex model and reasoning effort in .caracara/config.json:

{
  "runner": "codex",
  "model": "gpt-5.6-luna",
  "model_reasoning_effort": "low"
}

Both settings are optional. Without them, Codex uses its own configuration. You can also set them with caracara init --model <model> --model-reasoning-effort <effort>.

Caracara runs the Codex CLI installed on your machine: the codex executable on PATH, or the file named by CARACARA_CODEX_PATH. Install it with npm install -g @openai/codex; Caracara supports version 0.164.0 or newer and prints a warning for older versions. Updating codex updates the runtime Caracara uses. Codex uses your existing local Codex login, and Caracara starts a fresh Codex thread for each scenario while sharing one run-scoped browser session.

When Codex marks a check as failed, it captures a WebP screenshot through Chrome DevTools. The CLI validates and uploads the screenshot before submitting the completed result. Run deletion also removes the stored screenshots.

CLI scenario authoring

The logged-in CLI can update the selected project directly:

caracara addPhase --name "Checkout"
caracara createScenario --name "Complete checkout" --instructions "Buy one item."
caracara addCheck --scenario complete-checkout --name "Receipt" --expectation "The receipt is visible."
caracara updateCheck --scenario complete-checkout --check "Receipt" --expectation "The receipt shows VAT."

The complete mutation set is addPhase, editPhase, removePhase, createScenario, updateScenario, addCheck, removeCheck, and updateCheck. Phase references accept an ID, order, or exact name. Check references accept an ID or exact name. Commands print one JSON result and fail if a name is ambiguous.

Authoring commands update live records immediately and have no version, proposal, activation-delay, or undo workflow. The server rejects phase and scenario writes while the project has a running run.

Verify the flow

1. Visit / and confirm the signed-out shell renders.
2. Open /sign-in or /sign-up and complete authentication with Clerk's prebuilt UI.
3. Confirm the post-login redirect lands on /projects.
4. Confirm /projects shows identity data returned by the Convex query.
5. Sign out from the UserButton and confirm /projects is protected again.

Notes

• pnpm --filter web lint passes.
• pnpm --filter web typecheck passes.
• Convex code generation is not fully active yet because it needs a real deployment connection first. The frontend currently uses makeFunctionReference("users:viewer") so the auth flow can be completed before convex dev has generated convex/_generated/api.
• For production, repeat the same CLERK_FRONTEND_API_URL setup on the Convex production deployment and set the corresponding Clerk and NEXT_PUBLIC_CONVEX_SITE_URL env vars in Vercel.