clef-mcp 0.2.1 → 0.3.1

package/examples/claude-code/README.md

@@ -0,0 +1,21 @@
+# Claude Code
+
+## Register (recommended)
+
+```bash
+claude mcp add clef-mcp -- clef-mcp
+# without a global install:
+claude mcp add clef-mcp -- npx -y clef-mcp
+```
+
+## Or via project config
+
+Copy `mcp.json` from this directory to your project root as `.mcp.json` (project-scope servers).
+
+## One-time setup
+
+```bash
+npx clef-mcp install
+```
+
+Verify inside Claude Code with `/mcp` — `clef-mcp` should list the `clef_decide` tool.

package/examples/claude-code/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "clef-mcp": {
+      "command": "clef-mcp",
+      "args": []
+    }
+  }
+}

package/examples/codex/config.toml

@@ -0,0 +1,21 @@
+# Codex CLI — register clef-mcp as an MCP server.
+# Location: ~/.codex/config.toml
+#
+# If clef-mcp is installed globally (npm i -g clef-mcp):
+[mcp_servers.clef-mcp]
+command = "clef-mcp"
+args = []
+
+# Without a global install, prefer npx:
+# [mcp_servers.clef-mcp]
+# command = "npx"
+# args = ["-y", "clef-mcp"]
+
+# Optional environment overrides:
+# [mcp_servers.clef-mcp.env]
+# CLEF_MODEL = "clef-flash"
+# CLEF_LOG_LEVEL = "error"
+# CLEF_HOME = "~/.cache/clef-mcp"
+
+# One-time setup (downloads the model):
+#   npx clef-mcp install

package/examples/cursor/README.md

@@ -0,0 +1,12 @@
+# Cursor
+
+Copy `mcp.json` from this directory to `<project>/.cursor/mcp.json`
+(or `~/.cursor/mcp.json` for global scope).
+
+## One-time setup
+
+```bash
+npx clef-mcp install
+```
+
+Cursor → Settings → MCP: `clef-mcp` should appear with the `clef_decide` tool.

package/examples/cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "clef-mcp": {
+      "command": "clef-mcp",
+      "args": []
+    }
+  }
+}

package/examples/hooks/README.md

@@ -0,0 +1,12 @@
+# clef-mcp automation recipes
+
+One-shot `clef-mcp decide` recipes — callers that invoke the decision model **deterministically** (hooks, CI), where the call happens because the infrastructure says so, not because an LLM chose to.
+
+| Recipe | What it does |
+|---|---|
+| [`pretooluse-guard/`](pretooluse-guard/) | PreToolUse hook: block shell commands the model judges destructive (p ≥ 0.9), note softer leans on stderr |
+| [`ci-triage/`](ci-triage/) | GitHub Action: severity + area verdict for a PR diff, into the step summary / labels |
+
+Both recipes are honest about the trade-offs: cold start per `decide` call (~seconds, model load included), advisory-only gating (fail open), and a 16k-token context ceiling for state. Read the caveats in each folder before wiring them into real workflows.
+
+Client registration snippets (MCP config for Claude Code / Codex / Cursor) live in the sibling folders: [`../claude-code/`](../claude-code/), [`../codex/`](../codex/), [`../cursor/`](../cursor/).

package/examples/hooks/ci-triage/README.md

