GO — Healthy across all four use cases

• 46+ active contributors
• Distributed ownership (top contributor 32% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

The Fuck is a Python CLI tool that automatically detects and corrects errors in recently-executed shell commands by matching them against a library of ~100 rule-based correctors (apt_get, git, brew, etc.). It intercepts the last command's stderr/stdout, applies pattern-matching rules, and presents one or more corrected alternatives for interactive selection before re-execution. Monolithic structure: thefuck/ package contains core engine, rules/ subdirectory holds 80+ rule modules (each a simple dict with 'match' and 'get_corrected_commands' functions), entrypoints/ provides shell integration points (alias install, fix_command), and shells/ adapters wrap bash/zsh/fish/tcsh initialization. Tests mirror this: tests/rules/ has one test per rule file, tests/functional/ validates shell-specific behavior end-to-end.

DevOps engineers, sysadmins, and developers who frequently typo or mistype shell commands (e.g., forgetting sudo, misspelling git branch, missing required flags) and want instant, interactive corrections without manual research.

Production-ready and actively maintained. The project has ~38k stars on GitHub, comprehensive test coverage across bash/zsh/fish/tcsh shells (tests/functional/test_*.py), CI/CD via GitHub Actions (.github/workflows/test.yml), and demonstrates sustained development with rules for 80+ command-line tools. Code is stable with Python 3.5+ support established.

Low risk for core functionality, moderate risk for shell integration. Single maintainer (nvbn) could delay responses, but no critical dependencies beyond Python stdlib + pexpect (test harness). Risk surfaces in shell-specific integration: each shell adapter (bash/zsh/fish/tcsh) has separate test suites that must pass, and shell initialization order can silently break command detection. PowerShell/Batch support is less mature (scripts/fuck.ps1, scripts/fuck.bat are minimal).

Repo shows active maintenance: GitHub Actions workflow (test.yml) runs on push/PR, setup.py and requirements.txt indicate Python 3.5+ focus, and Dockerfile/.devcontainer/ suggest recent DevOps tooling updates. No visible breaking changes in recent commits, but 'instant mode' experimental feature (referenced in README) suggests performance optimization work underway.

git clone https://github.com/nvbn/thefuck && cd thefuck && pip install -e . && fuck --help. For development: pip install -r requirements.txt && pytest tests/ to validate test suite. Shell integration: eval "$(thefuck --alias)" in your shell rc file.

Daily commands: thefuck --alias to print shell integration. eval "$(thefuck --alias)" in ~/.bashrc or ~/.zshrc, then type any command, hit enter to trigger error, type 'fuck' to trigger correction. For testing: pytest tests/rules/test_apt_get.py (unit), pytest tests/functional/test_bash.py (shell integration).

• thefuck/rules/: Contains 80+ individual rule modules (apt_get.py, git_.py, brew_.py, etc.)—each rule is the core intelligence for correcting a specific command-line tool
• thefuck/shells/: Shell adapter layer (bash.py, zsh.py, fish.py, tcsh.py)—bridges thefuck binary with shell initialization; hooks into shell history and aliases to intercept failed commands
• thefuck/entrypoints/: CLI entry points for 'thefuck' alias and 'fuck' command; orchestrates rule matching, user interaction, and command execution
• tests/rules/: One test file per rule (test_apt_get.py, test_git_*.py, etc.); validates match() and get_corrected_commands() logic for each tool
• tests/functional/: End-to-end shell integration tests (test_bash.py, test_zsh.py, test_fish.py, test_tcsh.py) using pexpect to spawn actual shells and verify alias behavior
• setup.py: Defines package metadata, console_scripts entry points, and Python version requirement (3.5+); fastentrypoints.py optimizes startup time
• .github/workflows/test.yml: CI/CD config; runs pytest across all test suites and validates shell integration on each push/PR

To add a new correction rule: create tests/rules/test_your_tool.py (follow pattern in test_apt_get.py, test_git_* files), then create thefuck/rules/your_tool.py with @for_app('your_tool') decorator, match(command) and get_corrected_commands(command) functions. To modify shell integration: edit thefuck/shells/*.py (bash.py, zsh.py, fish.py, tcsh.py). To change CLI behavior: edit thefuck/entrypoints/ files.

Shell initialization order is brittle—thefuck relies on shell alias or function being sourced after PATH setup and history configuration; if user's .bashrc or .zshrc is malformed, alias won't load silently. pexpect tests require pseudo-terminal support (PTY), so they fail in CI without proper Docker/container setup (see tests/Dockerfile). Rule matching is sequential and first-match-wins, so rule load order in thefuck/rules/init.py matters. instant_mode feature is experimental and may be unstable. PowerShell and Batch scripts (scripts/.ps1, scripts/.bat) are minimal stubs and lack feature parity with Unix shells.

• Rule-based Pattern Matching Engine — Thefuck's core: each rule module defines match(command) to detect a command type via regex/string inspection and get_corrected_commands() to generate fixes; understanding this pattern is essential to adding new rules or debugging why a correction isn't triggered
• Shell Integration via Init Files and Aliases — Thefuck doesn't patch the shell binary; instead it registers itself as an alias/function in .bashrc/.zshrc/.config/fish/config.fish—understanding shell initialization order and how shells load functions is critical for debugging integration failures
• PTY (Pseudo-Terminal) I/O and pexpect — The functional tests use pexpect to spawn real shell processes and interact via PTY—understanding PTY semantics (blocking reads, terminal modes, signal handling) is necessary for debugging test failures and adding new shell adapter code
• Command Exit Codes and stderr/stdout Capture — Thefuck detects errors by inspecting command exit code and stderr/stdout output; rule matching depends on parsing these signals correctly—misunderstanding how shells capture and report command output leads to broken rules
• Console Entry Points and pkg_resources — setup.py uses console_scripts entry point to register 'thefuck' and 'fuck' commands on PATH—understanding setuptools entry points is key to modifying CLI structure or adding new command aliases
• Cross-Shell Compatibility (bash/zsh/fish/tcsh) — Each shell has different syntax for aliases, functions, history access, and event hooks; rules must be shell-agnostic but integration code must account for these differences—adding a new shell adapter requires understanding its initialization and command-line argument parsing
• Decorator Pattern for Tool-Specific Rule Registration — Rules use @for_app('git') and @for_app('apt-get') decorators to register match logic—understanding Python decorators and thefuck's rule discovery mechanism (via init.py imports) is necessary to understand how the correct rule is selected at runtime

• jlevy/the-art-of-command-line — Companion guide teaching shell best practices and troubleshooting—context for the problems The Fuck solves
• junegunn/fzf — Interactive fuzzy command-line finder often used with thefuck for exploring corrected command options via TUI
• ajcr/under-os — Alternative tool targeting similar use case (correcting shell typos) but with rule-based approach instead of AI/NLP
• tldr-pages/tldr — Companion reference for simplified command man pages—users often consult after thefuck corrects a command to understand flags
• cli/cli — GitHub CLI (gh) increasingly integrates command suggestions and auto-correct, overlapping thefuck's goal for git/GitHub workflows

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive rule tests for output_readers and expand test coverage

The tests/output_readers directory only contains test_rerun.py, suggesting incomplete test coverage for output reading functionality. The codebase likely has other output reader implementations that lack corresponding tests. This is critical for a tool that parses shell output to ensure correctness across different scenarios.

• [ ] Audit thefuck/output_readers/ directory to identify all output reader implementations
• [ ] Create corresponding test files in tests/output_readers/ for each reader (e.g., test_stdout.py, test_stderr.py if they exist)
• [ ] Add parametrized tests covering edge cases: empty output, multiline output, special characters, and different shell encodings
• [ ] Ensure test coverage reaches >90% for output_readers module using pytest-cov

Implement missing functional shell tests and cross-shell compatibility

The tests/functional/ directory has tests for bash, fish, tcsh, and zsh, but the test structure suggests potential gaps. Given that thefuck supports multiple shells, there should be more comprehensive cross-shell validation tests, particularly around edge cases in command parsing and rule application across different shell syntaxes.

• [ ] Review tests/functional/conftest.py to understand the test harness setup
• [ ] Add parametrized shell tests in tests/functional/ that run the same test cases across all supported shells (bash, zsh, fish, tcsh)
• [ ] Create tests/functional/test_shell_compatibility.py for cross-shell edge cases (e.g., history handling, quote escaping, variable expansion)
• [ ] Add tests using pytest-docker-pexpect (already in dependencies) for real shell integration scenarios

Add GitHub Actions workflow for testing Windows compatibility and add corresponding rule tests

The repo has scripts/fuck.bat and scripts/fuck.ps1 for Windows, plus setup.py supporting Windows, but .github/workflows/test.yml likely only tests Linux. Additionally, there are no visible test files for Windows-specific rules. Adding Windows CI and comprehensive rule tests for Windows commands would ensure the tool works reliably on Windows systems.

• [ ] Review .github/workflows/test.yml to confirm Windows testing is absent
• [ ] Create .github/workflows/test-windows.yml with Windows-specific test matrix using windows-latest runner
• [ ] Add tests/rules/test_windows_*.py files for Windows-specific correction rules (PowerShell, batch, Windows-native commands)
• [ ] Test scripts/fuck.bat and scripts/fuck.ps1 execution paths in the Windows CI workflow

• Add missing test coverage for rules/aws_cli.py, rules/az_cli.py, and other cloud CLI rules (tests/rules/test_aws_cli.py exists but test_az_cli.py is minimal)—expand to cover more error patterns those CLIs emit
• Write integration tests for the instant_mode feature mentioned in README.md and example_instant_mode.gif but not covered in tests/functional/ or tests/rules/—add a test_instant_mode.py to validate performance and correctness
• Improve PowerShell support by expanding scripts/fuck.ps1 to match bash/zsh feature parity—currently minimal, could add shell integration similar to thefuck/shells/bash.py logic

The codebase presents a moderate security posture. Primary concerns include loose dependency version constraints (especially setuptools >=17.1 which is extremely outdated) and lack of clear separation between production and development dependencies. The project lacks visible automated security scanning in CI/CD pipelines. No evidence of hardcoded secrets, injection vulnerabilities, or significant infrastructure misconfigurations was detected in the provided file structure. Immediate remediation should focus on pinning dependency versions and implementing automated vulnerability scanning.

• Medium · Dependency Version Pinning Not Enforced — requirements.txt. The requirements.txt file does not specify exact versions for dependencies. This allows for potential installation of newer versions with unknown vulnerabilities. Dependencies like setuptools, pytest, pexpect, and others lack version constraints. Fix: Pin all dependencies to specific versions using == operator (e.g., 'setuptools==17.1' instead of 'setuptools>=17.1'). Regularly audit and update pinned versions after security testing.
• Medium · Loose setuptools Version Constraint — requirements.txt, setup.py. setuptools is specified as '>=17.1', which is a very old version (from 2015). This constraint allows installation of any newer version including those with unpatched vulnerabilities. setuptools is a critical build tool. Fix: Update to setuptools>=65.0 and pin to a specific recent stable version. Regularly review setuptools security advisories.
• Low · Testing Dependencies in Production Context — requirements.txt. Test dependencies (pytest, pytest-mock, pytest-benchmark, mock) are listed in requirements.txt without clear separation between development and production dependencies. This could lead to accidental inclusion in production deployments. Fix: Separate test dependencies into requirements-dev.txt or use setup.py extras_require. Ensure production installations exclude testing packages.
• Low · No Security Update Mechanism Documented — .github/workflows/test.yml (inferred). No evidence of automated dependency scanning tools (e.g., Dependabot, Snyk) in CI/CD configuration visible in the repository structure. The project may not catch security vulnerabilities in dependencies proactively. Fix: Implement automated dependency scanning in GitHub Actions using tools like Dependabot or integrate with Snyk. Enable security alerts and auto-patching for critical vulnerabilities.
• Low · Installation Script Not Audited — install.sh. The install.sh script is present in the repository but its contents were not provided for review. Shell installation scripts can present security risks if they execute commands without proper validation. Fix: Review install.sh for: proper error handling, validation of downloaded content, use of HTTPS URLs, no execution of arbitrary code, proper permission handling. Consider providing checksums for verification.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nvbn/thefuck shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nvbn/thefuck repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nvbn/thefuck.

What it runs against: a local clone of nvbn/thefuck — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nvbn/thefuck | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 689 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nvbn/thefuck. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nvbn/thefuck.git
#   cd thefuck
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nvbn/thefuck and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nvbn/thefuck(\\.git)?\\b" \\
  && ok "origin remote is nvbn/thefuck" \\
  || miss "origin remote is not nvbn/thefuck (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 689 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~659d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nvbn/thefuck"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.