How to use TypeSafe Jev with Claude: a step-by-step guide

# macOS: keep the key in the Keychain. -w with no value makes it ask,
# so the key never lands in your shell history.
security add-generic-password -a "$USER" -s typesafe-api -w

# Make it available to the terminals that start Claude Code
echo 'export TYPESAFE_API_KEY="$(security find-generic-password -s typesafe-api -w)"' >> ~/.zshrc
source ~/.zshrc

# Check it works without printing it
[ -n "$TYPESAFE_API_KEY" ] && echo "key loaded (${#TYPESAFE_API_KEY} characters)"

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

# later, to update
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai

● real run · 28 Sep 2026

$ claude plugin list
  …
  ❯ typesafe@typesafe-ai
    Version: 0.5.7
    Scope: user
    Status: ✔ enabled

#!/usr/bin/env node
// ~/jev-mcp/server.mjs — gives Claude one tool, jev_evaluate. Zero dependencies.
import { execFileSync } from "node:child_process";
import { createInterface } from "node:readline";

const API = "https://api.typesafe.ai/v1/systemone";

function apiKey() {
  if (process.env.TYPESAFE_API_KEY) return process.env.TYPESAFE_API_KEY.trim();
  try {
    // macOS Keychain, so the key never sits in a config file
    return execFileSync("/usr/bin/security", ["find-generic-password", "-s", "typesafe-api", "-w"], {
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
    }).trim();
  } catch {
    return null;
  }
}

const TOOL = {
  name: "jev_evaluate",
  description:
    "Ask TypeSafe's Jev typed questions about some state. noul → probability of yes; " +
    "choice → one option + probabilities + confidence; score → position on 2–10 ordered levels. " +
    "Batch every independent question about the same state into ONE call.",
  inputSchema: {
    type: "object",
    properties: {
      state: { description: "Text, or an object of named fields, to judge." },
      questions: { type: "object", description: "Map of id → {type, instructions, criteria?}." },
      model: { type: "string", description: "Default: jev-latest" },
    },
    required: ["state", "questions"],
  },
};

const fail = (text) => ({ content: [{ type: "text", text }], isError: true });

async function evaluate({ state, questions, model = "jev-latest" }) {
  const key = apiKey();
  if (!key) return fail("No TypeSafe key: set TYPESAFE_API_KEY or add it to the Keychain.");
  const started = Date.now();
  try {
    const res = await fetch(API, {
      method: "POST",
      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
      body: JSON.stringify({ state, questions, model }),
      signal: AbortSignal.timeout(20_000),
    });
    const text = await res.text();
    if (!res.ok) return fail(`TypeSafe HTTP ${res.status}: ${text.slice(0, 500)}`);
    const body = { ...JSON.parse(text), latency_ms: Date.now() - started };
    return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
  } catch (err) {
    return fail(`TypeSafe request failed: ${err.message}`);
  }
}

// MCP over stdio: one JSON-RPC message per line in, one per line out.
const send = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...msg }) + "\n");

createInterface({ input: process.stdin }).on("line", async (line) => {
  if (!line.trim()) return;
  const { id, method, params } = JSON.parse(line);
  if (method === "initialize") {
    return send({
      id,
      result: {
        protocolVersion: params?.protocolVersion ?? "2025-06-18",
        capabilities: { tools: {} },
        serverInfo: { name: "jev", version: "1.0.0" },
      },
    });
  }
  if (method === "tools/list") return send({ id, result: { tools: [TOOL] } });
  if (method === "tools/call") return send({ id, result: await evaluate(params?.arguments ?? {}) });
  if (method === "ping") return send({ id, result: {} });
  if (id !== undefined) send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
});

mkdir -p ~/jev-mcp            # then save server.mjs there
claude mcp add --scope user jev -- node ~/jev-mcp/server.mjs
claude mcp get jev

● real run · 28 Sep 2026

$ claude mcp get jev
jev:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: stdio
  Command: /opt/homebrew/bin/node
  Args: ~/jev-mcp/server.mjs
  Environment:

{
  "mcpServers": {
    "jev": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/Users/you/jev-mcp/server.mjs"]
    }
  }
}

