# GitHub issue summary

Adopt this skill: https://proskills.md/skills/other/billionsbobby-jevrouter-examples-skills-github-summary

Page: https://proskills.md/skills/other/billionsbobby-jevrouter-examples-skills-github-summary
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: examples/skills/github-summary/SKILL.md
size: 273
sha: 057c6fd0e906a59c322dd21b8dd85e821010a709
upstream: https://github.com/billionsbobby/jevrouter/blob/main/examples/skills/github-summary/SKILL.md

```text
---
name: GitHub issue summary
description: Summarize GitHub issue search results by severity.
version: 1.0.0
permissions:
  - github.read
---

# GitHub issue summary

Use this skill after a read-only issue search to group results by severity and produce a concise report.
```

## File: README.md
upstream: https://github.com/billionsbobby/jevrouter/blob/main/README.md

````text
<div align="center">

<img src="docs/assets/jev-api-router-comparison.png" alt="JevRouter — Jev supplies the decision model, JevRouter supplies the agent integration" width="720" />

# JevRouter

**Faster agent decisions.** Models, subagents, skills, MCP tools, CLIs and plugins become one candidate set — Jev answers one typed Choice question, JevRouter enforces availability, permissions, risk and confirmation around it.

[![CI](https://github.com/BillionsBobby/JevRouter/actions/workflows/ci.yml/badge.svg)](https://github.com/BillionsBobby/JevRouter/actions/workflows/ci.yml)
[![Website](https://img.shields.io/badge/website-jevrouter.co-blue)](https://www.jevrouter.co/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Node.js ≥ 20](https://img.shields.io/badge/node-%E2%89%A5%2020-339933?logo=node.js&logoColor=white)](package.json)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&logoColor=white)](tsconfig.json)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

[Website](https://www.jevrouter.co/) · [Quickstart](#quickstart) · [Benchmark](#benchmark) · [Cookbook](docs/cookbook/README.md) · [Documentation](#documentation) · [中文](#中文介绍)

</div>

---

## Why JevRouter

Agents waste reasoning tokens on a question a fast decision model answers better: **which capability should handle this next?** JevRouter puts [Jev](https://www.jevrouter.co/) — a System One model that turns structured state into typed decisions with probability distributions — in front of your tools, while your reasoning model stays the execution and fallback layer.

The key contract is simple: **Jev owns the decision probabilities; JevRouter owns availability, permissions, risk and confirmation.** Router fields live under `router`, while the original `probabilities`, `confidence`, and complete provider response remain intact. Filtered candidates are never re-normalized.

- **Decision-only by default** — nothing executes implicitly; medium/high/critical capabilities require confirmation.
- **One call or a plan** — `route` answers one question; `plan` answers "which capability handles step 1..N" with serial, batch, and decomposed strategies.
- **Every surface** — models, subagents, Skills, MCP tools, CLIs, DSH plugins share one routing contract.
- **Receipts by default** — append-only decision/plan files with provenance hashes; what was decided, why, and at what confidence is always auditable.
- **Capability trust is explicit** — discovered and caller-supplied candidates carry verification status; strict projects can set `require_verified_candidates` to prevent unverified descriptions from being selected.

![JevRouter Architecture](docs/assets/jevrouter-architecture.png)

## Benchmark

First-5 tool-call prediction on 10 Toolathlon tasks (real tool inventories from 9 live MCP servers, Jev `typesafe/jev-1.13-20260917` vs DeepSeek V4.1 Flash):

| Metric | Jev serial | Jev decompose + thread | DeepSeek V4.1 Flash |
|---|---|---|---|
| Position-wise hits | 38% | **44%** | 24% |
| Prefix alignment (mean LCP) | 0.9 | **1.6** | 0.5 |
| Latency per task | **1.58s** | 10.6s | 8.65s |
| Cost per 10 tasks | **$0.0058** | $0.0055 | ≈ $0.0407 |

Batch mode with beam sequence selection (`--sequence beam`) lifts position-wise hits 28% → 36% at **zero extra provider calls**. The same decompose+thread configuration scores 44% hits / 69% overlap on MCP-Atlas. This experiment measures ordered routing decisions, not end-to-end task completion; method and per-task data in [issue #2](https://github.com/BillionsBobby/JevRouter/issues/2), strategies in [PR #9](https://github.com/BillionsBobby/JevRouter/pull/9).

## Quickstart

Node.js 20+ required. JevRouter accepts either the official Jev API or an OpenRouter key. The key is entered interactively when no matching environment variable is already exported.

**Give your agent the router** (installs the Skill + project instructions, checks Jev, launches the host):

```bash
npx --yes github:BillionsBobby/JevRouter agent start --agent codex
```

Choose `typesafe` for the official Jev API or `openrouter` at the prompt, then paste the corresponding key. The key stays in the current process environment and is never written to project files. For Claude Code use `--agent claude`, and for Cursor use `--agent cursor`. Setup automatically adds `.jevrouter/` to `.gitignore` to keep local decision receipts from being accidentally committed. To install without launching a host, export `TYPESAFE_API_KEY`, `JEV_API_KEY`, or `OPENROUTER_API_KEY` first and use `agent setup`; to verify later, use `agent doctor` (`--live` adds a small paid probe):

```bash
npx --yes github:BillionsBobby/JevRouter agent setup          # Skill + project instructions only
npx --yes github:BillionsBobby/JevRouter agent doctor --live  # configuration + connectivity check
```

**Route one decision** (no registry needed — pass candidates inline):

```bash
OPENROUTER_API_KEY="your-key" npx --yes github:BillionsBobby/JevRouter route --provider openrouter \
  --request "Find original sources before summarizing" \
  --candidates '[{"name":"search_web","description":"Find web sources"},{"name":"summarize","description":"Summarize existing sources"}]'
```

**Plan a multi-step task**:

```bash
OPENROUTER_API_KEY="your-key" npx --yes github:BillionsBobby/JevRouter plan --provider openrouter \
  --request "Search sources about Jev, summarize them, save to notes.md" \
  --candidates-file candidates.json --steps 3 --mode serial
```

**SDK**:

```bash
npm install github:BillionsBobby/JevRouter
```

```ts
import { route, plan } from "jevrouter";

const decision = await route({ request, candidates: agentTools });
const planResult = await plan({ request, candidates: agentTools }, { steps: 3, mode: "batch", sequence: "beam" });
```

Try everything offline with the labelled demo provider (`--provider demo`) — no key required.

## Cookbook

Task-oriented recipes, each with exact commands and expected output:

| Recipe | What it covers |
|---|---|
| [Route your first request](docs/cookbook/01-route-your-first-request.md) | CLI one-shot, inline candidates, exit codes, demo mode |
| [Multi-step plans](docs/cookbook/02-multi-step-plans.md) | serial vs batch vs decompose, beam sequences, strategies |
| [Use with Codex](docs/cookbook/03-use-with-codex.md) | `agent setup/start/doctor`, `$jevrouter` Skill, MCP option |
| [Use with Claude Code](docs/cookbook/04-use-with-claude-code.md) | same flow for Claude Code (`/jevrouter`) |
| [MCP adapter](docs/cookbook/05-mcp-adapter.md) | `serve-mcp` stdio server, `jev_route` tool, host MCP configs |
| [Custom candidates & discovery](docs/cookbook/06-custom-candidates.md) | manifest contract, OpenAI tool shapes, `discover` |
| [Policy, risk & confirmation](docs/cookbook/07-policy-and-confirmation.md) | `policy.json`, confidence gates, `no_decision`, permissions |
| [Offline, caching & receipts](docs/cookbook/08-offline-and-caching.md) | demo provider, cache control, provenance, receipts |
| [Local dashboard](docs/cookbook/09-local-dashboard.md) | read-only routing statistics and effect boundary |

## How it works

1. **Choose the model.** Route by capability, latency, cost, and context without rewriting your agent loop.
2. **Every tool surface.** Skill, MCP, or plugin — routed through the same Jev decision layer with permissions, risk, and confirmation intact.
3. **Choose the specialist.** Delegate research, coding, and focused work to the subagent built for the request.

Single decisions go through one Jev Choice call. When `single_stage_max_candidates` is exceeded, JevRouter keeps the coarse Top-K first, then asks Jev for a final Choice over the reduced set; both raw responses are preserved in `raw_jev_stages`.

## Multi-step plans

`route` answers one question. `plan` answers "which capability should handle step 1..N of this request?":

- **Serial** (default): one full routing decisio
````
