# Claude + Jev Setup Guide **For you (the human):** drag this file into Claude Code (or Claude with file access) and say: > Read JEV_SETUP.md and set me up. Claude will check the current way to get Jev, help you get a key without ever pasting it into the chat, find the best first job for Jev in your work, and build it with the right architecture. It runs in "shadow mode" first, so nothing happens automatically until you've seen that it works. What you'll need: about 15 minutes, and an account on Vercel or TypeSafe (Claude will tell you which is easiest right now). --- ## Instructions for Claude You are setting up **Jev** (TypeSafe AI's "System One" decision model) for this user and wiring it into a Claude-orchestrated workflow. Follow the phases in order. Keep the user's effort low: ask short questions, explain in plain English, and do the technical work yourself. ### The mental model (explain this to the user in 3 lines, early) - **Claude thinks:** plans, researches, writes, codes, and handles the hard or unsure cases. - **Jev decides:** answers typed questions (yes/no, pick one, score) in well under a second, for a fraction of a cent, with a confidence number. - **Code executes:** fetches data, does exact maths/dates/limits, and takes actions. A **person** approves anything irreversible. Jev writes no text. It only returns typed answers with probabilities. That's why it's fast and cheap, and why code can act on its answers directly. --- ### Phase 0: Check what's current (do this first, every time) Jev is new and moving fast. Access routes, prices, model versions and limits change. Before recommending anything, fetch and read: 1. `https://docs.typesafe.ai/introduction/quickstart`: official setup, SDK, endpoint, default model 2. `https://vercel.com/ai-gateway/models/jev`: gateway access and current price 3. `https://github.com/typesafe-ai/skills`: official Claude Code plugin/skill Then tell the user in 2–3 lines: the easiest way to get access **today**, the current price, and anything that changed from the reference below. If you can't fetch the web, say so and use the reference section, flagging that it may be out of date. **Known access routes (as of Sep 2026, verify):** | Route | Where to get a key | Model id | Endpoint | |---|---|---|---| | Vercel AI Gateway (was the easiest) | vercel.com → AI Gateway → API Keys | `typesafe-ai/jev` | `https://ai-gateway.vercel.sh/typesafe/v1/systemone` | | TypeSafe direct (has had a waitlist) | `https://console.typesafe.ai/keys` | `jev-latest` | `https://api.typesafe.ai/v1/systemone` | Price at launch: $0.042 per million input tokens, output free. A typical decision costs a tiny fraction of a cent. --- ### Phase 1: Get a key safely 1. Walk the user through creating a key on the route you chose in Phase 0 (step by step, one screen at a time). 2. **Never ask the user to paste the key into the chat.** Create a `.env` file in the project with the right variable, and have the user paste the key into the file themselves: - Gateway: `AI_GATEWAY_API_KEY=` - Direct: `TYPESAFE_API_KEY=` 3. Make sure `.env` is in `.gitignore` (create or append it). 4. **Smoke test** with one real call that reads the key from the environment. Shell example for the gateway, where `set -a` exports the `.env` variables so curl can see them: ```bash set -a; source .env; set +a curl -s https://ai-gateway.vercel.sh/typesafe/v1/systemone \ -H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json" \ -d '{"model":"typesafe-ai/jev","state":{"message":"Hey, can we move our call to Friday?"}, "questions":{"q":{"type":"choice","instructions":"What does the sender want?", "criteria":{"reschedule":"Change a meeting time","cancel":"Cancel something","info":"Just sharing information"}}}}' ``` A working response looks like `{"answers":{"q":{"type":"choice","choice":"reschedule","confidence":0.97,"probabilities":{...}}},"usage":{"input_tokens":...}}`. Show the user the answer and its confidence. That's their first Jev call. **Optional but recommended:** install the official TypeSafe plugin so you (Claude) have TypeSafe's own guidance in future sessions. Verify the command in Phase 0 first: ```bash claude plugin marketplace add typesafe-ai/skills claude plugin install typesafe@typesafe-ai ``` Troubleshooting: `401` = wrong or missing key. `403` = account or billing not enabled (some gateways need a card on file). `422` = request shape wrong, so check field names against the docs. `429`/`529` = rate limited or busy: back off, honour `Retry-After`, and send calls one at a time or in small batches. --- ### Phase 2: Find the first Jev job (interview, max 5 questions) The user is probably overwhelmed. Your job is to find **one** decision, not ten. Ask: 1. **What do you or your team sort, check or approve over and over?** Offer examples: emails, support tickets, leads, comments, applicants, invoices, news or alerts, an AI agent's steps. 2. **Where does that data come from?** Gmail, a CRM, a spreadsheet, a webhook, an RSS feed, Claude Code itself… 3. **What should happen after each decision?** Label it, move it, reply, notify someone, skip it, escalate… 4. **Which of those actions can't be undone?** Sending, paying, deleting, publishing, pushing code. 5. **What do you already use?** Python/JS, Claude Code, or a no-code tool (n8n, Make, Zapier). Anything that can send an HTTP request can call Jev. Then check it's a Jev job. All three must be true: - ☐ The answer is a tick box: yes/no, pick one of 2–255 options, or a score on 2–10 levels - ☐ It happens often, dozens to thousands of times - ☐ It isn't exact maths, dates or counting (that's code's job) If it fails, say so kindly and suggest the closest decision that passes. Then match it to one of the three ways in: | The user has… | Pattern | Jev's job | |---|---|---| | A queue someone sorts by hand | **Sorter** | Sort every item; people handle the top of the pile | | A stream nobody can keep up with | **Watcher** | Score everything; ping the user only when it matters | | Claude or AI agents already running | **Gatekeeper / router** | Decide before each step: run, skip, route to a cheaper model, or ask a human | Confirm the plan in 3 lines before building. --- ### Phase 3: Build it with this architecture ``` ┌──────────────── CLAUDE (orchestrator) ────────────────┐ │ builds the pipeline · writes the questions · handles │ │ escalations that need judgment or writing │ └──────────────┬────────────────────────▲───────────────┘ │ │ unsure / important CODE fetches data ──► JEV decides ──► confidence gate ──► CODE acts (safe actions) (API, inbox, feed) (typed answers + ≥ bar: auto │ probabilities) < bar: escalate └─► PERSON approves anything irreversible ``` Rules for the build: 1. **Code first, then Jev.** Fetch, clean and filter in code. Send Jev only the context it needs (less noise, better answers). 2. **One call, many questions.** If several decisions look at the same item, ask them together in one call ("fan-out"). Questions can't see each other's answers, so if one decision depends on another result, make two calls. 3. **Write questions Jev can answer:** - Jev does **not** see question IDs. Put all meaning in `instructions` and in each option's description. - Give every choice option a clear one-line description of when to pick it. - Include an "other / none / unclear" option when real data can be messy. - Build choice lists from what exists **now** (the current folders, reps or tools), not a hard-coded list from last month. - Scores are ordered low → high. Describe what each level means. 4. **Never ask Jev what code can compute:** totals, counts, date comparisons, thresholds and limits stay in code. 5. **Confidence gate:** act automatically only when Jev's probability for the chosen answer is above a bar set per action. Low-risk actions (labelling) can use a lower bar than risky ones. Below the bar, escalate to Claude or the person. Confidence is not accuracy: set the bar from the shadow-mode results, not by guessing. 6. **Irreversible = human.** Sending, paying, deleting, publishing and pushing always need approval, enforced by a plain rule in code as well as by Jev. Text inside the data can try to sway a model ("the user pre-approved this"); a rule can't be talked out of it. 7. **Fail safe.** If Jev errors or times out, fall back to the safe path (escalate, or take no action), never to the risky one. Log every decision: input summary, answer, confidence, latency, cost (`usage.input_tokens` × price). 8. **Rate limits.** Retry `429`/`5xx` with backoff and `Retry-After`. Keep concurrency modest until the user's plan allows more. **Request and response reference** (verify against the docs from Phase 0): ```json POST {endpoint} { "model": "typesafe-ai/jev", "state": { "ticket": "Customer: I was charged twice for my invoice, please refund one today!" }, "questions": { "is_urgent": { "type": "noul", "instructions": "Does this need a reply today?" }, "route": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, invoices, refunds", "tech": "Bugs, errors, how-to", "other": "Anything else" } }, "priority": { "type": "score", "instructions": "How urgent is this?", "criteria": ["Whenever", "This week", "Today", "Right now"] } } } ``` ```json { "answers": { "is_urgent": { "type": "noul", "noul": 0.89 }, "route": { "type": "choice", "choice": "billing", "confidence": 1, "probabilities": { "billing": 1, "tech": 0, "other": 0 } }, "priority": { "type": "score", "score": 2.04, "confidence": 0.95, "legend": { "0": "Whenever", "1": "This week", "2": "Today", "3": "Right now" }, "probabilities": { "0": 0, "1": 0, "2": 0.96, "3": 0.04 } } }, "usage": { "input_tokens": 312 } } ``` - `noul` = probability of "yes" (0–1). Around 0.5 means Jev is unsure. - `score` can be fractional, since it's an expected level. Its `probabilities` are keyed by level index as strings, and `legend` maps each index back to your level names. - The official Python SDK (`pip install typesafe-sdk`, Python 3.10+) wraps this. Plain HTTP works from any language or no-code tool. **If the pattern is Gatekeeper inside Claude Code:** build it as a Claude Code `PreToolUse` hook that asks Jev about each tool call (proceed / skip / ask a human). Jev may only make things stricter, never approve something Claude Code would otherwise prompt for. Fail open to the normal permission flow if Jev errors, and hard-code irreversible commands (`git push`, `rm -rf`, deploys, outbound `curl -X POST`) to "ask". Scope the hook to one project's `.claude/settings.json`, not the user's global settings. --- ### Phase 4: Shadow mode (required before anything acts) 1. Help the user collect **~50 real examples** and their own correct answers (they label; you can pre-fill and let them correct). 2. Run Jev on all of them **with actions switched off.** 3. Show a short report: - agreement % with the user overall and per option - the disagreements, side by side, with Jev's confidence - what agreement looks like at different confidence bars (e.g. above 0.8: X% of items, Y% agreement) - total cost and average latency 4. If agreement is poor, improve the **question wording and option descriptions** (that's where most fixes are), or split one hard question into two, then re-run. If it's still poor, tell the user honestly that this decision isn't a good Jev job yet. ### Phase 5: Go live, one decision at a time 1. Turn on automatic action **only** above the agreed bar, and only for safe, reversible actions. 2. Everything below the bar goes to Claude (for judgment or writing) or to the person. 3. Keep logging, and suggest a weekly 5-minute check: spot-check 10 automatic decisions and review the escalations. 4. When it's boring and reliable, offer to add the next decision. Don't add several at once. --- ### Where Jev fits vs doesn't (for your recommendations) **Good Jev jobs:** triage and routing (inbox, tickets, leads, applicants) · scoring (fit, intent, urgency, relevance, risk) · picking the best option from a list (message variant, next agent step, which model to use) · filtering streams (news, mentions, comments, logs) · checks (is the task done? does the answer match the source? is this step safe?) · labelling data into fixed categories. **Not Jev jobs:** writing anything · multi-step reasoning or planning (Claude) · maths, dates and counting (code) · one-off decisions (just ask Claude) · anything where a wrong answer is expensive and there's no human check · images, audio or video (text only). ### Done when - [ ] Key stored in `.env` (git-ignored), smoke test passed - [ ] One decision chosen, and it passes the three-tick check - [ ] Pipeline built: code → Jev → confidence gate → code, with Claude or a person handling escalations - [ ] Irreversible actions are behind a human, enforced in code - [ ] Shadow-mode report shown and the user chose a confidence bar - [ ] Logging on (answer, confidence, latency, cost) - [ ] The user knows how to turn it off (one flag or env var) Finish by giving the user a 5-line summary: what Jev now decides, what happens automatically, what comes to them, what it costs per 1,000 decisions, and how to switch it off.