● real run · 28 Sep 2026

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"jev","version":"1.0.0"}}}
→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"jev_evaluate", … }]}}
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"jev_evaluate","arguments":{
    "state":"Can you please send me the invoice again? I cannot find it.",
    "questions":{"billing":{"type":"noul","instructions":"Is this message about billing or invoices?"}}}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{ \"model\": \"jev-1.13.0\",
    \"answers\": { \"billing\": { \"type\": \"noul\", \"noul\": 0.99 } },
    \"usage\": { \"input_tokens\": 288, \"output_tokens\": 20 }, \"latency_ms\": 865 }"}]}}

#!/usr/bin/env node
// .claude/hooks/jev-bash-guard.mjs — a PreToolUse hook for Bash.
// Asks Jev whether a command is destructive. It can only ADD a confirmation
// step; it never approves anything, and it stays silent whenever Jev can't help.

const DESTRUCTIVE = 0.7; // probability that the command is hard to undo
const BLAST = 1.5; // 0 = nothing lost … 2 = a whole project or remote system
const UNSURE = 0.5; // blast-radius confidence below this means "Jev can't tell"

let raw = "";
for await (const chunk of process.stdin) raw += chunk;
const command = JSON.parse(raw).tool_input?.command ?? "";
const key = process.env.TYPESAFE_API_KEY;
if (!key || !command) process.exit(0); // fail open: normal permission rules apply

const questions = {
  destructive: {
    type: "noul",
    instructions:
      "Would running `command` delete or overwrite files, data, git history or cloud resources in a way that is hard to undo?",
    criteria: {
      true: "Deletes, overwrites, force-pushes, resets or drops something that may not be recoverable",
      false: "Reads, builds, tests, or makes changes that are easy to undo",
    },
  },
  blast_radius: {
    type: "score",
    instructions: "If `command` did the wrong thing, how much could be lost?",
    criteria: [
      "Nothing, or only a temporary file",
      "Some uncommitted local work",
      "A whole project, repository, database or remote system",
    ],
  },
};

try {
  const res = await fetch("https://api.typesafe.ai/v1/systemone", {
    method: "POST",
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: JSON.stringify({ model: "jev-1.13.0", state: { tool: "Bash", command }, questions }),
    signal: AbortSignal.timeout(3_000),
  });
  if (!res.ok) process.exit(0);
  const { answers } = await res.json();
  const p = answers.destructive.noul;
  const blast = answers.blast_radius;
  const risky = p >= DESTRUCTIVE || blast.score >= BLAST || (p >= 0.4 && blast.confidence < UNSURE);
  if (risky) {
    const reason =
      `Jev: destructive ${p.toFixed(2)}, blast radius ${blast.score.toFixed(2)}/2 ` +
      `(confidence ${blast.confidence.toFixed(2)}). Check what this deletes before allowing it.`;
    console.log(
      JSON.stringify({
        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: reason },
      }),
    );
  }
} catch {
  // timeout or network error: say nothing
}
process.exit(0);

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/jev-bash-guard.mjs",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

● real run · 28 Sep 2026

$ echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf ~/projects/shop-api && git push --force origin main"}}' | node jev-bash-guard.mjs
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Jev: destructive 0.96, blast radius 1.99/2 (confidence 0.98). Check what this deletes before allowing it."}}

$ echo '{"tool_name":"Bash","tool_input":{"command":"git reset --hard origin/main && git clean -fdx"}}' | node jev-bash-guard.mjs
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Jev: destructive 0.89, blast radius 1.29/2 (confidence 0.55). Check what this deletes before allowing it."}}

$ echo '{"tool_name":"Bash","tool_input":{"command":"npm test -- --run src/lib"}}' | node jev-bash-guard.mjs
                                                  (silence: no decision, normal rules apply)

$ echo '{"tool_input":{"command":"rm -rf /"}}' | TYPESAFE_API_KEY= node jev-bash-guard.mjs
                                                  (silence: no key, so the hook fails open)

● real run · 28 Sep 2026

> /jev-check hey claude hope you're doing well!! so basically I was wondering if you could
  maybe fix the login bug when you get a chance, and also update the readme, and also maybe
  clean up by deleting the old migrations folder. thanks so much, you're the best!!

Secret scan: clean. Sent to TypeSafe for review.

Prompt: ~63 tokens (249 chars) · model jev-1.13.0

Filler:        a lot (2.33/3) → cut pleasantries/restatements; state the task once
Excess paste:  no (0.02)
Structure:     multiple_tasks → Several unrelated tasks. Split them, or number them in priority order.
Destructive:   yes (0.89) → expect a confirmation step; name exactly what may be removed
Injected instr: no (0.05)

