# Understanding corrector.py in the thefuck Architecture: The Correction Engine Explained

> Explore corrector.py the core engine of thefuck. Discover how it parses commands, applies rules, and generates prioritized correction suggestions for fixing shell errors efficiently.

- Repository: [Vladimir Iakovlev/thefuck](https://github.com/nvbn/thefuck)
- Tags: internals
- Published: 2026-02-27

---

**corrector.py serves as the central engine in thefuck that transforms parsed shell commands into prioritized correction suggestions by discovering rules, filtering enabled ones, and generating deduplicated fixes.**

The `thefuck` project by nvbn is a command-line tool that corrects errors in previous console commands. At the heart of this system lies [`thefuck/corrector.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/corrector.py), a module that bridges configuration, rule discovery, and correction generation to deliver intelligent suggestions.

## What Is corrector.py in the thefuck Architecture?

corrector.py acts as the orchestration layer between three critical components: configuration management, rule discovery mechanisms, and the actual correction generation pipeline. It transforms raw shell command data into actionable fixes by applying a series of user-defined and built-in rules.

The module exposes several key functions that handle everything from importing rule paths to organizing final suggestions by priority. Unlike the UI layer or individual rule implementations, corrector.py focuses exclusively on the logistics of finding and applying corrections.

## The Three-Layer Pipeline: How corrector.py Fits In

The architecture of thefuck divides responsibilities into distinct layers, with corrector.py serving as the glue between them.

### Configuration Layer

The configuration layer, managed through [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py), defines where rules live and which settings govern their behavior. Within corrector.py, the `get_rules_import_paths()` function queries these settings to build a comprehensive list of directories that might contain rule modules.

This function checks both the built-in `thefuck/rules` package and any user-defined directories specified in the configuration, ensuring that third-party extensions are discovered alongside core functionality.

### Rule Discovery Layer

Once paths are identified, `get_loaded_rules()` takes over to transform file paths into executable `Rule` objects. This function iterates through the discovered paths, uses `Rule.from_path` to load each module, and filters the results to include only rules where `rule.is_enabled` evaluates to true.

The Rule objects encapsulate the logic for matching specific error patterns and generating appropriate corrections, acting as the primary units of work within the correction pipeline.

### Correction Generation Layer

The final layer handles the actual transformation of commands into suggestions. The `get_corrected_commands()` function accepts a `Command` object and iterates through all enabled rules. For each rule, it checks `rule.is_match(command)` to determine applicability, then calls `rule.get_corrected_commands(command)` to yield potential fixes.

After collecting suggestions, the function passes them to `organize_commands()`, which removes duplicates, sorts them by the originating rule's `priority` attribute, and returns a generator of `CorrectedCommand` objects ready for presentation.

## Key Functions in corrector.py

Understanding the internal mechanics of corrector.py requires examining its primary functions in detail.

### get_rules_import_paths()

This function constructs the search path for rule modules. It combines the default rules directory with any additional paths specified in the user configuration, returning a list of directories that `get_loaded_rules()` will scan.

### get_loaded_rules()

Responsible for module instantiation, this function loads Python files from the discovered paths and converts them into `Rule` instances. It performs the critical filtering step that excludes disabled rules before they enter the correction pipeline.

### get_corrected_commands()

The core processing function that accepts a `Command` object and produces corrections. It orchestrates the matching and generation process across all enabled rules, yielding a stream of potential fixes that require further organization.

### organize_commands()

This utility function handles post-processing of suggestions. It deduplicates corrections that might come from multiple rules, sorts them according to rule priority, and prepares the final output format that the UI layer consumes.

## From Failed Command to Fix: A Practical Example

To see corrector.py in action, consider a typical usage scenario where a user mistypes a git command.

```python
from thefuck.types import Command
from thefuck.corrector import get_corrected_commands

# Simulate a failed 'git comit' command

cmd = Command(
    script='git comit',
    stdout='',
    stderr="git: 'comit' is not a git command. See 'git --help'.",
    return_code=1
)

# Generate correction suggestions

suggestions = list(get_corrected_commands(cmd))

for suggestion in suggestions:
    print(f"Suggested fix: {suggestion.command}")

```

When executed, corrector.py loads all enabled rules from `thefuck/rules` and any user-defined directories. It checks each rule's `is_match` method against the command, finds that the git-related rules match the typo pattern, and generates `git commit` as a corrected command. The `organize_commands` function ensures that if multiple rules suggest the same fix, only the highest-priority version appears in the final output.

## Summary

- **corrector.py** serves as the central orchestration engine in the thefuck architecture, bridging configuration, rule discovery, and correction generation.
- The module discovers rules through `get_rules_import_paths()` and instantiates them via `get_loaded_rules()`, filtering for enabled rules only.
- It generates suggestions using `get_corrected_commands()`, which matches commands against rules and yields potential fixes.
- Final output is processed by `organize_commands()` to remove duplicates and sort by rule priority before presentation to the user.
- Located at [`thefuck/corrector.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/corrector.py), this module works closely with [`thefuck/types.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/types.py) for data structures and [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) for configuration management.

## Frequently Asked Questions

### What does corrector.py do in thefuck?

corrector.py functions as the core correction engine that transforms failed shell commands into actionable fix suggestions. It discovers available rules, filters for enabled ones, matches them against the input command, and generates a prioritized list of corrections for the user interface to display.

### How does corrector.py load custom rules?

The module uses `get_rules_import_paths()` to build a search path that includes both the built-in `thefuck/rules` directory and any user-defined directories specified in the configuration. `get_loaded_rules()` then scans these paths, loads each Python module, and creates `Rule` objects using `Rule.from_path`, ensuring only enabled rules enter the pipeline.

### What is the difference between Rule and CorrectedCommand in thefuck?

A `Rule` object represents the logic for detecting specific error patterns and generating fixes, containing methods like `is_match()` and `get_corrected_commands()`. A `CorrectedCommand` represents a concrete suggestion produced by applying a rule to a specific failed command, containing the corrected script string and metadata about which rule generated it.

### How does corrector.py prioritize correction suggestions?

After generating potential fixes, `organize_commands()` processes the stream of suggestions to remove duplicates. It then sorts the remaining commands based on the `priority` attribute of the originating rule, ensuring that higher-priority rules (typically more specific or reliable fixes) appear first in the final output presented to the user.