cantino/mcfly: a ctrl-r replacement that ranks shell history with a small neural network

The problem McFly targets: ctrl-r that ignores where you are

Default reverse history search matches a substring against a flat, chronological list. That works until you have months of history from several projects, at which point the same short command (a test runner, a deploy script, a git invocation) appears many times and the most recent match is not the one you want. McFly's premise, stated in the README, is that the command you want is usually the one you ran in this directory, after a similar command, and that succeeded. It rebinds ctrl-r, opens a full-screen search, and orders results by those signals instead of by recency alone. The audience is anyone who lives in a terminal across more than one repository and has stopped trusting ctrl-r. It is not aimed at people who want a fuzzy finder over files, or at shells outside the supported set.

How the ranking works: SQLite plus a small neural network

McFly keeps a SQLite database alongside your normal shell history file, and the README lists what it stores per command: exit status, timestamp and execution directory. The README also states that the normal history file is maintained in parallel, so the tool is additive rather than a replacement for the file your shell already writes. Ranking is described as running in real time through a small neural network, and the README enumerates the inputs: the directory the command ran in, the commands typed before it, how often it runs, when it last ran, whether you have selected it in McFly before, and its historical exit status. Note that this is a scoring model, not a search index: the README does not describe how the network is trained, where the weights live, or how to inspect a score, so the ordering is something you observe rather than audit. The Rust crate list includes rusqlite with the bundled SQLite feature enabled by default, which means the binary carries its own SQLite rather than linking the system one. One search affordance is documented explicitly: typing % matches any number of characters.

Installing McFly and running your first search

The README gives several install paths. On macOS or Linux, Homebrew is the shortest. This installs the binary only; the shell integration is a separate step.

brew install mcfly

Then append the init line for your shell to the end of its startup file. For Zsh the README shows this exact line:

eval "$(mcfly init zsh)"

Bash uses eval "$(mcfly init bash)" and Fish uses mcfly init fish | source. On Windows the README points at WinGet with winget install AndrewCantino.McFly, and then Invoke-Expression -Command $(mcfly init powershell | Out-String) added to $PROFILE, with the caveat that the project does not maintain that install script and cannot vouch for its accuracy or safety. MacPorts is also supported through sudo port install mcfly. If you prefer building it yourself, the README requires Rust 1.40 or later, then git clone, cd, and cargo install --path . with ~/.cargo/bin on your PATH. There is also a curl install script: curl -LSfs https://raw.githubusercontent.com/cantino/mcfly/master/ci/install.sh | sh -s -- --git cantino/mcfly.

After reloading the shell, press ctrl-r. You should get a full-screen list rather than the shell's built-in search. Type a fragment to filter, use % where you want a wildcard, and press enter to run the highlighted command. The README mentions a scrub action that removes a history item from both the McFly database and your shell history files, which is the one destructive operation worth knowing about before you start. If you use iTerm2, the README warns that McFly's UI can interfere with scrollback unless a specific iTerm2 option is unchecked, and points to docs/iterm2.jpeg for which one.

Where McFly gets in the way

The most concrete limitation is maintenance. The README opens with a request for co-maintainers, saying the author does not have much time for the project. The last push to the repository was on 2026-09-01, so the code is not abandoned, but the stated intent is that someone else should help carry it. A second issue is the ranking itself. Because suggestions come from a neural network, a wrong guess is hard to explain and, per the README, there is no documented way to inspect or adjust the weights. If you want deterministic ordering that you can predict, this is the wrong tool. Third, shell coverage is bounded: Zsh, Bash 3+ and PowerShell 7+, plus Fish in the install instructions. A shell outside that list gets nothing. Fourth, the Windows path runs through a WinGet package the README explicitly disclaims, so Windows users are relying on a script the project will not vouch for. Finally, McFly writes a database of your commands, their directories and their exit statuses. That is a more sensitive artifact than a plain history file, and the README does not discuss encryption or where exactly the database lives beyond the fact that it exists.

McFly against fzf and plain history expansion

The obvious comparison is fzf wired into ctrl-r. fzf is a general-purpose fuzzy finder that ranks by match quality against the text you type; it has no notion of your working directory, no record of exit status, and no model of what you ran previously. It is also transparent: given the same input list and query, you can reason about why one line outranks another. McFly inverts both properties. It reads richer signals and produces an order you cannot fully reconstruct, and it owns the history store rather than filtering a file you already have. The other comparison is the shell's own history expansion and ctrl-r, which cost nothing and add no database. If your history is short or your work happens in one directory, that baseline is probably enough, and McFly's extra machinery buys you little. McFly is the better fit when directory and context are the signals you are missing, and the worse fit when predictability matters more than relevance.

Upgrade cost, the MIT licence and the co-maintainer question

The project is MIT licensed, which permits commercial and closed-source use, modification and redistribution provided the copyright notice and permission notice are kept. That is the whole of the licence implication here; nothing in the repository suggests a different arrangement, and nothing in it constitutes legal advice. Upgrades are simple in practice: Homebrew, MacPorts and cargo install all replace the binary in place, and the shell integration is regenerated each time the shell starts because the init line calls mcfly init on every startup. That means the init output comes from whichever binary is on your PATH, so a stale binary and a new shell config can disagree. The database schema is the part to watch across versions, since it is the only persistent state; the README does not document a migration path or a rollback procedure, so keeping a copy of the database before a major version jump is the cautious move. The version in Cargo.toml is 0.9.4, matching the most recent release. The more serious cost is organisational: with the README asking for co-maintainers, anyone who standardises a team on McFly is betting on a project that has publicly said it needs help.

Editorial conclusion

Adopt McFly if you work in many directories and your ctrl-r results keep surfacing commands that belong to a different project; the directory and context signals are the part you cannot get from history expansion alone. Skip it if you want a search box you can reason about, since the ranking comes from a neural network and the README does not describe how to inspect or tune the weights, and skip it if you need an actively developed project: the README asks for co-maintainers and the last push was on 2026-09-01. Before rolling it out, add the init line to one shell, run a few commands, and confirm that mcfly's own history database and your normal history file both receive entries, so that removing the init line returns you to your previous setup.

Frequently asked questions

Official sources

1. cantino/mcfly on GitHub
2. Issues
3. License: MIT
4. README
5. Releases