/ollama-optimizer

name: ollama-optimizer
description: "Optimize Ollama configuration for the current machine's hardware. Use when asked to speed up Ollama, tune local LLM performance, or pick models that fit available GPU/RAM. Don't use for LM Studio, llama.cpp, vLLM, or hosted-API LLM providers."
license: MIT
effort: medium
metadata:
  version: 1.3.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Ollama Optimizer

Optimize Ollama configuration based on system hardware analysis.

When to Use

Use this skill when the user asks to optimize Ollama, configure Ollama, speed up Ollama, fix Ollama running slow, set up a local LLM, tune inference speed, reduce memory usage, or select models that fit their GPU/RAM. The skill analyzes hardware (GPU, VRAM, RAM, CPU) and produces tailored recommendations.

Do not use for LM Studio, llama.cpp, vLLM, or hosted-API LLM providers (OpenAI, Anthropic) — those use different runtimes and tuning surfaces.

Safety Rules

• Phases 1 and 2 are read-only. They run `scripts/detect_system.py`, `ollama --version`, `ollama list`, and `ollama ps`, and they change nothing.
• An **applied change** is any write to the machine: an env-var write, a service or app restart, `ollama pull`, a Modelfile `ollama create`, or any `sudo` command. Before each applied change, show its exact command and wait for the user's yes for that change.
• Saving the guide to the path the user chose is not an applied change.
• If the user asks for recommendations only, apply nothing and deliver the guide. A recommendations-only request is not a decline.
• Back up each config location before the first write to it (*Choose where the env vars go*).
• Never delete a model, and never run `ollama rm`. List oversized models in the guide instead.
• Never set `OLLAMA_HOST=0.0.0.0` unless the user asks for network access. If they ask, warn that it exposes the Ollama API to the network without authentication.

Workflow

**Fast path (opt-in only):** only skip full hardware analysis if the user explicitly asks to. Otherwise always run Phases 1-4 and follow the tier-based recommendation — do not apply shortcuts by default, and do not let them override a tier decision already made. For the per-platform shortcut commands and env vars, see [Platform-Specific Setup](references/platform_specific.md) and [Environment Variables](references/environment_variables.md).

Phase 1: System Detection

Run the detection script to gather hardware information:

python3 scripts/detect_system.py

The script prints JSON on stdout and exits 0. On an unexpected failure it prints `Error: ...` on stderr and exits 1. If it exits 1, show that message, follow its fix hint, and run it once more. If the second run also exits 1, stop with `BLOCKED` (*Final Report*).

Parse the JSON output to identify:

• OS and version
• CPU model and core count
• Total RAM / unified memory
• GPU type, VRAM, and driver version
• Current Ollama installation and environment variables
• `hardware_tier` — the script's computed `category`, `max_model_size`, and `recommended_quant`

If `ollama.installed` is `false`, continue to Phase 2. The plan then starts with the install step from [Platform-Specific Setup](references/platform_specific.md). Installing Ollama is an applied change.

Phase 2: Analyze and Recommend

Use `hardware_tier` from Phase 1 as the tier decision. Do not re-derive it; the table below explains what each tier means and which optimizations it implies. Override the script only with an explicit reason (e.g. VRAM shared with a display), and state that reason in the report.

**Unknown VRAM.** The script tiers a GPU only from `vram_gb`. An AMD ROCm GPU, an NVIDIA GPU whose VRAM reads `[N/A]`, and the Windows WMIC fallback report no `vram_gb`, so the script returns `low_vram`. An Intel Mac with a discrete GPU reports an empty `gpu` list, so the script returns `cpu_only`. In these cases, ask the user for the VRAM size. If they give it, override the tier from the table and state the reason. If they do not, keep the script's tier and list it under `Uncertainty:` as a conservative tier.

**Hardware Tier Classification:**

| Tier (`category`) | Script band | Max Model | Key Optimizations | |------|----------|-----------|-------------------| | `cpu_only` | No GPU detected | 3B | num_thread tuning, Q4_K_M quant | | `low_vram` | <6GB VRAM | 3B | Flash attention, KV cache q4_0 | | `entry` | 6-10GB VRAM | 8B | Flash attention, KV cache q8_0 | | `prosumer` | 10-16GB VRAM | 14B | Flash attention, full offload | | `workstation` | 16-48GB VRAM | 32B | Standard config, Q5_K_M option | | `high_end` | 48GB+ VRAM | 70B+ | Multiple models, Q5/Q6 quants |

**Apple Silicon Special Case:**

• Unified memory = shared CPU/GPU RAM; the script tiers it directly from total unified memory
• 8GB Mac → `entry`
• 16GB Mac → `prosumer`
• 32GB Mac → `workstation`; 64GB+ Mac → `high_end`

**Nothing to change.** `current_env_vars` shows only the environment the script ran in. For `Ollama.app` or the systemd service, also read the values Ollama uses (`launchctl getenv VAR`, `systemctl show ollama -p Environment`). If every recommended env var already has the recommended value there and every installed model fits the tier, the guide says so and the run proposes no applied change.

Phase 3: Generate Optimization Plan

Read [Report Templates](references/report-template.md), then create the guide with these sections:

1. System Overview

Present detected hardware specs and highlight constraints (e.g., "8GB unified memory limits to 8B models").

2. Dependency Assessment

List what's needed based on the platform:

• macOS: Ollama only (Metal automatic)
• Linux NVIDIA: Ollama + NVIDIA driver 450+
• Linux AMD: Ollama + ROCm 5.0+
• Windows: Ollama + NVIDIA driver 452+

3. Configuration Recommendations

**Essential environment variables:**

# Always recommended
export OLLAMA_FLASH_ATTENTION=1

# Memory-constrained systems (<12GB)
export OLLAMA_KV_CACHE