⚡ snapdec

📌 What is snapdec?

snapdec (Snap Decisions) is a lightweight, zero-configuration Model Context Protocol (MCP) server and Agent Skill that gives AI coding agents a dedicated System 1 fast-thinking engine.

Instead of burning thousands of tokens and 3–5 seconds of latency having frontier LLMs (Claude 3.5 Sonnet, GPT-4o, Gemini 1.5 Pro) deliberate over routine categorical choices, snapdec executes typed micro-decisions—classify, check, score, rank, and deterministic project facts—using specialized local models (Kev, Laya) or free hosted routers in under 50 milliseconds.

💡 Why Coding Agents Need Snapdec

Coding agents execute hundreds of micro-decisions during multi-turn workflows:

• "Is this test error an environmental flake or a code bug?"

• "Which 3 files out of 30 in this git diff touch authentication?"

• "What severity level is this linter violation?"

• "Does this repo use uv, poetry, npm, pnpm, or cargo?"

Sending these trivial questions into a 200,000-token context window bloats costs, slows down the agent loop, and wastes time. snapdec intercepts these tasks, processes them in parallel with calibrated confidence scores, and returns an honest auto | review recommendation.

Related MCP server: jev-mcp

✨ Key Features

• ⚡ Sub-50ms Micro-Decisions: Run classification and ranking in 5–50 ms locally on CPU, Apple Silicon (MLX), or CUDA GPU.

• 🎯 Calibrated Probabilities & Fail-Closed Abstention: Every decision includes exact confidence scores (probabilities) and a typed verdict (auto | review). If the model is uncertain, it safely abstains and defers to the host agent.

• 🛠️ Tier-0 Deterministic Facts (0 Tokens): Instant, zero-token repository introspection (project_facts) detecting test runners, linters, package managers, monorepos, and CI setups.

• 💻 Hardware-Aware Auto-Profiler: snapdec init inspects your exact CPU, RAM, GPU, VRAM, and OS, presenting only the local models your machine can genuinely run.

• 🔌 Zero-Config Agent Integration: Automatically registers with 9+ coding agents with atomic backups and 1-click clean uninstall:

  • Claude Code

  • Cursor

  • Windsurf

  • VS Code & GitHub Copilot

  • Codex CLI

  • Cline / Roo Code

  • OpenCode

  • Google Antigravity

• 🔋 Always-On, Zero Idle Drain: Lightweight stdio MCP shim starts in <1s. Daemon starts lazily on first tool call and automatically resurrects dead backends. Zero background battery drain when idle.

• 🔒 100% Private & Local Loopback: Local servers bind strictly to 127.0.0.1. API keys are stored in user-owned state with restricted permissions (0600) and never leak to agent configs. Zero telemetry.

• 🔄 Safe, Non-Intrusive Updates: snapdec update checks PyPI with a 24-hour cache. Never installs silently or modifies agent files without user consent.

🚀 Quickstart (60 Seconds)

1. Install snapdec

Install using uv (recommended), pipx, or standard pip:

# Recommended: isolated tool installation via uv
uv tool install snapdec

# Or via pipx
pipx install snapdec

# Or standard python pip
pip install snapdec

2. Run the Interactive Setup Wizard

Run snapdec init to profile your system, choose your backend, and auto-wire all detected coding agents:

snapdec init

The wizard scans your hardware and displays an honest, benchmarked menu tailored to your machine:

Recommended for this machine (13th Gen i5 · 16 GB RAM · Intel UHD · Windows 11)

  LOCAL — free · private · offline
    [1] Laya EN (421M)  —  DI ~0 zero-shot (specialize-first base)
        5–15 ms GPU/Apple · 50–450 ms CPU · setup: ~2 GB        (recommended)
    [2] Laya multilingual (322M)  —  DI ~0 zero-shot · 100+ languages
    [3] Decision 2.0 Eos 0.8B  —  card: JevArena 53.9 · transfer 50.3 (vllm-sr)
        setup: ~3 GB · best Decision 2.0 fit for this machine
        CPU: ~7 s/question (bench)                           [slow on CPU]
    [4] Decision 2.0 Kai 0.6B  —  card: JevArena 48.6 · smallest (~2 GB)
        CPU: ~6 s/question (bench)                           [slow on CPU]
    [5] Kev 0.8B  —  DI 23.3 · OOD acc 0.65
        40–80 ms CUDA · fast on Apple (MLX) · CPU: seconds/question
        setup: ~5 GB                                             [slow on CPU]
  HOSTED — API key · best accuracy
    [6] OpenRouter  —  free keys (openrouter.ai/keys) · typesafe/jev-router · Jev DI 54.0
    [7] TypeSafe Jev  —  native /v1/systemone · Jev DI 54.0 (best known) · paid per call
    [8] Other /v1/systemone URL

Choice [1]:

Headless / CI Mode: You can also initialize non-interactively:

snapdec init --yes --backend local             # Auto-select best local model
snapdec init --yes --api-key sk-or-v1-xxxx     # Auto-detect provider & model

🔍 How It Works

┌─────────────────────────────────────────────────────────────┐
│             Coding Agents (Claude Code, Cursor, ...)        │
└──────────────────────────────┬──────────────────────────────┘
                               │ stdio MCP (thin shim, <1s startup)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 snapdec daemon (127.0.0.1 IPC)              │
│       Lazy-start · Health check · Auto-resurrect            │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
    [ Local Inference Engine ]     [ Hosted System One API ]
    • Kev 0.8B / 4B / 9B / 27B     • OpenRouter (jev-router)
    • Laya EN / Multilingual       • TypeSafe Jev
    • Decision 2.0 (vllm-sr)       • Custom /v1/systemone
    • ONNX / PyTorch / MLX