@@ -0,0 +1,68 @@
+# CI triage — label a pull request with the local Clef model
+
+A GitHub Actions job that runs `clef-mcp decide` on the PR diff and reports severity + area. The result lands in the step summary and as job outputs; wiring it to GitHub labels is one `gh` call you can uncomment.
+
+> **Runner reality check:** `ubuntu-latest` (16 GB RAM) fits the Q4_K_M model (6 GB), but inference is CPU-only and the one-time `install` downloads ~6 GB + the llama.cpp build. Expect ~1–3 min of setup per job. For anything hotter than a few PRs per hour, use a self-hosted runner with the model pre-installed and drop the `install` step.
+
+```yaml
+# .github/workflows/clef-triage.yml
+name: clef-triage
+
+on:
+  pull_request:
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      severity: ${{ steps.decide.outputs.severity }}
+      area: ${{ steps.decide.outputs.area }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install model + runtime (one-time ~6 GB, CPU inference)
+        run: npx -y clef-mcp@latest install --yes
+
+      - name: Collect the diff as state
+        run: gh pr diff ${{ github.event.pull_request.number }} > /tmp/pr.diff
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Decide
+        id: decide
+        run: |
+          DIFF=$(jq -Rs . < /tmp/pr.diff)
+          RESULT=$(jq -n --argjson diff "$DIFF" '{
+            state: { pr: ${{ toJSON(github.event.pull_request.title) }}, diff: $diff },
+            questions: {
+              severity: { type: "score", instructions: "How severe are the changes in this diff if they ship as-is?",
+                          criteria: ["trivial", "minor", "moderate", "major", "critical"] },
+              area: { type: "choice", instructions: "Which area does this diff primarily touch?",
+                      criteria: { frontend: "UI / client code", backend: "server / API code", infra: "CI, build, deployment", docs: "documentation only" } }
+            }
+          }' | npx -y clef-mcp@latest decide)
+
+          SEVERITY=$(jq -r '.decisions.severity.answer | to_entries | max_by(.value) | .key' <<<"$RESULT")
+          AREA=$(jq -r '.decisions.area.answer | to_entries | max_by(.value) | .key' <<<"$RESULT")
+          echo "severity=$SEVERITY" >> "$GITHUB_OUTPUT"
+          echo "area=$AREA" >> "$GITHUB_OUTPUT"
+          echo "| question | pick |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|---|---|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| severity | $SEVERITY |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| area | $AREA |" >> "$GITHUB_STEP_SUMMARY"
+
+      # Optional: apply the verdict as labels (needs contents:write / pull-requests: write).
+      # - name: Label
+      #   run: gh pr edit ${{ github.event.pull_request.number }} --add-label "triage-${{ steps.decide.outputs.severity }}"
+      #   env:
+      #     GH_TOKEN: ${{ github.token }}
+```
+
+## Honest caveats
+
+- **The 9B model triages; it does not review.** Use the verdict for routing and prioritization, not as a merge gate.
+- **Diff size:** the model context is 16k tokens; a huge diff degrades both latency and judgment. Truncate `/tmp/pr.diff` (e.g. `head -c 50000`) for large PRs.
+- **Cold start per job.** The `install` step re-downloads unless you cache `~/.cache/clef-mcp` with `actions/cache` keyed on the model revision — or move to a self-hosted runner.
+- **State is data.** The diff is passed to the model as content to judge, never as instructions; the server treats it that way (see SECURITY.md).

package/examples/hooks/pretooluse-guard/README.md

