Intelligent Ollama Model Selector

AI-powered CLI that analyzes your hardware and recommends optimal LLM models.
Deterministic scoring across 200+ dynamic models (35+ curated fallback) with hardware-calibrated memory estimation.

Start Here • Installation • Quick Start • Calibration Quick Start • Docs • Claude MCP • Commands • Scoring • Hardware • Discord

Choosing the right LLM for your hardware is complex. With thousands of model variants, quantization levels, and hardware configurations, finding the optimal model requires understanding memory bandwidth, VRAM limits, and performance characteristics.

LLM Checker solves this. It analyzes your system, scores every compatible model across four dimensions (Quality, Speed, Fit, Context), and delivers actionable recommendations in seconds.

• Docs Hub
• Usage Guide
• Advanced Usage
• Technical Reference
• Changelog
• Calibration Fixtures

LLM Checker and llmfit solve related but different problems:

If your goal is: "What should I run on this exact machine right now?", use LLM Checker first.
If your goal is broader experimentation across custom pipelines, using both tools can be complementary.

# Install globally
npm install -g llm-checker

# Or run directly with npx
npx llm-checker hw-detect

Requirements:

• Node.js 16+ (any version: 16, 18, 20, 22, 24)
• Ollama installed for running models

Optional: For database search features (sync, search, smart-recommend):

npm install sql.js

If you are new, use this exact flow:

# 1) Install
npm install -g llm-checker

# 2) Detect your hardware
llm-checker hw-detect

# 3) Get recommendations by category
llm-checker recommend --category coding

# 4) Run with auto-selection
llm-checker ai-run --category coding --prompt "Write a hello world in Python"

If you already calibrated routing:

llm-checker ai-run --calibrated --category coding --prompt "Refactor this function"

LLM Checker is published in all primary channels:

• npm (latest, recommended): llm-checker@latest
• GitHub Releases: Release history
• GitHub Packages (legacy mirror, may lag): @pavelevich/llm-checker

If you need the newest release, install from npm (llm-checker), not the scoped GitHub Packages mirror.

If you installed @pavelevich/llm-checker and version looks old:

npm uninstall -g @pavelevich/llm-checker
npm install -g llm-checker@latest
hash -r
llm-checker --version

• Calibrated routing is now first-class in recommend and ai-run:
  • --calibrated [file] support with default discovery path.
  • clear precedence: --policy > --calibrated > deterministic fallback.
  • routing provenance output (source, route, selected model).
• New calibration fixtures and end-to-end tests for:
  • calibrate --policy-out ... → recommend --calibrated ...
• Hardened Jetson CUDA detection to avoid false CPU-only fallback.
• Documentation reorganized under docs/ with clearer onboarding paths.

Use this only if you explicitly need GitHub Packages. It may not match npm latest.

# 1) Configure registry + token (PAT with read:packages)
echo "@pavelevich:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> ~/.npmrc

# 2) Install
npm install -g @pavelevich/llm-checker@latest

# 1. Detect your hardware capabilities
llm-checker hw-detect

# 2. Get full analysis with compatible models
llm-checker check

# 3. Get intelligent recommendations by category
llm-checker recommend

# 4. (Optional) Sync full database and search
llm-checker sync
llm-checker search qwen --use-case coding

This path produces both calibration artifacts and verifies calibrated routing in one pass.

cp ./docs/fixtures/calibration/sample-suite.jsonl ./sample-suite.jsonl

mkdir -p ./artifacts
llm-checker calibrate \
  --suite ./sample-suite.jsonl \
  --models qwen2.5-coder:7b llama3.2:3b \
  --runtime ollama \
  --objective balanced \
  --dry-run \
  --output ./artifacts/calibration-result.json \
  --policy-out ./artifacts/calibration-policy.yaml

Artifacts created:

• ./artifacts/calibration-result.json (calibration contract)
• ./artifacts/calibration-policy.yaml (routing policy for runtime commands)

llm-checker recommend --calibrated ./artifacts/calibration-policy.yaml --category coding
llm-checker ai-run --calibrated ./artifacts/calibration-policy.yaml --category coding --prompt "Refactor this function"

