Jevbridge

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.

Home: tacticocc/Jevbridge.

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.

Built With

Related MCP server: jev-flash-router

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

1. Clone the repo

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

   The npm name is @tactico/jevbridge. After a release is published:

   npm install -g @tactico/jevbridge

2. Install (no runtime npm dependencies)

   npm install

3. 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-...

4. Run a recipe without any network

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

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

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.

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.

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

• examples/zed.settings.json

• examples/zed.claude-proxy.json

• examples/zed.codex-proxy.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.

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 sidecar:

1. Classifies the turn (question, code edit, computer use, terminal).

2. Calls Jev or the LLM System One adapter.

3. Confidence-gates the result.

4. Streams session/update tool calls and a short agent message.

Sessions persist under ~/.jevbridge/sessions. The adapter advertises loadSession plus sessionCapabilities.resume / list / close / delete, so Zed and other hosts can restore a thread with session/load (replay history) or session/resume (reconnect without replay).

Proxy an upstream agent

Point Jevbridge at Claude Code or Codex. It speaks ACP to the host, forwards the generating agent, and intercepts session/request_permission plus pending tool_call notifications. Jevbridge then allows, asks the user, or denies the call.

jevbridge acp --upstream claude
jevbridge acp --upstream codex
jevbridge acp -- /path/to/custom-acp-agent

Zed settings.json (Codex behind Jevbridge):

{
  "agent_servers": {
    "Jevbridge Codex": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "@tactico/jevbridge", "acp", "--upstream", "codex"],
      "env": {
        "TYPESAFE_API_KEY": "ts_..."
      }
    }
  }
}

Presets spawn npx -y @agentclientprotocol/claude-agent-acp and npx -y @agentclientprotocol/codex-acp. Destructive execute/delete/edit/move calls that Jev aborts are failed in the client and cancelled upstream.

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

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);

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 @tactico/jevbridge

• Transfer this repository into the tacticocc organization

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

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!

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

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

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Tactico — github.com/tacticocc

Project Link: https://github.com/tacticocc/Jevbridge

Acknowledgments

• Best-README-Template

• TypeSafe Jev and the System One adapter

• Agent Client Protocol

• Choose an Open Source License

• Img Shields

• GitHub Pages