jev-x-kit

jev-x-kit

Universal TypeSafe Jev / OpenJev autonomous decision, deep research, ultra-planning & self-improving agent framework — packaged as a Claude Code plugin/skill, an MCP server, and a standalone CLI.

Built for Claude Code, Cursor, Codex, OpenCode, Continue.dev, Ollama / vLLM, and every MCP-compatible agent. Runs 100% free and offline: no API key, no GPU, no cloud required.

Install as a Claude Code plugin (30 seconds)

git clone https://github.com/Kadihx/jev-x-kit.git
cd jev-x-kit && npm install && npm run build

Then point Claude Code at this folder as a plugin (.claude-plugin/plugin.json is already wired up: it registers the jev skill and the jev-super-agent MCP server with 21 tools). See skills/jev/SKILL.md for the command cheat-sheet Claude reads to decide when to reach for Jev instead of free-text reasoning.

Why this exists (6 root problems)

1. Latency wall — LLMs take 3–30s for a simple yes/no routing decision.
2. Token cost explosion — agent loops burn $10–$50 per session on micro-decisions.
3. JSON schema breakage — free-text models hallucinate parameters and break parsers.
4. Context rot — "summarized" logs hallucinate file paths, commands and error codes.
5. Single-pass blind spot — a model can't adversarially review its own plan.
6. Vendor lock-in — paid APIs only, no offline path.

What this kit does

It inserts a System 1 decision layer in front of every micro-decision:

• Non-autoregressive primitives: Choice (up to 255 options), Score (fractional 1–10), Noul (calibrated probability in [0, 1]) — never free text, schema-validated, zero output-token cost.
• "BELKİ" Gatekeeper: confidence > 0.85 executes directly at $0 LLM cost; 0.60–0.85 splits into speculative sub-decisions; below 0.60 escalates to System 2 or a human.
• Speculative fan-out: N independent questions are evaluated in one parallel pass — extra questions add no latency and no cost.
• Winnow lossless compaction: irrelevant log lines are deleted, never summarized. File paths, commands, error codes, URLs and diff headers are always preserved byte-identically.
• Adversarial red-teaming: a hostile reviewer generates concrete anti-theses; the Jev loop arbitrates the safest route with residual risks.
• RLVR self-improvement: tsc + npm test pass/fail records ±1 rewards into .jev-skill-memory.json; verified wins auto-tune the gatekeeper thresholds.

Quickstart (zero config, offline)

npm install
npm run build
npm test            # 27 unit tests (core 20 + datacenter 7) on the deterministic offline simulator
npm run test:hub    # 7 datacenter tests (source registry, robots, license engine, FTS store, query tiers)
npm run smoke       # full end-to-end MCP smoke test (50 checks)

Everything works immediately with no network, no GPU and no API key — the deterministic offline simulator keeps every primitive valid and schema-safe.

MCP server setup

Add this to your agent's MCP config (mcp-config.json, claude_desktop_config.json, opencode.json, Continue.dev, Codex):

{
  "mcpServers": {
    "jev-super-agent": {
      "command": "node",
      "args": ["C:\\path\\to\\jev-x-kit\\dist\\index.js"],
      "env": {
        "JEV_BACKEND_PROVIDER": "auto",
        "OPENJEV_BASE_URL": "http://localhost:8000/v1",
        "JEV_LLM_BASE_URL": "http://localhost:11434/v1"
      }
    }
  }
}

Free local backends (auto-detected in order)

Backend	Command	Cost
OpenJev on vLLM (razorback16/openjev)	docker run --gpus all -p 8000:8000 razorback16/openjev	$0
LayA (NandhaKishorM/laya)	python -m laya.serve --port 8000	$0
Ollama (System-2 LLM for planner/red-team)	ollama serve (default :11434)	$0
Vercel AI Gateway free tier	set VERCEL_AI_GATEWAY_KEY	free tier
TypeSafe Jev native	TYPESAFE_JEV_API_KEY + TYPESAFE_JEV_NATIVE=1 (required — see below)	$0.042 / 1M in, $0 output

Set JEV_BACKEND_PROVIDER to auto (default), typesafe_jev, openjev_local, laya_local or heuristic (fully offline).

