<a id="readme-top"></a>

<!-- PROJECT SHIELDS -->
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]



<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://github.com/gamesonrblx/Jevbridge">
    <img src="brand/icon.png" alt="Jevbridge logo" width="180" height="180">
  </a>

  <h3 align="center">Jevbridge</h3>

  <p align="center">
    ACP and MCP adapter that bridges TypeSafe Jev with any LLM.
    <br />
    Computer use and typed decisions alongside Codex, Claude, Grok, and OpenCode.
    <br />
    <br />
    <a href="https://github.com/gamesonrblx/Jevbridge"><strong>Explore the docs »</strong></a>
    <br />
    <br />
    <a href="https://github.com/gamesonrblx/Jevbridge">View Demo</a>
    &middot;
    <a href="https://github.com/gamesonrblx/Jevbridge/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
    &middot;
    <a href="https://github.com/gamesonrblx/Jevbridge/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
  </p>
</div>



<!-- TABLE OF CONTENTS -->
<details>
  <summary>Table of Contents</summary>
  <ol>
    <li>
      <a href="#about-the-project">About The Project</a>
      <ul>
        <li><a href="#core-capabilities">Core Capabilities</a></li>
        <li><a href="#built-with">Built With</a></li>
      </ul>
    </li>
    <li>
      <a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#prerequisites">Prerequisites</a></li>
        <li><a href="#installation">Installation</a></li>
      </ul>
    </li>
    <li><a href="#usage">Usage</a></li>
    <li><a href="#mcp-server">MCP Server</a></li>
    <li><a href="#acp-adapter">ACP Adapter</a></li>
    <li><a href="#computer-use">Computer Use</a></li>
    <li><a href="#roadmap">Roadmap</a></li>
    <li><a href="#contributing">Contributing</a></li>
    <li><a href="#license">License</a></li>
    <li><a href="#contact">Contact</a></li>
    <li><a href="#acknowledgments">Acknowledgments</a></li>
  </ol>
</details>



<!-- ABOUT THE PROJECT -->
## About The Project

<div align="center">
  <a href="https://github.com/gamesonrblx/Jevbridge">
    <img src="brand/icon.png" alt="Jevbridge" width="220" height="220">
  </a>
</div>

[TypeSafe Jev](https://typesafe.ai) 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`](https://github.com/tacticocc). This public repository is published from the connected GitHub account until it can be transferred into that organization.

<p align="right">(<a href="#readme-top">back to top</a>)</p>



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

<p align="right">(<a href="#readme-top">back to top</a>)</p>



### Built With

* [![TypeScript][TypeScript]][TypeScript-url]
* [![Node.js][Node.js]][Node.js-url]
* [![TypeSafe][TypeSafe]][TypeSafe-url]
* [![ACP][ACP]][ACP-url]

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- GETTING STARTED -->
## 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](https://console.typesafe.ai/settings/keys)
* Optional: an LLM key (`XAI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENCODE_API_KEY`)

### Installation

1. Clone the repo
   ```sh
   git clone https://github.com/gamesonrblx/Jevbridge.git
   cd Jevbridge
   ```
2. Install (no runtime npm dependencies)
   ```sh
   npm install
   ```
3. Export keys you actually have. Native Jev is preferred; otherwise Jevbridge wraps your LLM.
   ```sh
   export TYPESAFE_API_KEY=ts_...
   export JEVBRIDGE_LLM=xai
   export XAI_API_KEY=xai-...
   ```
4. Run a recipe without any network
   ```sh
   node --experimental-strip-types src/cli.ts eval support-route
   ```

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- USAGE EXAMPLES -->
## Usage

### Library

```ts
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

```sh
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:

```sh
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.

_For more examples, see `src/recipes.ts` and `skills/jevbridge/SKILL.md`._

<p align="right">(<a href="#readme-top">back to top</a>)</p>



## MCP Server

Jevbridge speaks the [Model Context Protocol](https://modelcontextprotocol.io) 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`):

```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`):

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

```json
{
  "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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>



## ACP Adapter

Jevbridge implements the [Agent Client Protocol](https://agentclientprotocol.com) over stdio with LSP-style `Content-Length` framing.

Add to Zed `settings.json`:

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

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.

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>



## 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`.

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- ROADMAP -->
## Roadmap

- [x] System One client (Jev, LLM adapter, heuristic)
- [x] Confidence gate
- [x] Computer-use recipes
- [x] ACP stdio adapter (`initialize`, `session/new`, `session/prompt`)
- [x] 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](https://github.com/gamesonrblx/Jevbridge/issues) for a full list of proposed features (and known issues).

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- CONTRIBUTING -->
## 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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

### Top contributors:

<a href="https://github.com/gamesonrblx/Jevbridge/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=gamesonrblx/Jevbridge" alt="contrib.rocks image" />
</a>



<!-- LICENSE -->
## License

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- CONTACT -->
## Contact

Tactico — [github.com/tacticocc](https://github.com/tacticocc)

Project Link: [https://github.com/gamesonrblx/Jevbridge](https://github.com/gamesonrblx/Jevbridge)

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- ACKNOWLEDGMENTS -->
## Acknowledgments

* [Best-README-Template](https://github.com/othneildrew/Best-README-Template)
* [TypeSafe Jev](https://typesafe.ai) and the [System One adapter](https://github.com/typesafe-ai/system-one-adapter-python)
* [Agent Client Protocol](https://agentclientprotocol.com)
* [Choose an Open Source License](https://choosealicense.com/)
* [Img Shields](https://shields.io)
* [GitHub Pages](https://pages.github.com)

<p align="right">(<a href="#readme-top">back to top</a>)</p>



<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
[contributors-shield]: https://img.shields.io/github/contributors/gamesonrblx/Jevbridge.svg?style=for-the-badge
[contributors-url]: https://github.com/gamesonrblx/Jevbridge/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/gamesonrblx/Jevbridge.svg?style=for-the-badge
[forks-url]: https://github.com/gamesonrblx/Jevbridge/network/members
[stars-shield]: https://img.shields.io/github/stars/gamesonrblx/Jevbridge.svg?style=for-the-badge
[stars-url]: https://github.com/gamesonrblx/Jevbridge/stargazers
[issues-shield]: https://img.shields.io/github/issues/gamesonrblx/Jevbridge.svg?style=for-the-badge
[issues-url]: https://github.com/gamesonrblx/Jevbridge/issues
[license-shield]: https://img.shields.io/github/license/gamesonrblx/Jevbridge.svg?style=for-the-badge
[license-url]: https://github.com/gamesonrblx/Jevbridge/blob/main/LICENSE
[TypeScript]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white
[TypeScript-url]: https://www.typescriptlang.org/
[Node.js]: https://img.shields.io/badge/Node.js_22-339933?style=for-the-badge&logo=nodedotjs&logoColor=white
[Node.js-url]: https://nodejs.org/
[TypeSafe]: https://img.shields.io/badge/TypeSafe_Jev-111111?style=for-the-badge
[TypeSafe-url]: https://docs.typesafe.ai/
[ACP]: https://img.shields.io/badge/ACP-stdio-555555?style=for-the-badge
[ACP-url]: https://agentclientprotocol.com