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

> McFly replaces the default Ctrl-R reverse search in bash/zsh/fish with a neural-ranked, context-aware history finder that considers directory, exit status, and recency.

## Install

Save as a script file and run:

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

## Quick Use
```bash
brew install mcfly
# bash
echo 'eval "$(mcfly init bash)"' >> ~/.bashrc
# zsh
echo 'eval "$(mcfly init zsh)"' >> ~/.zshrc
# Press Ctrl-R — start typing, best match wins
```

## 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

---
Source: https://tokrepo.com/en/workflows/bc4f7f6d-389d-11f1-9bc6-00163e2b0d79
Author: Script Depot