TypeSafe usage: 858 input tokens

● real run · 28 Sep 2026

{
  "model": "jev-1.13.0",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "order_status",
      "confidence": 1,
      "probabilities": { "product_question": 0, "other": 0, "order_status": 1, "refund_or_return": 0 }
    },
    "needs_written_reply": { "type": "noul", "noul": 0.28 },
    "complexity": {
      "type": "score",
      "score": 0.18,
      "confidence": 0.73,
      "legend": {
        "0": "A standard lookup or procedure",
        "1": "Needs some judgment or several steps",
        "2": "Unusual situation, dispute or escalation"
      },
      "probabilities": { "0": 0.83, "1": 0.16, "2": 0.01 }
    },
    "angry": { "type": "noul", "noul": 0.06 }
  },
  "usage": { "input_tokens": 522, "output_tokens": 101 },
  "latency_ms": 464
}

// support/router.ts — Jev decides; code routes; Claude writes only when needed.
import Anthropic from "@anthropic-ai/sdk";
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";

// null when the key is missing: routing is an optimisation, never a dependency
const jev = process.env.TYPESAFE_API_KEY
  ? new TypeSafeClient({ timeout: 4_000, retry: { maxRetries: 1 } })
  : null;
const claude = new Anthropic();

// Every question and threshold in one place, so a person can review them.
export const QUESTIONS = {
  intent: choice("What does the customer in `message` want?", {
    order_status: "Where an existing order is, or when it will arrive",
    refund_or_return: "Money back, a return or an exchange",
    product_question: "A question about a product before or after buying",
    other: "Anything else, including greetings and off-topic chat",
  }),
  needs_written_reply: noul(
    "Does answering `message` need a thoughtful written reply, rather than a status lookup that code can fill in from a database?",
  ),
  complexity: score("How hard is `message` to resolve?", [
    "A standard lookup or procedure",
    "Needs some judgment or several steps",
    "Unusual situation, dispute or escalation",
  ]),
  angry: noul("Is the customer in `message` angry, using hostile or strongly negative language?"),
};
const SURE = 0.8;
const HARD = 1.5;
const ANGRY = 0.7;

const SYSTEM = "You are the support assistant for an online shop. Be warm, specific and brief.";

export async function handle(message: string) {
  const judged = jev
    ? await jev
        .systemOne({ model: "jev-1.13.0", state: { message }, questions: QUESTIONS })
        .catch(() => null) // a Jev failure must not cost the customer a reply
    : null;

  if (judged) {
    const { intent, needs_written_reply, complexity, angry } = judged.answers;

    // 1. Easy and certain: plain code, no Claude call at all.
    if (intent.choice === "order_status" && intent.confidence >= SURE && needs_written_reply.noul < 0.5) {
      return { route: "code", reply: await orderStatusReply(message) };
    }

    // 2. Hard or heated: Claude drafts, a person approves.
    const notes =
      `Router notes (from Jev ${judged.model}): intent=${intent.choice} (confidence ${intent.confidence.toFixed(2)}), ` +
      `complexity=${complexity.score.toFixed(2)}/2, angry=${angry.noul.toFixed(2)}.`;
    if (complexity.score > HARD || angry.noul > ANGRY) {
      return { route: "human-review", draft: await askClaude(message, notes) };
    }
    return { route: "claude", reply: await askClaude(message, notes) };
  }

  // 3. No key, a timeout or an error: exactly the behaviour before Jev.
  return { route: "claude", reply: await askClaude(message) };
}

async function askClaude(message: string, notes?: string) {
  const response = await claude.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    // The system prompt never changes, so prompt caching keeps working;
    // Jev's notes travel in the user turn instead.
    system: SYSTEM,
    messages: [{ role: "user", content: notes ? `${notes}\n\nCustomer message:\n${message}` : message }],
  });
  return response.content
    .filter((b): b is Anthropic.TextBlock => b.type === "text")
    .map((b) => b.text)
    .join("");
}

async function orderStatusReply(message: string) {
  // Your own code: find the order number with a regex, look it up, fill a template.
  const order = /#?(\d{4,})/.exec(message)?.[1];
  return order ? `Order #${order} is with the courier. Tracking: https://example.com/t/${order}` : "Could you share your order number?";
}

