README.md

September 20, 2026 · View on GitHub

Jevbridge

ACP and MCP adapter that bridges TypeSafe Jev with any LLM.
Computer use and typed decisions alongside Codex, Claude, Grok, and OpenCode.

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

About The Project
- Core Capabilities
- Built With
Getting Started
- Prerequisites
- Installation
Usage
MCP Server
ACP Adapter
Computer Use
Roadmap
Contributing
License
Contact
Acknowledgments

About The Project

TypeSafe Jev is a System One model: unstructured state in, typed probabilistic decisions out. It does not generate text. That makes it a poor chatbot and an excellent function call for routing, gating, scoring, and computer-use action selection.

Jevbridge is the adapter that sits alongside the LLM you already run.

Native Jev when TYPESAFE_API_KEY is set.
Any LLM as System One when it is not — Codex, Claude, Grok, OpenCode, or a generic OpenAI-compatible endpoint.
ACP over stdio so Zed, JetBrains, and other Agent Client Protocol hosts can treat Jev as the decision sidecar for a generating model.
Confidence gates so a peaked distribution executes, a middling one confirms, and a destructive click does not go unsupervised.

The LLM writes the plan and the explanation. Jevbridge returns noul, choice, and score answers that software can branch on.

Intended home: tacticocc/Jevbridge. This public repository is published from the connected GitHub account until it can be transferred into that organization.

(back to top)

Core Capabilities

Evaluate one state against mixed Choice, Score, and Noul questions.
Swap backends (jev | llm | heuristic | auto) without changing question shapes.
Confidence-gate tool calls and computer-use clicks (execute, confirm, escalate, abort).
Speak MCP (jev_decide, jev_gate, jev_computer_use) and ACP over stdio.
Ship recipes for support routing, destructive command gates, context keep/drop, and GUI next-action.
Run offline with the heuristic backend in tests and CI.

(back to top)

Built With

(back to top)

Getting Started

Jevbridge is a zero-dependency Node 22 library plus MCP and ACP stdio binaries. You do not need a TypeSafe key to try it: the heuristic backend and any OpenAI-compatible LLM both speak the same protocol.

Prerequisites

Node.js 22 or newer
Git
Optional: a TypeSafe API key
Optional: an LLM key (XAI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENCODE_API_KEY)

Installation

Clone the repo

git clone https://github.com/gamesonrblx/Jevbridge.git
cd Jevbridge

Install (no runtime npm dependencies)
```
npm install
```
Export keys you actually have. Native Jev is preferred; otherwise Jevbridge wraps your LLM.
```
export TYPESAFE_API_KEY=ts_...
export JEVBRIDGE_LLM=xai
export XAI_API_KEY=xai-...
```

Run a recipe without any network

node --experimental-strip-types src/cli.ts eval support-route

(back to top)

Usage

Library

import { evaluate, gate, noul, choice, score } from "./src/index.ts";

const result = await evaluate({
  state: "I was charged twice for order A-104. Refund the duplicate today.",
  questions: {
    refund: noul("Does this request a refund?"),
    team: choice("Which team should handle this?", {
      billing: "Payments, invoices, refunds.",
      technical: "Bugs, outages, integrations.",
      other: "None of the above.",
    }),
    urgency: score("How urgent is this?", [
      "Can wait a week",
      "Handle today",
      "Blocking now",
    ]),
  },
  backend: "auto",
  jev: process.env.TYPESAFE_API_KEY
    ? { apiKey: process.env.TYPESAFE_API_KEY }
    : undefined,
});

const decision = gate(result.answers, { choiceId: "team" });
if (decision.action === "execute") {
  // branch on result.answers.team.choice
}

CLI

node --experimental-strip-types src/cli.ts recipes
node --experimental-strip-types src/cli.ts eval computer-use
node --experimental-strip-types src/cli.ts mcp
node --experimental-strip-types src/cli.ts acp

Or use the wrapper:

node bin/jevbridge.mjs eval destructive-gate

Environment

Variable	Purpose
`TYPESAFE_API_KEY`	Native Jev (`POST https://api.typesafe.ai/v1/systemone`)
`JEVBRIDGE_LLM`	`xai` \| `openai` \| `anthropic` \| `opencode` \| `codex` \| `generic`
`JEVBRIDGE_LLM_MODEL`	Override model id
`JEVBRIDGE_BASE_URL`	Override OpenAI-compatible base URL
`XAI_API_KEY`	Grok
`OPENAI_API_KEY`	OpenAI / Codex
`ANTHROPIC_API_KEY`	Claude
`OPENCODE_API_KEY`	OpenCode