Notes:

• --policy <file> has precedence over --calibrated [file].
• If --calibrated has no path, discovery uses ~/.llm-checker/calibration-policy.{yaml,yml,json}.
• --mode full currently requires --runtime ollama.
• ./docs/fixtures/calibration/sample-generated-policy.yaml shows the expected policy structure.

LLM Checker includes a built-in Model Context Protocol (MCP) server, allowing Claude Code and other MCP-compatible AI assistants to analyze your hardware and manage local models directly.

# Install globally first
npm install -g llm-checker

# Add to Claude Code
claude mcp add llm-checker -- llm-checker-mcp

Or generate the exact command directly from the CLI:

llm-checker mcp-setup

Or with npx (no global install needed):

claude mcp add llm-checker -- npx llm-checker-mcp

Restart Claude Code and you're done.

Once connected, Claude can use these tools:

Core Analysis:

Ollama Management:

Advanced (MCP-exclusive):

After setup, you can ask Claude things like:

• "What's the best coding model for my hardware?"
• "Benchmark qwen2.5-coder and show me the tok/s"
• "Compare llama3.2 vs codellama for coding tasks"
• "Clean up my Ollama — what should I remove?"
• "What model should I use for this Rust project?"
• "Optimize my Ollama config for maximum performance"
• "How much RAM is Ollama using right now?"

Claude will automatically call the right tools and give you actionable results.

Running llm-checker with no arguments now opens an interactive panel (TTY terminals):

• animated startup banner
• main command list with descriptions
• type / to open all commands
• use up/down arrows to select a command
• press Enter to execute
• add optional extra flags before run (example: --json --limit 5)

For scripting and automation, direct command invocation remains unchanged:

llm-checker check --use-case coding --limit 3
llm-checker search "qwen coder" --json

Both check and recommend support --policy <file>.

• In audit mode, policy violations are reported but the command exits with 0.
• In enforce mode, blocking violations return non-zero (default 1).
• You can override the non-zero code with enforcement.exit_code in policy.yaml.

Examples:

llm-checker check --policy ./policy.yaml
llm-checker check --policy ./policy.yaml --use-case coding --runtime vllm
llm-checker recommend --policy ./policy.yaml --category coding

recommend and ai-run now support calibration routing policies generated by calibrate --policy-out.

• --calibrated [file]:
  • If file is omitted, discovery defaults to ~/.llm-checker/calibration-policy.{yaml,yml,json}.
• --policy <file> takes precedence over --calibrated for routing resolution.
• Resolution precedence:
  • --policy (explicit)
  • --calibrated (explicit file or default discovery)
  • deterministic selector fallback
• CLI output includes routing provenance (--policy, --calibrated, or default discovery) and the selected route/model.

Examples:

llm-checker recommend --calibrated --category coding
llm-checker recommend --calibrated ./calibration-policy.yaml --category reasoning
llm-checker ai-run --calibrated --category coding --prompt "Refactor this function"
llm-checker ai-run --policy ./calibration-policy.yaml --prompt "Summarize this report"

Use audit export when you need machine-readable compliance evidence for CI/CD gates, governance reviews, or security tooling.

# Single report format
llm-checker audit export --policy ./policy.yaml --command check --format json --out ./reports/check-policy.json

# Export all configured formats (json, csv, sarif)
llm-checker audit export --policy ./policy.yaml --command check --format all --out-dir ./reports

• --command check|recommend chooses the candidate source.
• --format all honors reporting.formats in your policy (falls back to json,csv,sarif).
• In enforce mode with blocking violations, reports are still written before non-zero exit.

# CI artifact (JSON) for post-processing in pipeline jobs
llm-checker audit export --policy ./policy.yaml --command check --format json --out ./reports/policy-report.json

# Flat CSV for SIEM ingestion (Splunk/ELK/DataDog pipelines)
llm-checker audit export --policy ./policy.yaml --command check --format csv --out ./reports/policy-report.csv

# SARIF for security/code-scanning tooling integrations
llm-checker audit export --policy ./policy.yaml --command check --format sarif --out ./reports/policy-report.sarif

