TUI Guide

Everything about llmfit's interactive terminal UI: navigation, planning, simulation, configuration, downloads, the community leaderboard, benchmarking, themes, and the web dashboard.

← Back to README

TUI (default)

llmfit

Launches the interactive terminal UI. Your system specs (CPU, RAM, GPU name, VRAM, backend) are shown at the top. Models are listed in a scrollable table sorted by composite score. Each row shows the model's score, estimated tok/s, best quantization for your hardware, run mode, memory usage, and use-case category.

Vim-like modes

The TUI uses Vim-inspired modes shown in the bottom-left status bar. The current mode determines which keys are active.

Normal mode

The default mode. Navigate, search, filter, and open views. All keys in the table above apply here.

Visual mode (v)

Select a contiguous range of models for bulk comparison. Press v to anchor at the current row, then navigate with j/k or arrow keys to extend the selection. Selected rows are highlighted.

The multi-compare view displays a table where rows are attributes (Score, tok/s, Fit, Mem%, Params, Mode, Context, Quant, etc.) and columns are models. Best values are highlighted. Use h/l or arrow keys to scroll horizontally if more models are selected than fit on screen.

Select mode (V)

Column-based actions. Press V (shift-v) to enter Select mode, then use h/l or arrow keys to move between column headers. The active column is visually highlighted. Press Enter or Space to trigger that column's current action.

Row navigation still works in Select mode so you can see the effect of actions as you apply them: j/k, arrow keys, Ctrl-U, Ctrl-D, PageUp, PageDown, Home, and End. Press Esc to return to Normal mode.

TUI Plan mode (p)

Plan mode inverts normal fit analysis: instead of asking "what fits my hardware?", it estimates "what hardware is needed for this model config?".

Use p on a selected row, then:

Plan mode shows estimates for:

• minimum and recommended VRAM/RAM/CPU cores
• feasible run paths (GPU, CPU offload, CPU-only)
• upgrade deltas to reach better fit targets

Hardware Simulation (S)

Press S to open the hardware simulation popup. Override RAM, VRAM, and CPU core count to see which models would fit on different target hardware. All model scores, fit levels, and speed estimates are recalculated instantly against the simulated specs.

When simulation is active, a SIM badge appears in the system bar and status bar. The entire model table reflects the simulated hardware until you reset.

Advanced Configuration (A)

Press A to open the Advanced Configuration popup. This panel lets you tune the parameters behind TPS estimation, run mode penalties, and composite scoring — addressing issue #449 where tok/s was overestimated for certain models (e.g., Qwen3 30B).

All changes are applied immediately and the model table is recalculated. Close with Esc to accept or Ctrl-R to reset to defaults.

Download Manager (D)

Press D to open the Download Manager view. This full-screen view replaces the main model table and provides three sections:

• Active Download — shows the current download in progress with a progress bar, model name, and status message.
• Config — displays (and allows editing) the GGUF models directory. The configured path persists across sessions.
• History — a navigable list of past downloads (newest first) with model name, provider, status, and date. Failed downloads can be removed from history, and successful downloads can be deleted from the provider.

Use Tab / Shift-Tab to cycle focus between sections.

For failed downloads (e.g. 404 errors), x removes the entry from history. For successful downloads, it deletes the model from the provider (supported for Ollama and llama.cpp).

Community Leaderboard (b)

Press b to open the Community Leaderboard view. Instead of relying solely on llmfit's theoretical speed estimates, this view shows real-world performance data from other users with the same hardware — actual measured tok/s, time-to-first-token, and peak VRAM usage.

Data is sourced from localmaxxing.com, a community benchmark database. When you open the view, llmfit auto-detects your hardware (GPU model, VRAM tier, Apple Silicon chip family, OS) and queries for matching results.

Press H to open the hardware picker — a scrollable list of 27 popular GPUs and chips (RTX 5090 through CPU-only, plus Apple Silicon M1–M4 variants, AMD RX/MI series, and NVIDIA datacenter cards). Select one to instantly load benchmarks for that hardware, even if it's not what you're running on. Select "My Hardware (auto-detect)" to go back to your own system.

API key setup

Public benchmarks work without authentication. For full access, provide your localmaxxing.com API key:

# Via environment variable (recommended)
export LOCALMAXXING_API_KEY="bhk_your_key_here"
llmfit

# Or via CLI flag
llmfit --api-key "bhk_your_key_here"

Inference Bench (I)

Press I (uppercase) to open the Inference Bench view. This runs live inference benchmarks against your locally running providers — Ollama, vLLM, and MLX — measuring time-to-first-token (TTFT), tokens per second (TPS), and total latency with real inference requests.

Unlike the Community Leaderboard (which shows crowd-sourced data from other users), Inference Bench measures your actual hardware with your actual models.

TUI usage

Results are cached to ~/.config/llmfit/bench-cache.json and loaded instantly on subsequent opens.

CLI usage

# Auto-detect provider and benchmark
llmfit bench

# Benchmark all discovered models across all running providers
llmfit bench --all

# Benchmark a specific model via Ollama
llmfit bench --provider ollama llama3.2

# Override endpoint URL
llmfit bench --provider ollama --url http://my-server:11434 llama3.2

# Override vLLM endpoint
llmfit bench --provider vllm --url http://localhost:8000

# Output as JSON (for scripting)
llmfit bench --json

# Run quality benchmarks (role-based scoring for routing)
llmfit bench --quality

# Output routing matrix
llmfit bench --quality --routing

Environment variables

Themes

Press t to cycle through 10 built-in color themes. Your selection is saved automatically to ~/.config/llmfit/theme and restored on next launch.

Web dashboard

When you run llmfit in non-JSON mode, it automatically starts a background web dashboard on 0.0.0.0:8787. Open it in any browser on the same network:

http://<your-machine-ip>:8787

Override the host or port with environment variables:

LLMFIT_DASHBOARD_HOST=0.0.0.0 LLMFIT_DASHBOARD_PORT=9000 llmfit

To disable the auto-started dashboard, pass --no-dashboard:

llmfit --no-dashboard