TYPESAFE_JEV_NATIVE=1 is not optional for the hosted API. TypeSafe's real API is a single POST /v1/systemone endpoint (state + named questions in, named answers + token usage out) — there is no /chat/completions endpoint at api.typesafe.ai, so without the native flag the chat-proxy transport 404s and every call silently falls back to the offline heuristic. Verified live on 2026-09-21: a 12-candidate jev_research run cost $0.00016874 in real TypeSafe API usage. Note the hosted API only answers Choice/Score/Noul — it has no chat/completion endpoint, so point JEV_LLM_BASE_URL at Ollama/vLLM/etc. regardless, for planner/red-team/research-synthesis text generation.

CLI (scriptable, zero MCP client needed)

node dist/cli.js info                                    # backend + chain diagnosis
node dist/cli.js decide "run tsc first?" --options "yes,no"
node dist/cli.js plan "Ship an offline decision layer" --preset software-architecture
node dist/cli.js redteam "We cache everything forever"
node dist/cli.js compact --file build.log --goal "port binding error"
node dist/cli.js audit .
node dist/cli.js guardrail --tool bash --args "rm -rf /"
node dist/cli.js verify --cwd .                          # RLVR: tsc + tests -> reward
node dist/cli.js label --file data.jsonl --mode score
node dist/cli.js memory report
node dist/cli.js features                                # 20 enterprise features

MCP tools (28)

Tool	Module	What it does
jev_evaluate	1	Fan-out batch of Choice/Score/Noul in one pass
jev_decide	1	"BELKİ" gatekeeper: execute / speculative / system2
jev_plan	2	Ultra-planning: hypothesis + anti-thesis + 4-dim Jev score
jev_redteam	3	Adversarial dual loop: anti-theses, severity, arbitration
jev_audit	4	360° scan: architecture / security / marketing / legal / budget
jev_research	5a	4 parallel channels: web / academic / code / social + Jev re-rank
jev_compact	5b	Winnow lossless context compaction (delete, never summarize)
jev_github_mine	6	License audit + clean-room originality guard (5-gram Jaccard)
jev_label_dataset	7	Auto-label rows at $0/row into JSONL
jev_preference_pairs	7	RLCD/DPO chosen/rejected pairs for local models
jev_distill_recipe	7	LoRA distillation recipe + axolotl YAML (Qwen2.5-0.5B / ModernBERT-421M)
jev_verify	8	RLVR: run tsc/tests, record reward, auto-tune thresholds
jev_memory	8	Skill memory report / optimize / record / state
jev_dispatch	9	Chief-of-staff role routing from shared memory
jev_guardrail	9	AutoMode pre-execution gate (allow / ask / block)
jev_privacy_sanitize	10.7	Local PII/secret masking before external calls
jev_rerank	10.12	RAG noise filter + top-K re-ranking
jev_edge_qa	10.11	Deterministic edge-case test matrix
jev_pr_gate	10.16	PR gatekeeper: secrets, breaking exports, leftovers
jev_features	10	20-feature catalog with honest status
jev_backend_info	infra	Backend chain, pricing, policy, presets, paths
hub_crawl	research	Politely crawl the 11-source personal-development knowledge base
hub_query	research	FTS5 + Jev-ranked, cited answers from the crawled hub
hub_stats	research	Doc counts / word counts per source
hub_ingest_rendered	research	Browser-render bridge: feed a page rendered by the calling agent's own browser tool (e.g. Claude Code's claude-in-chrome) through the same extract/license/store pipeline — for client-rendered sources a plain fetch can't read
jev_compact_transcript	5b	Winnow for structured message transcripts: pairs each tool call with its result by id, decides per-pair (keep / truncate / drop), anchors override a "drop" verdict
jev_calibration_check	new	Feeds known-answer Choice cases through the gatekeeper; compares claimed confidence to real accuracy per threshold bucket and checks option-order position bias
jev_competitor_scan	new	Paginated/sortable GitHub search, Noul-ranked against our own positioning, System-2 "closest rival + gaps" synthesis

One-click MCP install

Instead of hand-editing claude_desktop_config.json / .cursor/mcp.json / .continue/config.json, run:

npm run install-mcp

scripts/install-mcp.js detects Claude Desktop, Cursor and Continue.dev on your machine, merges (never overwrites) a jev-super-agent entry into whichever config files exist, and backs up each original file to <file>.bak first.