name: Policy Gate
on: [pull_request]

jobs:
  policy-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: node bin/enhanced_cli.js check --policy ./policy.yaml --runtime ollama --no-verbose
      - if: always()
        run: node bin/enhanced_cli.js audit export --policy ./policy.yaml --command check --format all --runtime ollama --no-verbose --out-dir ./policy-reports
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: policy-audit-reports
          path: ./policy-reports

check, recommend, and audit export outputs include normalized model provenance fields:

• source
• registry
• version
• license
• digest

If a field is unavailable from model metadata, outputs use "unknown" instead of omitting the field. This keeps downstream parsers deterministic. License values are canonicalized for policy checks (for example MIT License -> mit, Apache 2.0 -> apache-2.0).

llm-checker hw-detect

Summary:
  Apple M4 Pro (24GB Unified Memory)
  Tier: MEDIUM HIGH
  Max model size: 15GB
  Best backend: metal

CPU:
  Apple M4 Pro
  Cores: 12 (12 physical)
  SIMD: NEON

Metal:
  GPU Cores: 16
  Unified Memory: 24GB
  Memory Bandwidth: 273GB/s

llm-checker recommend

Use optimization profiles to steer ranking by intent:

llm-checker recommend --optimize balanced
llm-checker recommend --optimize speed
llm-checker recommend --optimize quality
llm-checker recommend --optimize context
llm-checker recommend --optimize coding

INTELLIGENT RECOMMENDATIONS BY CATEGORY
Hardware Tier: HIGH | Models Analyzed: 205

Coding:
   qwen2.5-coder:14b (14B)
   Score: 78/100
   Command: ollama pull qwen2.5-coder:14b

Reasoning:
   deepseek-r1:14b (14B)
   Score: 86/100
   Command: ollama pull deepseek-r1:14b

Multimodal:
   llama3.2-vision:11b (11B)
   Score: 83/100
   Command: ollama pull llama3.2-vision:11b

llm-checker search llama -l 5
llm-checker search coding --use-case coding
llm-checker search qwen --quant Q4_K_M --max-size 8

LLM Checker prioritizes the full scraped Ollama model cache (all families/sizes/variants) and falls back to a built-in curated catalog when cache is unavailable.

The curated fallback catalog includes 35+ models from the most popular Ollama families (used only when the dynamic scraped pool is unavailable):

All available models are automatically combined with locally installed Ollama models for scoring.

Models are evaluated across four dimensions, weighted by use case:

Three scoring systems are available, each optimized for different workflows:

Deterministic Selector (primary — used by check and recommend):

Scoring Engine (used by smart-recommend and search):

All weights are centralized in src/models/scoring-config.js.

Memory requirements are calculated using calibrated bytes-per-parameter values:

The selector automatically picks the best quantization that fits your available memory.

For MoE models, deterministic memory estimation supports explicit sparse metadata when present:

• total_params_b
• active_params_b
• expert_count
• experts_active_per_token

Normalized recommendation variants expose both snake_case and camelCase metadata aliases (for example: total_params_b + totalParamsB) when available.

MoE parameter path selection is deterministic and uses this fallback order:

1. active_params_b (assumption source: moe_active_metadata)
2. total_params_b * (experts_active_per_token / expert_count) (assumption source: moe_derived_expert_ratio)
3. total_params_b (assumption source: moe_fallback_total_params)
4. Model paramsB fallback (assumption source: moe_fallback_model_params)

Dense models continue to use the dense parameter path (dense_params) unchanged.

When active_params_b (or a derived active-ratio path) is available, inference memory uses the sparse-active parameter estimate even if artifact size metadata is present.

MoE speed estimates now include runtime-specific overhead assumptions (routing, communication, offload), instead of using a single fixed MoE boost.

• Canonical helper: src/models/moe-assumptions.js
• Applied in both:
  • src/models/deterministic-selector.js
  • src/models/scoring-engine.js

Current runtime profiles:

Recommendation outputs now expose these assumptions through runtime metadata and MoE speed diagnostics.

