How to Set Up Jev: API, SDKs and Claude Code Hooks

mkdir -p ~/.config/jev && chmod 700 ~/.config/jev
read -rs JEV_KEY && printf '%s\n' "$JEV_KEY" > ~/.config/jev/key && unset JEV_KEY
chmod 600 ~/.config/jev/key

stat -f '%Lp' ~/.config/jev/key    # on Linux: stat -c '%a' ~/.config/jev/key
head -c 9 ~/.config/jev/key; echo

curl -s https://openrouter.ai/api/alpha/decisions \
  -H "Authorization: Bearer $(cat ~/.config/jev/key)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "The build is green and the diff only changes README.md.",
    "questions": {
      "docs_only": {
        "type": "noul",
        "instructions": "Does the state say the change touches only documentation?"
      }
    }
  }'

{
  "model": "typesafe/jev-1.13-20260917",
  "answers": {
    "docs_only": { "type": "noul", "noul": 0.96 }
  },
  "usage": { "input_tokens": 288, "output_tokens": 21, "cost": 0.000012096 },
  "id": "gen-dec-1793292008-8FZQ0ChPV9wDLAT0V8hi",
  "provider": "TypeSafe"
}

// first-call.mjs: run with `bun first-call.mjs` or `node first-call.mjs`
import { readFileSync } from "node:fs";
import { homedir } from "node:os";
 
const key = process.env.OPENROUTER_API_KEY ?? readFileSync(`${homedir()}/.config/jev/key`, "utf8").trim();
 
const res = await fetch("https://openrouter.ai/api/alpha/decisions", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "typesafe/jev-1.13",
    state: "Deploy failed: the migration timed out after 300 seconds on the orders table.",
    questions: {
      needs_human: { type: "noul", instructions: "Should a human look at this before anyone retries?" },
    },
  }),
  signal: AbortSignal.timeout(8000),
});
if (!res.ok) throw new Error(`Jev HTTP ${res.status}: ${await res.text()}`);
 
const { answers, usage } = await res.json();
console.log(answers.needs_human.noul, usage.cost);

import { OpenRouter } from "@openrouter/sdk";
 
const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
 
const decision = await openrouter.alpha.decisions.create({
  decisionsRequest: {
    model: "typesafe/jev-1.13",
    state: "Deploy failed: the migration timed out after 300 seconds on the orders table.",
    questions: {
      needs_human: { type: "noul", instructions: "Should a human look at this before anyone retries?" },
      area: {
        type: "choice",
        instructions: "Which area does the failure belong to?",
        criteria: { database: "Schema, migrations, queries", network: "DNS, TLS, timeouts between services", code: "Application logic" },
      },
    },
  },
});
 
console.log(JSON.stringify(decision.answers), JSON.stringify(decision.usage));

{"needs_human":{"noul":0.88,"type":"noul"},"area":{"choice":"database","confidence":1,"probabilities":{"database":1,"network":0,"code":0},"type":"choice"}} {"cost":0.000015414,"inputTokens":367,"outputTokens":56}

import os
import requests
 
resp = requests.post(
    "https://openrouter.ai/api/alpha/decisions",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
    json={
        "model": "typesafe/jev-1.13",
        "state": "Deploy failed: the migration timed out after 300 seconds on the orders table.",
        "questions": {"needs_human": {"type": "noul", "instructions": "Should a human look at this before anyone retries?"}},
    },
    timeout=10,
)
resp.raise_for_status()
print(resp.json()["answers"], resp.json()["usage"])

import os
from typesafe_sdk import TypeSafeClient
 
client = TypeSafeClient(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api",
)
 
result = client.system_one(
    model="jev-1.13",
    state="Deploy failed: the migration timed out after 300 seconds on the orders table.",
    questions={"needs_human": {"type": "noul", "instructions": "Should a human look at this before anyone retries?"}},
)
 
print(result.answers["needs_human"])

