How to Filter llmfit Results by Fit Level Using the CLI

Use the --min-fit flag on the recommend sub-command to filter llmfit results by fit level, accepting values perfect, good, marginal (default), or tootight.

The llmfit CLI provides built-in filtering capabilities that let you control recommendation quality directly from the command line. Each model evaluation receives a FitLevel classification based on hardware compatibility, and you can use this classification to narrow results before applying additional filters like runtime or use case constraints.

Understanding Fit Levels in llmfit

In llmfit-core/src/fit.rs (lines 75-84), the FitLevel enum defines four quality tiers:

// From llmfit-core/src/fit.rs
pub enum FitLevel {
    Perfect,    // Optimal hardware match
    Good,       // Strong compatibility with minor trade-offs
    Marginal,   // Acceptable but suboptimal fit (default threshold)
    TooTight,   // Resource constraints likely
}

The FitLevel represents how well a specific model matches your detected hardware configuration. Higher tiers indicate better predicted performance and reliability.

The --min-fit CLI Option

The filtering mechanism is implemented in llmfit-tui/src/main.rs. Lines 551-553 declare the argument:

// From llmfit-tui/src/main.rs (lines 551-553)
#[arg(long, value_name = "LEVEL", default_value = "marginal")]
min_fit: String,

When you invoke llmfit recommend, the run_recommend function parses this string and applies the filter at lines 1340-1350, mapping your input to the FitLevel enum and discarding any models below your specified threshold.

Filter Behavior by Level

--min-fit value	Models retained
perfect	Only Perfect fits
good	Perfect + Good
marginal	Perfect + Good + Marginal (default)
any other value	Treated as marginal

The fit level filter applies first in the recommendation pipeline, ensuring downstream runtime, capability, and use-case filters only operate on models meeting your quality baseline.

Practical CLI Examples

Filter llmfit results by fit level using these common patterns:

# Show top 5 recommendations, minimum "good" quality

llmfit recommend --limit 5 --min-fit good

# Strictest quality: only perfect hardware matches, JSON output

llmfit recommend --limit 5 --min-fit perfect --json

# Default marginal threshold with runtime and limit constraints

llmfit recommend --min-fit marginal --runtime vllm --limit 10

# Combine with GPU-specific filtering

llmfit recommend --min-fit good --runtime llama-cpp --use-case chat

How the Filtering Logic Works

The run_recommend function in llmfit-tui/src/main.rs handles the conversion and filtering in two stages:

1. Parse: The input string is matched against FitLevel variants (case-insensitive)
2. Filter: The vector of ModelFit objects is reduced to retain only models where fit_level >= min_fit

This approach leverages Rust's enum ordering, treating higher variants as more desirable. The filtered results then proceed through remaining pipeline stages.

API Equivalence

If you need the same filtering via HTTP, the llmfit-tui/src/serve_api.rs file implements an equivalent min_fit query parameter for the serve mode, maintaining consistent behavior across interfaces.

Summary

• Primary method: Add --min-fit <LEVEL> to any llmfit recommend command
• Valid levels: perfect, good, marginal (default), tootight
• Implementation location: llmfit-tui/src/main.rs in the run_recommend function (lines 1340-1350)
• Core enum definition: llmfit-core/src/fit.rs lines 75-84
• Filter precedence: Executed before runtime, use-case, or capability filters

Frequently Asked Questions

What happens if I provide an invalid --min-fit value?

Invalid values default to marginal. The parser in llmfit-tui/src/main.rs falls back to this safe baseline rather than failing, ensuring you still receive usable recommendations.

Does --min-fit affect performance or just output?

The filter only affects output—it reduces the recommendation list returned to your terminal or API client. All models are still evaluated; the flag simply controls which results you see.

Can I filter by exact fit level instead of minimum?

No. The CLI implements minimum threshold filtering only (greater-than-or-equal logic). To see only Perfect matches, use --min-fit perfect. To exclude Marginal results, use --min-fit good or higher.

Is the fit level calculation customizable?

The scoring logic in llmfit-core/src/fit.rs determines fit levels based on hardware detection and model requirements. These thresholds are fixed in the source code; customization requires modifying the core library and rebuilding.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}