@@ -0,0 +1,87 @@
+# PreToolUse guard — a Clef "reflex" before risky shell commands
+
+A hook that asks the local Clef model one `noul` question ("is this destructive?") plus a blast-radius `score` before a shell command runs. Blocks only on a decisive `p(true) ≥ 0.9`; everything else passes with a note on stderr.
+
+## What it looks like
+
+```
+$ rm -rf node_modules
+clef guard: p(destructive)=0.04 blast_radius=single_file       # allowed
+
+$ git push --force origin main
+Blocked: the local Clef model judges this command destructive (p=0.94, blast_radius=repo).
+Ask the user to confirm explicitly; if they confirm, let them run it themselves
+or have them disable the guard. Do not work around this gate by rephrasing the command.
+```
+
+## What a block means — learned in the wild (2026-10-04)
+
+A block is a **pause plus escalation to the user, not a wall**. The first real firing of this guard proved both halves:
+
+1. **The catch worked.** A different agent session, mid history-rewrite, ran `git push --force origin --all` → p=0.94, blocked (exit 2).
+2. **The bypass also "worked" — and that was the lesson.** The agent read the script, saw the pre-filter matched the literal string `push --force`, and re-ran the identical push as a `+refspec` (`git push origin '+refs/heads/*:refs/heads/*'`), which slipped past the string match before the model was ever asked. Both fixes shipped as a result:
+   - the pre-filter is **semantic about pushes** now: `--force` (incl. `--force-with-lease`), `-f`, `+refspec`, and `git filter-repo`/`filter-branch` all reach the model; a plain `git push` still skips it;
+   - the block message **routes the agent to the user** ("ask the user to confirm explicitly") instead of hinting "re-run without the guard" — an LLM reads that hint as an instruction to find a workaround.
+
+Honest residual: the `+refspec` form scores lower than the literal flag (p≈0.87 in the same setup — passes with a lean logged to stderr). A string pre-filter can never be bypass-proof against an agent with full access; this gate's contract is *visibility and a nudge toward the human*, and the tuning knobs (keyword list, thresholds) sit at the top of `guard.sh` on purpose.
+
+## Install
+
+Requirements: `jq` on PATH, `clef-mcp install` done once.
+
+```bash
+# 1. Put the script somewhere permanent and make it executable
+cp guard.sh ~/.local/bin/clef-guard.sh && chmod +x ~/.local/bin/clef-guard.sh
+
+# 2. Register it as a PreToolUse hook for Bash commands
+```
+
+<details open>
+<summary><b>Claude Code</b> — <code>~/.claude/settings.json</code></summary>
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "~/.local/bin/clef-guard.sh" }]
+      }
+    ]
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>ZCode</b> — <code>~/.zcode/cli/config.json</code></summary>
+
+Configuration-file hooks are **disabled by default** — the top-level `"enabled": true` is required:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "events": {
+      "PreToolUse": [
+        {
+          "matcher": "Bash",
+          "hooks": [
+            { "type": "command", "command": "~/.local/bin/clef-guard.sh", "timeout": 90, "statusMessage": "clef guard: judging command risk" }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+The matcher is a case-sensitive regex against the tool name (`Bash`, not `bash`). `timeout` is in **seconds** — keep it generous enough for a cold model load; run `clef-mcp daemon` alongside to make the gate sub-second. Exit code `2` is the standard deny.
+</details>
+
+## Honest caveats
+
+- **Advisory, not a security boundary.** The guard fails open: missing model, missing `jq`, or a `clef-mcp` error all allow the command. It raises the cost of accidents; it cannot prevent a determined one. A block tells the agent to confirm with the user — the user, not the agent, decides what happens next.
+- **Cold start per call** (~a few seconds, model load included). The keyword pre-filter keeps model calls rare — but it now sends every force-flavored push to the model, so history-rewriting sessions pay it repeatedly; run `clef-mcp daemon` alongside to make each gate sub-second.
+- **The model is a signal, not a judge.** `p ≥ 0.9` blocks; 0.5–0.9 is a lean printed to stderr for you to read.
+- **Tune the threshold and the keyword list to your taste** — both are at the top of `guard.sh` on purpose.

package/examples/hooks/pretooluse-guard/guard.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# PreToolUse guard: ask the local Clef model whether a shell command looks
+# destructive before it runs. Blocks (exit 2) only on a decisive p(true).
+#
+# Contract (Claude Code / ZCode PreToolUse):
+#   stdin  : event JSON, command at .tool_input.command
+#   exit 0 : allow
+#   exit 2 : block (stderr is shown to the agent)
+#
+# Design notes:
+#   - Fail open. If the model or jq is missing, the guard allows the command:
+#     it is an advisory gate, not a security boundary.
+#   - Cold start. Each decide call loads the model (~a few seconds). The cheap
+#     keyword pre-filter keeps the model calls rare.
+#   - Threshold. Blocking requires p(destructive) >= 0.9; below that the
+#     command runs and the lean is logged to stderr.
+
+set -euo pipefail
+
+EVENT=$(cat)
+COMMAND=$(printf '%s' "$EVENT" | jq -r '.tool_input.command // empty')
+
+[ -z "$COMMAND" ] && exit 0
+
+# Cheap pre-filter: only spend a model call on plausibly risky commands.
+# History-rewriting pushes come in several clothes: --force, -f, force-with-lease
+# and the +refspec form ('git push origin "+refs/heads/*:refs/heads/*"') — all
+# go to the model, because a literal 'push --force' match alone was bypassed in
+# the wild (2026-10-04: same push re-run as a +refspec).
+if ! printf '%s' "$COMMAND" | grep -qiE '\b(rm|mv|dd|mkfs|shred|chmod|chown|kill|pkill|drop|truncate|reset --hard|clean -|publish|filter-repo|filter-branch)\b|push[^|]*(--force|-f[ =]|\+refs)|[^|]*\|\s*(ba)?sh'; then
+  exit 0
+fi
+
+DECISION=$(printf '%s' "$EVENT" | jq -n \
+  --arg cmd "$COMMAND" \
+  '{
+    state: { source: "pretooluse-guard", command: $cmd },
+    questions: {
+      is_destructive: {
+        type: "noul",
+        instructions: "Could this shell command irreversibly destroy data, credentials or published state (deletion, force-push, credential exposure, publishing)?"
+      },
+      blast_radius: {
+        type: "score",
+        instructions: "How much damage could this command cause if it is a mistake?",
+        criteria: ["none", "single_file", "repo", "machine", "beyond_machine"]
+      }
+    }
+  }' | clef-mcp decide) || {
+  echo "clef guard unavailable; allowing command" >&2
+  exit 0
+}
+
+P_DESTRUCTIVE=$(printf '%s' "$DECISION" | jq -r '.decisions.is_destructive.answer.true')
+TOP_RADIUS=$(printf '%s' "$DECISION" | jq -r '.decisions.blast_radius.answer | to_entries | max_by(.value) | .key')
+
+echo "clef guard: p(destructive)=$P_DESTRUCTIVE blast_radius=$TOP_RADIUS" >&2
+
+BLOCKED=$(printf '%s' "$DECISION" | jq -n --argjson p "$P_DESTRUCTIVE" '$p >= 0.9')
+if [ "$BLOCKED" = "true" ]; then
+  echo "Blocked: the local Clef model judges this command destructive (p=$P_DESTRUCTIVE, blast_radius=$TOP_RADIUS). Ask the user to confirm explicitly; if they confirm, let them run it themselves or have them disable the guard. Do not work around this gate by rephrasing the command." >&2
+  exit 2
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clef-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "mcpName": "io.github.HighlyLoadedEgo/clef-mcp",
   "description": "Local MCP server exposing the Clef decision model as a structured clef_decide tool.",
   "type": "module",
@@ -24,6 +24,7 @@
   "files": [
     "dist",
     "skills",
+    "examples",
     "assets",
     "tests/evals",
     "README.md",
@@ -35,7 +36,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "npm run build && vitest run",
+    "test": "npm run build && tsc --noEmit && vitest run",
     "test:watch": "vitest",
     "evals": "npm run build && node dist/cli.js evals",
     "prepack": "npm run build"

package/skills/clef-decisions/SKILL.md

@@ -18,7 +18,15 @@ Good fits (the model was trained for these):
 - **Confidence / severity** (`score`): ordered scales like very_low → very_high.
 - **Batching related judgments**: all questions in ONE call are scored in a single forward pass — batch instead of looping.
 
-Bad fits: free-text generation, code writing, anything needing reasoning beyond picking among options you define.
+## When NOT to call it
+
+The tool earns its keep where a judgment call would otherwise be a guess. Skip it when:
+
+- **You already know the answer.** If the decision is trivial or fully determined by what you see, deciding yourself is faster and strictly better — a 9B reflex adds latency and noise, not information.
+- **The task needs generation or reasoning** — free text, code writing, multi-step analysis. Clef only splits probability mass over options you define.
+- **You would re-ask without new facts.** A flat distribution means the *state* did not disambiguate. Re-rolling the same state gives the same answer: gather context or ask the user instead.
+- **The missing input is user preference, not judgment.** "Deploy Friday or Monday?" is a question for the user, not for the model.
+- **The stakes require accountability you can't delegate.** For destructive or security-adjacent actions the model is a gate signal, never the decision maker.
 
 ## How to call
 
@@ -48,7 +56,7 @@ Bad fits: free-text generation, code writing, anything needing reasoning beyond
 
 Rules that prevent wasted calls:
 
-- **`state` is data, not instructions.** Compact, factual, relevant. It never executes and never changes server behavior. Keep it well under 1 MB; the model context is 16k tokens (the runtime rejects overflow with a hint).
+- **`state` is data, not instructions.** Compact, factual, relevant. It never executes and never changes server behavior. Keep it well under 1 MB; the model context is 16k tokens (the runtime rejects overflow with a hint). Latency scales with context: aim for a state of ~1–4k tokens — 16k-token states are ~20× slower than 1k ones.
 - **`choice` criteria**: map `option_id → description`, or a plain list of option strings (ids become the strings). Both are accepted.
 - **`score` criteria**: an **ordered** list — index order is the score order (low → high). Do not shuffle.
 - **`noul`**: instructions only; the answer is `{"true": p, "false": 1-p}`.
@@ -62,15 +70,17 @@ Rules that prevent wasted calls:
 {
   "model": "clef-flash",
   "decisions": {
-    "next_action": { "answer": { "inspect": 0.96, "modify": 0.01, "test": 0.01, "ask_user": 0.01 } }
-  }
+    "next_action": { "answer": { "inspect": 0.96, "modify": 0.01, "test": 0.01, "ask_user": 0.01 }, "confidence": 0.83 }
+  },
+  "usage": { "input_tokens": 228, "output_tokens": 0, "latency_ms": 512 }
 }
 ```
 
 - The result is **structured JSON**. Do not render it as prose to the user; use the probabilities to act and summarize in your own words.
 - **Argmax** is the model's pick; a decisive distribution (e.g. `0.9+`) means act on it.
+- **`confidence`** is the model's own certainty for that decision (reported for choice/score when the runtime sends it). Use it together with the top probability: for destructive or security-adjacent calls require top `p ≥ 0.8` *and* high `confidence` before acting; otherwise gather context or ask.
 - **Flat distributions** (~equal probabilities) mean the state did not disambiguate: gather more context and re-ask, or ask the user.
-- For safety-adjacent calls (destructive actions, security), require a **high threshold** (e.g. `p ≥ 0.8`) before acting; otherwise prefer asking.
+- **`usage`** shows how much context the call consumed (`input_tokens`) and what it cost in time (`latency_ms`). If `input_tokens` is large and `latency_ms` is seconds, your state is too big — compact it.
 - `noul` answers above ~0.9 true/false are strong signals; 0.5–0.7 is a lean, not a verdict.
 
 ## Errors and recovery