~/.claude/hooks/jev/
  jev.mjs               shared client
  jev-permission.mjs    PermissionRequest hook
  jev-rule-gate.mjs     PreToolUse hook
  jev-skill-picker.mjs  UserPromptSubmit hook
  register.mjs          adds the three hooks to settings.json
~/.config/jev/
  key                   your OpenRouter key, mode 600
  usage.jsonl           one line per Jev call

// Shared Jev client for the global Claude Code hooks.
// Key lookup: OPENROUTER_API_KEY env var, then ~/.config/jev/key. A missing or placeholder key disables every hook.
// Model: JEV_MODEL env var, default typesafe/jev-1.13.
// JEV_URL is a test seam: point it at a local mock server when testing.
// Every successful call appends one line to ~/.config/jev/usage.jsonl (override with JEV_USAGE_LOG).
import { appendFileSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { basename, join } from "node:path";
 
const PLACEHOLDER = "REPLACE_WITH_OPENROUTER_KEY";
export const MODEL = process.env.JEV_MODEL || "typesafe/jev-1.13";
const JEV_URL = process.env.JEV_URL || "https://openrouter.ai/api/alpha/decisions";
const USAGE_LOG = process.env.JEV_USAGE_LOG || join(homedir(), ".config", "jev", "usage.jsonl");
 
export function loadKey() {
  const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
  if (fromEnv && fromEnv !== PLACEHOLDER) return fromEnv;
  try {
    const fromFile = readFileSync(join(homedir(), ".config", "jev", "key"), "utf8").trim();
    if (fromFile && fromFile !== PLACEHOLDER) return fromFile;
  } catch {
    // No key file: treated as not configured.
  }
  return undefined;
}
 
// Returns the decision response, or throws. Callers treat a throw as "no opinion" and fall through.
export async function decide(state, questions, timeoutMs = 8000) {
  const key = loadKey();
  if (!key) throw new Error("Jev not configured: set ~/.config/jev/key");
  const started = performance.now();
  const res = await fetch(JEV_URL, {
    method: "POST",
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: JSON.stringify({ model: MODEL, state, questions }),
    signal: AbortSignal.timeout(timeoutMs),
  });
  if (!res.ok) {
    await res.body?.cancel();
    throw new Error(`Jev HTTP ${res.status}`);
  }
  const body = await res.json();
  try {
    appendFileSync(USAGE_LOG, JSON.stringify({
      ts: new Date().toISOString(),
      hook: basename(process.argv[1] ?? "unknown"),
      id: body.id,
      model: body.model,
      input_tokens: body.usage?.input_tokens,
      cost: body.usage?.cost,
      ms: Math.round(performance.now() - started),
    }) + "\n");
  } catch {
    // Logging must never break a hook.
  }
  return body;
}
 
// Yes-probability for a noul answer, or undefined when missing or out of range.
export function yesProb(answers, key) {
  const p = answers?.[key]?.noul;
  return typeof p === "number" && p >= 0 && p <= 1 ? p : undefined;
}

// PermissionRequest hook (matcher: Bash). Auto-approves only clearly reversible commands.
// Anything risky, anything unsure, any failure: print nothing, so the normal prompt appears.
// Per-project opt-out: create <project>/.claude/no-jev
import { readFileSync, existsSync } from "node:fs";
import { join } from "node:path";
import { decide, loadKey, yesProb } from "./jev.mjs";
 
// Static list. Matching commands never reach Jev. This list is the security boundary, not the model.
const RISKY = [
  /\brm\s+-\S*[rRf]/,
  /\bgit\s+(push|reset\s+--hard|clean|branch\s+-D)\b/,
  /\b(sudo|doas|su)\b/,
  /\b(npm|pnpm|yarn|bun)\s+publish\b/,
  /\b(deploy|apply|destroy|delete)\b/,
  /\.env\b|\.ssh\b|\.aws\b|credentials/i,
  /\b(bash|sh|zsh|eval|xargs)\b/,
];
 
const input = JSON.parse(readFileSync(0, "utf8"));
const cmd = input?.tool_input?.command;
const cwd = input?.cwd ?? process.cwd();
 
if (!loadKey() || input?.tool_name !== "Bash" || typeof cmd !== "string") process.exit(0);
if (existsSync(join(cwd, ".claude", "no-jev"))) process.exit(0);
if (/\$\(|`|[<>]\(/.test(cmd) || RISKY.some((r) => r.test(cmd))) process.exit(0);
 
// Claude Code sends its own one-line description of the command; it nudges routine commands up a little.
const description = typeof input?.tool_input?.description === "string" ? input.tool_input.description.slice(0, 300) : undefined;
 
try {
  const { answers } = await decide(
    { commands: [cmd], project: cwd, ...(description ? { agent_description: description } : {}) },
    {
      // Explicit true/false criteria: in live tests this scored safe reads 0.95+ and installs, pushes
      // and network calls 0.07 to 0.58. A single-sentence question left even `git status` at 0.75.
      reversible: {
        type: "noul",
        instructions: "Is it safe to run every command in `commands` without asking a human?",
        criteria: {
          true: "The commands only read files, run tests or builds, or change files inside `project` that git can restore.",
          false: "The commands delete or overwrite data outside `project`, push, publish, deploy, install software, change system settings, or send data over the network.",
        },
      },
    },
  );
  if ((yesProb(answers, "reversible") ?? 0) >= 0.9) {
    console.log(JSON.stringify({
      hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "allow" } },
    }));
  }
} catch (err) {
  console.error(`jev-permission: ${err.message}`);
}

printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git status","description":"Show working tree status"},"cwd":"'"$PWD"'"}' \
  | bun ~/.claude/hooks/jev/jev-permission.mjs

{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}

[
  {
    "id": "employee-data-server-only",
    "path": "src/",
    "text": "Employee records are read on the server only. Browser code must never query the employees table or the database directly."
  }
]

// PreToolUse hook (matcher: Edit|Write|MultiEdit). Blocks an edit when Jev is at least 70% sure it breaks a project rule.
// Rules come from <project>/.claude/jev-rules.json. No file, no rules, no cost.
// Failure mode: fail open. The normal flow continues and the error goes to stderr.
import { readFileSync, existsSync } from "node:fs";
import { join } from "node:path";
import { decide, loadKey, yesProb } from "./jev.mjs";
 
const input = JSON.parse(readFileSync(0, "utf8"));
const cwd = input?.cwd ?? process.cwd();
if (!loadKey()) process.exit(0);
 
const rulesPath = join(cwd, ".claude", "jev-rules.json");
if (!existsSync(rulesPath)) process.exit(0);
 
let rules;
try {
  rules = JSON.parse(readFileSync(rulesPath, "utf8"));
} catch (err) {
  console.error(`jev-rule-gate: cannot parse ${rulesPath}: ${err.message}`);
  process.exit(0);
}
 
const toolInput = input?.tool_input ?? {};
const file = toolInput.file_path ?? "";
const proposed = toolInput.content
  ?? toolInput.new_string
  ?? (Array.isArray(toolInput.edits) ? toolInput.edits.map((e) => e.new_string ?? "").join("\n") : "");
const applicable = rules.filter((r) => file.includes(r.path));
if (applicable.length === 0 || proposed === "") process.exit(0);
 
const state = {
  file,
  proposed_change: proposed.slice(0, 20000),
  rules: applicable.map((r) => ({ id: r.id, text: r.text })),
};
const questions = Object.fromEntries(
  applicable.map((r) => [r.id, {
    type: "noul",
    instructions: `Does the code in \`proposed_change\`, written to \`file\`, break this rule: "${r.text}"`,
    criteria: {
      true: "The new code does something the rule forbids.",
      false: "The new code follows the rule, or the rule does not apply to this code.",
    },
  }]),
);
 