# support/verify.py — Claude drafts, Jev checks, code decides.
import anthropic
from typesafe_sdk import Noul, NoulCriteria, Score, TypeSafeClient

claude = anthropic.Anthropic()
jev = TypeSafeClient(timeout=4.0)

CHECKS = {
    "promises_beyond_policy": Noul(
        instructions="Does `draft_reply` promise something that `policy` does not allow, such as a faster timeline or a credit?"
    ),
    "claims_completed": Noul(
        instructions=(
            "Does `draft_reply` tell the customer that an action listed as false in `facts` has already "
            "been completed? Describing an action as in progress or upcoming is not claiming it is completed."
        ),
        criteria=NoulCriteria(
            true="Says, for example, that the refund has been issued or processed when `facts.refund_issued` is false",
            false="Only says what is confirmed, what is in progress, or what will happen next",
        ),
    ),
    "tone": Score(
        instructions="How does `draft_reply` sound to an upset customer?",
        criteria=[
            "Cold, defensive or dismissive",
            "Polite but generic",
            "Warm, specific and takes responsibility",
        ],
    ),
}
BROKEN = 0.5  # a policy or fact check above this fails the draft
WARM_ENOUGH = 1.0  # tone must reach at least "polite"


def check(draft: str, policy: str, facts: dict) -> list[str]:
    """Return the names of the checks the draft fails (empty list = safe to send)."""
    r = jev.system_one(
        state={"policy": policy, "facts": facts, "draft_reply": draft},
        questions=CHECKS,
        model="jev-1.13.0",
    )
    failed = [k for k in ("promises_beyond_policy", "claims_completed") if r.answers[k].noul > BROKEN]
    if r.answers["tone"].score < WARM_ENOUGH:
        failed.append("tone")
    return failed


def draft(model: str, customer: str, policy: str, facts: dict, fix: list[str] | None = None) -> str:
    note = f"\nYour last draft failed these checks: {', '.join(fix)}. Fix them." if fix else ""
    msg = claude.messages.create(
        model=model,
        max_tokens=1024,
        system=f"You write replies for a support team. Follow this policy exactly: {policy}",
        messages=[{"role": "user", "content": f"Facts: {facts}\n\nCustomer: {customer}{note}"}],
    )
    return "".join(b.text for b in msg.content if b.type == "text")


def reply(customer: str, policy: str, facts: dict) -> tuple[str, str]:
    text = draft("claude-haiku-4-5", customer, policy, facts)  # fast first draft
    failed = check(text, policy, facts)
    if not failed:
        return "send", text
    text = draft("claude-sonnet-5", customer, policy, facts, fix=failed)  # stronger redraft
    if not check(text, policy, facts):
        return "send", text
    return "human-review", text  # still failing: a person decides

// agent/ask-jev-tool.ts — let Claude decide when a quick typed judgment helps.
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { noul, TypeSafeClient } from "@typesafe-ai/sdk";
import { z } from "zod";

const claude = new Anthropic();
const jev = new TypeSafeClient({ timeout: 4_000 });

const askJev = betaZodTool({
  name: "ask_jev",
  description:
    "Ask a fast calibrated judgment model yes/no questions about one piece of text. " +
    "Returns the probability that each statement is true. Use it to triage many items " +
    "quickly; 0.5 means the model cannot tell, not 'half true'.",
  inputSchema: z.object({
    text: z.string().describe("The text to judge"),
    statements: z.array(z.string()).min(1).max(20).describe("Each a yes/no statement about the text"),
  }),
  run: async ({ text, statements }) => {
    const questions = Object.fromEntries(statements.map((s, i) => [`q${i}`, noul(s)]));
    const { answers } = await jev.systemOne({ state: { text }, questions });
    return JSON.stringify(statements.map((s, i) => ({ statement: s, probability: answers[`q${i}`]?.noul })));
  },
});

const final = await claude.beta.messages.toolRunner({
  model: "claude-sonnet-5",
  max_tokens: 16000,
  tools: [askJev],
  messages: [
    {
      role: "user",
      content:
        "Here are 40 app-store reviews (pasted below). Use ask_jev to find the ones that report a crash " +
        "or data loss, then write a short summary for the engineering team.\n\n<reviews>…</reviews>",
    },
  ],
});

console.log(final.content);