What Is the Purpose of the `--perfect` Flag in llmfit?

The --perfect flag in llmfit filters the output of the fit sub-command to show only models whose hardware fit level is "Perfect"—meaning their RAM/VRAM requirements exactly match or comfortably exceed the detected system specs.

llmfit analyzes how well Large Language Model (LLM) configurations align with your machine's available resources. The tool assigns every model a fit level on a tiered scale: Perfect > Good > Marginal > TooTight. This ranking helps users quickly identify which models will run optimally versus those that might strain or exceed hardware limits. The --perfect flag provides a targeted view of only the top-tier matches.

How the --perfect Flag Works

The flag is implemented as a boolean CLI argument in the Clap definition for the fit sub-command. You can find this in llmfit-tui/src/main.rs within the Commands::Fit variant.

When you invoke llmfit fit --perfect, the core analysis pipeline proceeds through these stages:

1. Analysis: ModelFit::analyze() evaluates all models against detected hardware specs
2. Filtering: The filter::perfect_only function retains only entries with fit_level == FitLevel::Perfect
3. Rendering: Results display sorted by score, limited to perfect matches

This filter operates on the fit_level field of each ModelFit instance, as defined in llmfit-core/src/fit.rs.

Behavior Comparison

Scenario	Without --perfect	With --perfect
Models shown	All compatible models regardless of fit quality	Only models with Perfect fit level
Ranking	Sorted by score, includes Good/Marginal/TooTight entries	Sorted by score, restricted to optimal matches
Best used for	Exploring full compatibility range	Finding ideal hardware matches quickly

Practical Usage Examples

Show All Compatible Models (Default)

# List top 10 models of any fit level

llmfit fit -n 10

Show Only Perfect-Fit Models

# List top 5 models with optimal hardware match

llmfit fit --perfect -n 5

Combine with Other Options

# Limit context window and filter to perfect matches

llmfit --max-context 8192 fit --perfect -n 3

The flag composes naturally with global options like --max-context and standard flags like -n (limit results).

Key Implementation Files

Understanding the --perfect flag requires familiarity with these source files:

• llmfit-tui/src/main.rs — Defines the Clap CLI structure and wires the --perfect boolean flag to the fit sub-command execution
• llmfit-core/src/fit.rs — Contains the FitLevel enum (Perfect, Good, Marginal, TooTight) and the filter::perfect_only logic that enforces the flag's behavior
• docs/cli.md — Documents command-line usage patterns including --perfect examples
• README.md — Provides quick-start examples demonstrating typical --perfect workflows

When to Use --perfect

Use this flag when you want to:

• Eliminate noise by hiding suboptimal matches
• Prioritize stability by selecting models with guaranteed headroom
• Automate selection in scripts that need reliable, non-marginal candidates
• Benchmark confidently knowing hardware limits won't throttle performance

Skip the flag when exploring edge cases, testing borderline configurations, or investigating why a seemingly compatible model receives a lower fit score.

Summary

• The --perfect flag restricts llmfit fit output to models with FitLevel::Perfect hardware compatibility
• Implementation spans llmfit-tui/src/main.rs (CLI definition) and llmfit-core/src/fit.rs (filter logic)
• Without the flag: all fit levels shown; with the flag: optimal matches only
• Combines with standard options like -n and --max-context for precise result control

Frequently Asked Questions

What fit levels does llmfit recognize?

llmfit evaluates models against four tiers: Perfect (ideal match), Good (comfortable fit), Marginal (tight but functional), and TooTight (exceeds available resources). These are defined in the FitLevel enum in llmfit-core/src/fit.rs.

Does --perfect affect how models are scored or just displayed?

The flag only filters displayed results. The underlying ModelFit::analyze() method computes scores and fit levels identically regardless of flags. The filter::perfect_only function applies after analysis completes.

Can I use --perfect with other sub-commands besides fit?

No. The --perfect flag is defined exclusively for the fit sub-command in llmfit-tui/src/main.rs. Other sub-commands like list or info do not expose this option.

What makes a model "Perfect" versus "Good"?

A Perfect fit means the model's RAM and VRAM requirements fall comfortably within detected hardware with substantial headroom. Good fits still run reliably but with less margin for system overhead or memory spikes. The exact thresholds are computed in the core analysis logic.

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