McFly — Fly Through Your Shell History with Context-Aware Search

Introduction

Default Ctrl-R reverse-i-search sorts purely by recency, which means that as your history grows, the command you actually want drifts further and further away. McFly replaces Ctrl-R with a small neural network that ranks past commands by recency plus current directory, time-of-day, and historical exit status, surfacing what you're most likely to want right now.

What McFly Does

• Intercepts Ctrl-R in bash, zsh, and fish.
• Builds a SQLite database of your shell history with metadata.
• Scores candidates via a lightweight neural net on each keystroke.
• Highlights the matching substring and previews directory context.
• Syncs with standard HISTFILE, keeping native history intact.

Architecture Overview

On shell init, McFly wraps history commands and logs every executed line into ~/.local/share/mcfly/history.db along with cwd, exit code, timestamp. When invoked, a Rust TUI reads stdin each keystroke, re-scores the top-N candidates with a trained model, and prints the selected command back via readline.

Self-Hosting & Configuration

• Install via brew, cargo, apt, dnf, or release binary.
• Database lives at ~/.local/share/mcfly/history.db — portable across machines.
• MCFLY_RESULTS sets how many matches to show.
• MCFLY_KEY_SCHEME=vim switches to Vi-style editing.
• MCFLY_INTERFACE_VIEW=BOTTOM places the TUI at the bottom of the screen.

Key Features

• Neural ranking uses directory + exit status + age.
• TUI preview of 10+ candidates, not a single match.
• Fuzzy substring matching with highlight.
• Portable SQLite db — rsync your history across machines.
• No external dependencies; ~5MB Rust binary.

Comparison with Similar Tools

• Atuin — sync across machines via server; heavier. McFly is local-first.
• fzf-history — fuzzy but no ranking model, no directory context.
• zsh-autosuggestions — inline suggestion, not a full search UI.
• HSTR — C-based ranker; slower startup, less polished UI.
• bash-preexec + custom — DIY, no ML ranking.

FAQ

Q: Does the neural net run on every keystroke? A: Yes but it's tiny — <1ms per 1000 candidates.

Q: Will it erase my history? A: No. It reads your existing HISTFILE on first run, then appends to both.

Q: Works with fish? A: Yes — mcfly init fish | source.

Q: Can I clear a command from the db? A: Select it then press F2 to delete.

Sources

• https://github.com/cantino/mcfly