LLM Checker uses a deterministic pipeline so the same inputs produce the same ranked output, with explicit policy outcomes for governance workflows.

flowchart LR
  subgraph Inputs
    HW["Hardware detector<br/>CPU/GPU/RAM/backend"]
    REG["Dynamic Ollama catalog<br/>(curated fallback if unavailable)"]
    LOCAL["Installed local models"]
    FLAGS["CLI options<br/>use-case/runtime/limits/policy"]
  end

  subgraph Pipeline["Selection Pipeline"]
    NORMALIZE["Normalize and deduplicate model pool"]
    PROFILE["Hardware profile and memory budget"]
    FILTER["Use-case/category filtering"]
    QUANT["Quantization fit selection"]
    SCORE["Deterministic 4D scoring<br/>Q/S/F/C"]
    POLICY["Policy evaluation (optional)<br/>audit or enforce"]
    RANK["Rank and explain candidates"]
  end

  subgraph Outputs
    REC["check / recommend output"]
    AUDIT["audit export<br/>JSON / CSV / SARIF"]
    RUN["pull/run-ready commands"]
  end

  REG --> NORMALIZE
  LOCAL --> NORMALIZE
  HW --> PROFILE
  FLAGS --> FILTER
  FLAGS --> POLICY
  NORMALIZE --> FILTER
  PROFILE --> QUANT
  FILTER --> QUANT
  QUANT --> SCORE
  SCORE --> POLICY
  SCORE --> RANK
  POLICY --> RANK
  RANK --> REC
  POLICY --> AUDIT
  RANK --> RUN

• Input layer: Collects runtime constraints from hardware detection, local inventory, dynamic registry data, and CLI flags.
• Normalization layer: Deduplicates identifiers/tags and builds a canonical candidate set.
• Selection layer: Filters by use case, selects the best fitting quantization, and computes deterministic Q/S/F/C scores.
• Governance layer: Applies policy rules in audit or enforce mode and records explicit violation metadata.
• Output layer: Returns ranked recommendations plus machine-readable compliance artifacts when requested.

1. Hardware profiling: Detect CPU/GPU/RAM and effective backend capabilities.
2. Model pool assembly: Merge dynamic scraped catalog (or curated fallback) with locally installed models.
3. Candidate filtering: Keep only relevant models for the requested use case.
4. Fit selection: Choose the best quantization for available memory budget.
5. Deterministic scoring: Score each candidate across quality, speed, fit, and context.
6. Policy + ranking: Apply optional policy checks, then rank and return actionable commands.

Detect your hardware:

llm-checker hw-detect

Get recommendations for all categories:

llm-checker recommend

Full system analysis with compatible models:

llm-checker check

Find the best coding model:

llm-checker recommend --category coding

Search for small, fast models under 5GB:

llm-checker search "7b" --max-size 5 --use-case fast

Get high-quality reasoning models:

llm-checker smart-recommend --use-case reasoning

git clone https://github.com/Pavelevich/llm-checker.git
cd llm-checker
npm install
node bin/enhanced_cli.js hw-detect

src/
  models/
    deterministic-selector.js  # Primary selection algorithm
    scoring-config.js          # Centralized scoring weights
    scoring-engine.js          # Advanced scoring (smart-recommend)
    catalog.json               # Curated fallback catalog (35+ models, only if dynamic pool unavailable)
  ai/
    multi-objective-selector.js  # Multi-objective optimization
    ai-check-selector.js        # LLM-based evaluation
  hardware/
    detector.js                # Hardware detection
    unified-detector.js        # Cross-platform detection
  data/
    model-database.js          # SQLite storage (optional)
    sync-manager.js            # Database sync from Ollama registry
bin/
  enhanced_cli.js              # CLI entry point

LLM Checker is licensed under NPDL-1.0 (No Paid Distribution License).

• Free use, modification, and redistribution are allowed.
• Selling the software or offering it as a paid hosted/API service is not allowed without a separate commercial license.

See LICENSE for full terms.

GitHub • Releases • npm • GitHub Packages • Issues • Discord