How it works

flowchart LR
    Q[Decision request] --> G{"BELKİ Gatekeeper<br/>confidence?"}
    G -- "&gt; 0.85" --> E["Execute directly<br/>$0, no LLM call"]
    G -- "0.60 – 0.85" --> S["Speculative fan-out<br/>N sub-decisions in parallel"]
    G -- "&lt; 0.60" --> T["Escalate to System 2<br/>(planner / red-team)"]

    subgraph Backend resolution
        B1[typesafe_jev] -->|unreachable| B2[openjev_local]
        B2 -->|unreachable| B3[laya_local]
        B3 -->|unreachable| B4["heuristic<br/>(always available)"]
    end

    E -.-> B1
    S -.-> B1
    T -.-> B1

Every primitive call (Choice / Score / Noul) is schema-validated — never free text — and the backend chain always terminates in a deterministic offline simulator, so nothing ever fails closed even with no network, no GPU and no API key.

Multi-domain presets (7)

software-architecture, marketing-growth, product-ux, cost-model-router, cybersecurity, legal-compliance (KVKK/GDPR), finance-valuation — every preset injects rules, red-flags, checklists and a scoring rubric into Jev state verbatim.

Self-improving memory

.jev-skill-memory.json stores decisions, verified outcomes and calibration buckets. The dynamic threshold auto-tuner lowers the executeThreshold when calibrated buckets over-deliver and raises it when they fail — so the system provably gets cheaper and safer with every verified outcome.

Configuration (all optional, all env-driven)

Env var	Default	Purpose
JEV_BACKEND_PROVIDER	auto	auto / typesafe_jev / openjev_local / laya_local / heuristic
OPENJEV_BASE_URL	http://localhost:8000/v1	local OpenJev / vLLM endpoint
TYPESAFE_JEV_API_KEY	—	hosted Jev key (or VERCEL_AI_GATEWAY_KEY)
JEV_LLM_BASE_URL	http://localhost:11434/v1	System-2 LLM (Ollama, vLLM, LM Studio)
JEV_LLM_MODEL	qwen2.5:7b-instruct	System-2 model
JEV_GATE_EXECUTE	0.85	gatekeeper direct-execution threshold
JEV_GATE_ESCALATE	0.6	"BELKİ" escalation threshold
JEV_MEMORY_PATH	<repo>/.jev-skill-memory.json	persistent self-improving memory

Development

npm run build      # strict TS compile (zero warnings)
npm test           # 27 unit tests (core 20 + datacenter 7)
npm run smoke      # 50-check end-to-end MCP client test
npm run test:real  # REAL model test: needs `ollama serve` + a local model (e.g. qwen2.5:3b)
npm run test:hub   # 7 datacenter-only tests, no network

Benchmark: how much does this actually save?

Real, reproducible numbers (not marketing copy) comparing jev_research to a Claude Code session doing the same research task by hand (WebSearch/WebFetch + inline reasoning, no local decision layer):

	jev_research	vanilla Claude Code
Tokens entering Claude's context	~2,300 avg	~43,000 avg (~19x more)
Tool round-trips	1	10-12 (~11x more)
Wall-clock	3-10s (measured)	~30-36s (assumption-labeled estimate)

Full methodology, caveats, and how to reproduce every number yourself: BENCHMARK.md.

Research Hub (knowledge data center)

Nightly-scraped research library for personal development, rationality, cognitive psychology and philosophy — 11 curated sources in 3 tiers (mental-models / library / academic), SQLite + FTS5 store, Jev-ranked answers.

npm run hub -- sources                        # list the 11 sources + policies
npm run hub -- crawl --dry-run                 # robots.txt + discovery preview, zero writes
npm run hub -- crawl --source sivers --force   # crawl one source now (off-hours override)
npm run hub -- crawl                           # full nightly crawl (02:00–06:00 Europe/Berlin)
npm run hub -- query "second-order thinking"   # FTS5 + Jev Noul re-rank + VERIFIED/PROBABLE/REJECTED tiers
npm run hub -- stats                           # docs + word counts per source

Pipeline per document: hour-window gate → robots.txt gate → sitemap/HTML/JSON discovery → license check (public-domain full text · academic/library metadata-only) → polite fetch → data/research-hub.sqlite (+ FTS5 index).

License

MIT.