// 0.7, not 0.8: in live tests a raw SQL query from browser code scored 0.75 on jev-1.13,
// while edits that respect the rule stayed at or below 0.56.
try {
  const { answers } = await decide(state, questions);
  const broken = applicable.filter((r) => (yesProb(answers, r.id) ?? 0) >= 0.7);
  if (broken.length > 0) {
    const reason = broken.map((r) => `${r.id}: ${r.text}`).join(" | ");
    console.log(JSON.stringify({
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: `Edit blocked by Jev rule check. ${reason}`,
      },
    }));
  }
} catch (err) {
  console.error(`jev-rule-gate: ${err.message}`);
}

PreToolUse:Write hook error: Edit blocked by Jev rule check. employee-data-server-only: Employee records are read on the server only. Browser code must never query the employees table or the database directly.

// UserPromptSubmit hook. Asks Jev which skill fits the prompt, or none, and adds the pick as context.
// Skill sources: ~/.claude/skills (global) and <project>/.claude/skills (project wins on name clash).
// The agent still decides what to do. Failure mode: fail open, no suggestion is added.
import { readFileSync, readdirSync, existsSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { decide, loadKey } from "./jev.mjs";
 
const input = JSON.parse(readFileSync(0, "utf8"));
if (!loadKey()) process.exit(0);
 
const prompt = String(input?.prompt ?? "").slice(0, 4000);
if (prompt.trim().length < 15) process.exit(0); // "yes", "continue" and similar carry no routing signal
const cwd = input?.cwd ?? process.cwd();
 
// Parse name and description from SKILL.md frontmatter. Handles inline values and | or > block scalars.
function parseSkill(text, fallbackName) {
  const m = text.match(/^---\n([\s\S]*?)\n---/);
  if (!m) return null;
  const lines = m[1].split("\n");
  const fields = {};
  for (let i = 0; i < lines.length; i++) {
    const kv = lines[i].match(/^([A-Za-z][\w-]*):\s*(.*)$/);
    if (!kv) continue;
    let value = kv[2].trim();
    if (value === "" || /^[|>][-+]?$/.test(value)) {
      const block = [];
      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) block.push(lines[++i].trim());
      value = block.join(" ");
    }
    fields[kv[1]] = value.replace(/^["']|["']$/g, "");
  }
  return {
    name: fields.name || fallbackName,
    description: (fields.description || "").slice(0, 400),
  };
}
 
function loadSkills(dirs) {
  const byName = new Map();
  for (const dir of dirs) {
    if (!existsSync(dir)) continue;
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      if (!entry.isDirectory()) continue;
      const file = join(dir, entry.name, "SKILL.md");
      if (!existsSync(file)) continue;
      const skill = parseSkill(readFileSync(file, "utf8"), entry.name);
      if (skill && skill.description) byName.set(skill.name, skill);
    }
  }
  return [...byName.values()];
}
 
const skills = loadSkills([join(homedir(), ".claude", "skills"), join(cwd, ".claude", "skills")]);
 
// Prefilter: the 40 skills sharing the most words with the prompt. Choice takes at most 255 options.
const words = new Set(prompt.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
const candidates = skills
  .map((s) => {
    const text = `${s.name} ${s.description}`.toLowerCase();
    return { s, hits: [...words].filter((w) => text.includes(w)).length };
  })
  .filter((x) => x.hits > 0)
  .sort((a, b) => b.hits - a.hits)
  .slice(0, 40)
  .map((x) => x.s);
if (candidates.length === 0) process.exit(0);
 
const criteria = Object.fromEntries(candidates.map((s) => [s.name, s.description]));
criteria.none = "The prompt needs none of these skills.";
 
try {
  const { answers } = await decide(
    { prompt },
    { skill: { type: "choice", instructions: "Which skill should handle this prompt, or none?", criteria } },
  );
  const pick = answers?.skill;
  if (pick?.choice && pick.choice !== "none" && pick.confidence >= 0.8) {
    console.log(JSON.stringify({
      hookSpecificOutput: {
        hookEventName: "UserPromptSubmit",
        additionalContext: `Relevant skill: ${pick.choice}. Load it before acting if it fits.`,
      },
    }));
  }
} catch (err) {
  console.error(`jev-skill-picker: ${err.message}`);
}

// Register the three Jev hooks in ~/.claude/settings.json. Safe to run twice.
// Backs up the file before the first change, appends to existing hook arrays, never removes anything.
import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
 
const path = join(homedir(), ".claude", "settings.json");
const settings = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
const dir = "$HOME/.claude/hooks/jev";
const additions = {
  PermissionRequest: { matcher: "Bash", hooks: [{ type: "command", command: `bun "${dir}/jev-permission.mjs"`, timeout: 15 }] },
  PreToolUse: { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: `bun "${dir}/jev-rule-gate.mjs"`, timeout: 15 }] },
  UserPromptSubmit: { hooks: [{ type: "command", command: `bun "${dir}/jev-skill-picker.mjs"`, timeout: 15 }] },
};
 