Every response returned to the agent includes calibrated metadata and a discreet status footer:

{
  "results": [
    {"id": "t1", "label": "bug", "p": 0.94, "decision": "auto"},
    {"id": "t2", "label": "infra", "p": 0.61, "decision": "review"}
  ],
  "summary": {
    "items": 2,
    "auto": 1,
    "review": 1
  },
  "status": "· snapdec 0.5.0 · kev-0.8b · 38 ms · 1/2 auto · ~210 tok offloaded"
}

The auto | review Philosophy (Safe Abstention)

• decision: "auto": The model's confidence exceeds the calibrated threshold. The agent can act immediately in batch without asking the user or second-guessing.

• decision: "review": The model's confidence is below threshold or evidence is ambiguous. The agent falls back to inspecting the problem directly.

• Advisory Only: snapdec is strictly an advisory decision engine. It is never used to automatically approve destructive actions (deletions, pushes, migrations).

🧰 Available MCP Tools

When snapdec is registered, agents gain access to 6 specialized tools:

Parallel Fan-Out: Multi-item requests are automatically fanned out concurrently in parallel batches so small-context local models never truncate or bottleneck on large collections.

💻 CLI Usage & Mirrors

All MCP tools have direct CLI counterparts for terminal workflows, shell scripts, and CI pipelines:

# Deterministic repository inspection (Tier 0)
snapdec project-facts .

# Categorize errors or logs from stdin (Tier 1)
echo '{"items":[{"id":"1","text":"ConnectionResetError during upload"}],
       "classes":{"network":"transient socket error","bug":"code bug"}}' \
  | snapdec classify --input -

# Diagnostic health check
snapdec doctor --live

# Update to latest version
snapdec update

# View hardware-gated model catalog
snapdec models

# Run local accuracy and latency benchmark suite
snapdec bench --backend mock

🤖 Supported Coding Agents

snapdec init and snapdec agents add automatically configure all installed agent environments:

To export standard configuration for any other MCP-compliant client:

snapdec agents print-snippet

📊 Models & Benchmarks

snapdec supports both local open weights and hosted router endpoints:

DI (Decision Intelligence) benchmarks cited from the official Kev 1.0 test suite. Measured local performance available in docs/benchmarks/.

(†) Decision 2.0 numbers are from the vendor's model cards (vllm-sr, 2026-10) on their own JevArena index — a different scale from the held-out breadth-v1 numbers above, so the two are never cross-compared (ADR-0008/0010). Measured CPU latency lives in docs/benchmarks/. On Apple Silicon, Decision 2.0 runs via the plain CPU path (no MLX build yet; MPS unvalidated), so Kev 0.8B (MLX) stays the recommended fast local pick there.

(‡) imajev numbers are JevBench board standings (2026-09) and repo runs on their own indices — a third scale, never cross-compared with kev's breadth-v1 or the vllm-sr card (ADR-0008/0011). Measured CPU latency lives in docs/benchmarks/. On Apple Silicon imajev runs a real MLX fast path (fp16), unlike Decision 2.0 there. Downloads show live byte + speed progress bars.

🔒 Security, Privacy & Reliability

• Strict Loopback Binding: Local model servers bind only to 127.0.0.1. No external ports are ever opened.

• Protected Secrets: API keys are saved with strict 0600 file permissions in ~/.local/state/snapdec/ or read from environment variables. They are never written into agent configuration files.

• Fail-Closed Design (NFR-4): If a backend crashes, drops connection, or times out, snapdec returns a valid envelope with decision: "review". It never throws an unhandled exception or interrupts your agent session.

• Zero Telemetry: No usage stats, prompts, code snippets, or user data are ever tracked or phoned home.

🛠️ CLI Command Reference

❓ Frequently Asked Questions (FAQ)

Frontier LLMs incur input token costs for every turn in their conversation history. In agent loops, repeatedly passing long logs, diffs, and lists into a 200k context window to ask small classification or boolean questions consumes significant tokens and compute. snapdec offloads these discrete questions to a local model or fast router, returning only the concise answer and confidence score.

Yes. When you choose a local model (such as Laya or Kev), all dependencies, weights, and runtimes run on your local machine on 127.0.0.1. No internet connection is required after initial model download.

The MCP shim features built-in self-healing: if the daemon is stopped or crashes, the shim automatically re-spawns it on the next incoming tool call. If the backend fails to recover, it returns a safe decision: "review" envelope so the agent continues operating without crashing.

Simply run:

snapdec uninstall

This restores all agent configuration files from their original backups and cleans up registered skills.

📜 Architecture & Decisions

• Architecture Design: SYSONE_ARCHITECTURE.md

• Architectural Decision Records (ADRs):

  • ADR-0001: Shim / Daemon Split

  • ADR-0002: Decision Tiers

  • ADR-0004: IPC Transport

  • ADR-0006: API Key Storage

  • ADR-0007: Rename Gate to snapdec

  • ADR-0008: Kev 1.0 Refresh & Model Catalog

  • ADR-0009: Update Mechanism & Status Footer

  • ADR-0010: Decision 2.0 as Third Local Backend

📄 License

Distributed under the Apache-2.0 License. See LICENSE for details.

snapdec routes to and credits Kev, Laya, TypeSafe Jev, the vllm-sr Decision 2.0 family, and the imajev family (pinned @ ccf586d4). Model weights are distributed under their respective Apache-2.0 licenses.