# Jev Checkpoint

**Jev Checkpoint** is a local MCP server that turns a bounded routing decision
into one TypeSafe Jev choice question. It returns the chosen route,
probabilities, confidence, and a thresholded recommendation. It never performs
the selected action.

## What it is for

Use it when an agent has already gathered evidence and needs to choose among a
small set of next actions, for example:

- proceed, inspect callers, or ask the user;
- routine review, deeper review, or human review; or
- code, configuration, dependency, or insufficient evidence.

It is not a planner, reviewer, implementation model, or approval mechanism.

## Configure in four steps

1. Install and build:

```sh
npm install
npm run build
```

2. Set your TypeSafe key:

```sh
export TYPESAFE_API_KEY="your-key"
```

You can get the API key from e.g. Openrouter : https://openrouter.ai/typesafe/jev-1.13

3. Add this server to Claude Code's MCP settings (replace the path):

```json
{
  "mcpServers": {
    "jev-checkpoint": {
      "command": "node",
      "args": ["/absolute/path/to/jev-checkpoint/dist/index.js"],
      "env": { "TYPESAFE_API_KEY": "your-key" }
    }
  }
}
```

4. Add this to your project's `CLAUDE.md` (or its equivalent agent
instructions):

```markdown
When a bounded routing decision is uncertain and has explicit choices, call
`classify_decision` before proceeding. Include the decision, compact evidence,
allowed choices, and error cost. Treat its result as advisory. Never use it to
auto-commit, push, deploy, make clinical decisions, or send sensitive data to a
third party without approval.
```

Claude Code then knows when to call the tool.

The optional reusable skill is [`.claude/skills/confidence-gate/SKILL.md`](.claude/skills/confidence-gate/SKILL.md).

## Tool contract

`classify_decision` accepts:

```json
{
  "decision": "Choose the next safe action.",
  "state": "Tests fail only after package X changed from 1.2 to 1.3.",
  "choices": [
    { "id": "inspect_dependency", "description": "Inspect the package change and callers." },
    { "id": "inspect_code", "description": "Trace the failing code path." },
    { "id": "ask_user", "description": "Ask for missing reproduction details." }
  ],
  "errorCost": "medium",
  "threshold": 0.95
}
```

The result is advisory. A confidence below `threshold` always returns
`needs_deeper_review`.

## How it works

```mermaid
flowchart LR
  A[Agent reaches an uncertain next step] --> B[Collect compact evidence]
  B --> C{2-10 explicit routes?}
  C -- no --> D[Use normal planning or investigation]
  C -- yes --> E[classify_decision]
  E --> F{Confidence meets threshold?}
  F -- yes --> G[Take selected safe route]
  F -- no --> H[Inspect more, use deeper model, or ask user]
```

```mermaid
flowchart LR
  A[Shadow mode: Jev recommendation] --> B[Normal workflow still runs]
  B --> C[Record final route, findings, time, and cost]
  C --> D{False-proceed rate and cost improve?}
  D -- yes --> E[Allow the gate to suppress selected deeper calls]
  D -- no --> F[Keep advisory-only or remove the gate]
```

## Safety

This server is advisory-only. It never performs the selected action, and a
calling agent must preserve its own approval and safety rules.

This project makes no claims yet about cost, speed, or quality improvement.
Those claims require a published benchmark against the intended workflow.

Do not send secrets, source code you are not allowed to disclose, or PHI to the
TypeSafe API. A local MCP process does not make a hosted API local.

## License

[MIT](LICENSE)