settings.hooks ??= {};
let changed = 0;
for (const [event, entry] of Object.entries(additions)) {
  const list = (settings.hooks[event] ??= []);
  if (list.some((e) => e.hooks?.some((h) => String(h.command ?? "").includes("/.claude/hooks/jev/")))) {
    console.log(`${event}: already registered`);
    continue;
  }
  list.push(entry);
  changed += 1;
  console.log(`${event}: added`);
}
 
if (changed > 0) {
  if (existsSync(path)) {
    const backup = `${path}.bak-jev-${Date.now()}`;
    copyFileSync(path, backup);
    console.log(`backup: ${backup}`);
  }
  writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
  JSON.parse(readFileSync(path, "utf8"));
  console.log("settings.json written and re-parsed OK");
}

bun ~/.claude/hooks/jev/register.mjs

PermissionRequest: added
PreToolUse: added
UserPromptSubmit: added
backup: /Users/you/.claude/settings.json.bak-jev-1793292809197
settings.json written and re-parsed OK

// Mock test for the permission gate. No key, no credits. Run: bun test-min.mjs
import { spawn } from "node:child_process";
import { homedir } from "node:os";
import { join } from "node:path";
 
// A fake decisions endpoint that says yes (0.95) to every noul question.
const server = Bun.serve({
  port: 0,
  async fetch(req) {
    const { questions } = await req.json();
    const answers = Object.fromEntries(Object.keys(questions).map((k) => [k, { type: "noul", noul: 0.95 }]));
    return Response.json({ id: "mock", answers, usage: { input_tokens: 0, cost: 0 } });
  },
});
 