backend: "auto" uses Jev when a TypeSafe key is present, otherwise the LLM adapter, otherwise heuristic.

With no API key, auto falls back to the local keyword scorer. The payload reports "backend": "heuristic". That scorer includes question text in its evidence, so asking "would this spend money, delete data, or submit a form?" about "hello world" can still score high from word overlap. Treat heuristic numbers as a smoke test, not a safety signal.

For more examples, see src/recipes.ts and skills/jevbridge/SKILL.md.

(back to top)

MCP Server

Jevbridge speaks the Model Context Protocol over stdio (newline-delimited JSON-RPC 2.0). Point Claude Desktop, Cursor, Codex, OpenCode, or any MCP host at jevbridge mcp. The generating model keeps writing; Jevbridge is the typed decision tool.

Tool	What it does
`jev_decide`	Fan out `noul` / `choice` / `score` on one state. Returns answers + gate.
`jev_gate`	Confidence-gate already computed answers (`execute` / `confirm` / `escalate` / `abort`).
`jev_computer_use`	Next GUI action from a closed set: click, type, scroll, wait, screenshot, done, abort.
`jev_recipe`	Run a built-in recipe (`support-route`, `computer-use`, `destructive-gate`, `compaction`).

Also exposes jevbridge://recipe/{id} resources and two prompts.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "jevbridge": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "/absolute/path/to/Jevbridge/src/cli.ts",
        "mcp"
      ],
      "env": {
        "TYPESAFE_API_KEY": "ts_..."
      }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.jevbridge]
command = "node"
args = ["--experimental-strip-types", "/absolute/path/to/Jevbridge/src/cli.ts", "mcp"]

OpenCode (opencode.json) and Cursor (.cursor/mcp.json) live in examples/. Drop-in copies:

examples/claude-desktop.json
examples/cursor.mcp.json
examples/codex.config.toml
examples/opencode.json

Example tool call:

{
  "name": "jev_decide",
  "arguments": {
    "state": "I was charged twice for order A-104. Refund the duplicate today.",
    "questions": {
      "refund": { "type": "noul", "instructions": "Does this request a refund?" },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments, invoices, refunds.",
          "technical": "Bugs, outages, integrations.",
          "other": "None of the above."
        }
      }
    }
  }
}

Call jev_gate before a destructive tool. Call jev_computer_use instead of asking the LLM which CSS selector to click.

(back to top)

ACP Adapter

Jevbridge implements the Agent Client Protocol over stdio with LSP-style Content-Length framing.

Add to Zed settings.json:

{
  "agent_servers": {
    "Jevbridge": {
      "type": "custom",
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "/absolute/path/to/Jevbridge/src/cli.ts",
        "acp"
      ],
      "env": {
        "TYPESAFE_API_KEY": "ts_...",
        "JEVBRIDGE_LLM": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

On session/prompt the adapter:

Classifies the turn (question, code edit, computer use, terminal).
Calls Jev or the LLM System One adapter.
Confidence-gates the result.
Streams session/update tool calls and a short agent message.

Codex, Claude Code, Grok Build, and OpenCode keep generating. Jevbridge decides.

(back to top)

Computer Use

Computer-use loops waste frontier tokens on “what should I click.” Jevbridge scores a GUI observation against a closed action set:

click · type · scroll · wait · screenshot · done · abort

plus target, safety, destructiveness, and goal progress. A refund button that spends money comes back confirm, not execute — destructiveness is an independent gate, so a peaked action distribution does not skip it.

import { computerUseQuestions, observationState, readAction } from "./src/index.ts";

const state = observationState({
  goal: "Refund the duplicate charge on order A-104",
  app: "Billing Console",
  visible: ["Refund duplicate", "Email customer", "Close ticket"],
});

const result = await evaluate({
  state,
  questions: computerUseQuestions(["Refund duplicate", "Email customer", "Close ticket"]),
  backend: "auto",
});

const action = readAction(result.answers);

(back to top)

Roadmap

System One client (Jev, LLM adapter, heuristic)
Confidence gate
Computer-use recipes
ACP stdio adapter (initialize, session/new, session/prompt)
MCP stdio server (jev_decide, jev_gate, jev_computer_use, jev_recipe)
Proxy an upstream ACP agent (Claude Code, Codex) and intercept tool calls
Session load / resume
Published npm package @tacticocc/jevbridge
Transfer this repository into the tacticocc organization

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please add or update tests under src/*.test.ts for behavioral changes.

(back to top)

Acknowledgments

(back to top)