// Async spawn on purpose: spawnSync would block this process, so the mock could never answer.
function runHook(file, input) {
  return new Promise((resolve) => {
    const child = spawn("bun", [join(homedir(), ".claude", "hooks", "jev", file)], {
      env: {
        ...process.env,
        OPENROUTER_API_KEY: "sk-test",
        JEV_URL: `http://127.0.0.1:${server.port}`,
        JEV_USAGE_LOG: "/dev/null",
      },
    });
    let out = "";
    child.stdout.on("data", (d) => { out += d; });
    child.on("close", () => resolve(out.trim()));
    child.stdin.end(JSON.stringify(input));
  });
}
 
const status = await runHook("jev-permission.mjs", { tool_name: "Bash", tool_input: { command: "git status" }, cwd: "/tmp" });
const push = await runHook("jev-permission.mjs", { tool_name: "Bash", tool_input: { command: "git push origin main" }, cwd: "/tmp" });
 
console.log(status.includes('"behavior":"allow"') ? "PASS git status is approved" : `FAIL git status: ${status}`);
console.log(push === "" ? "PASS git push stays on the prompt" : `FAIL git push: ${push}`);
server.stop(true);

PASS git status is approved
PASS git push stays on the prompt

jq -s 'group_by(.hook) | map({hook: .[0].hook, calls: length, tokens: (map(.input_tokens) | add), cost: (map(.cost) | add), avg_ms: ((map(.ms) | add) / length | round)})' ~/.config/jev/usage.jsonl