mcfly

Batch 8.

What it is

mcfly replaces the shell’s ctrl-r reverse-history search with a full-screen overlay that presents a ranked result list — and the ranking is the point. A small neural network scores candidates using context: which directory you’re in, what you ran just before, how often and how recently you ran a command, whether it previously succeeded (failed commands sink), and which suggestions you’ve actually picked before. You type, results re-rank live, you select one and it lands on the command line. It keeps the normal shell history file intact alongside its SQLite store, so it’s reversible.

This is the command-palette / fuzzy-launcher pattern at its most sophisticated — not just “filter a list” but “rank a list by what’s likely given where I am and what I’m doing.” For KN-86 it’s the reference for any command-palette surface (the REPL’s history recall, a CIPHER command recall, a mission-action quick-picker) where ranking should beat raw recency.

UI / layout / interaction

• Full-screen overlay that takes over the terminal, anchored TOP (default) or BOTTOM (MCFLY_INTERFACE_VIEW). A single custom prompt character is configurable (MCFLY_PROMPT).
• Ranked result list, default 30 rows (MCFLY_RESULTS), sortable by RANK or LAST_RUN (MCFLY_RESULTS_SORT). Each row is a candidate command with its match shown in context.
• Live re-ranking as you type — the list reorders on every keystroke as the score updates, not just filters down.
• Inline delete of bad history entries from within the overlay (MCFLY_DELETE_WITHOUT_CONFIRM to skip the prompt) — the search UI is also a curation UI.
• % wildcard matches any run of characters; optional fuzzy mode (MCFLY_FUZZY, 2–5 recommended).

Rendering — monochrome-adaptable

• Ranked list with highlighted match text: the matched substring of each result is emphasized so you see why it ranked. mcfly does this with color; KN-86 does it with inversion or bold on the matched run — the more robust channel on one color.
• Score as information: ranking is the core signal, and it’s conveyed by order (top = best) plus optionally a visible score. Order is a spatial channel — survives monochrome completely. A literal score column can render as a right-aligned number or a ▰▰▰▱▱ bar (Unicode block density), no color needed.
• MCFLY_LIGHT flips light/dark — confirms the UI is palette-swappable, which is the minimum bar for KN-86’s amber-on-black target.

Navigation / keybindings

• emacs (default) or vim key scheme (MCFLY_KEY_SCHEME) — selectable editing model inside the overlay, a good precedent for KN-86 letting operators pick their in-overlay edit grammar.
• Type to search; results re-rank; select to accept; delete to curate. MCFLY_DISABLE_MENU strips to a non-interactive mode.
• Bound by eval "$(mcfly init zsh|bash)"; Linux 6.2+ has a configurable binding workaround (MCFLY_BASH_SEARCH_KEYBINDING).

Libraries

• Rust + SQLite — the history DB carries each command’s exit status, timestamp, and execution directory (the ranking features). DB at platform-specific paths (~/.local/share/mcfly/history.db on Linux).
• Small embedded neural network scoring candidates in real time — notably, the model is tiny enough to run per-keystroke in a shell hook. That “tiny model, real-time, on-device ranking” profile is the interesting bit for a constrained device.

Architecture

• Augmented history store: every command logged with its context (dir, exit status, time) — the ranking is only possible because the store captures more than the command string. The architectural lesson for KN-86: if you want smart recall, log context at capture time, not just the payload. A KN-86 REPL/command history that records the surface, the deck state, and success/failure alongside each entry can later rank recall the way mcfly does.
• Context-aware ranking factors: directory, prior command, frequency, recency, prior selections, exit status. The exit-status factor (“don’t resurface old failed commands”) is a sharp, cheap heuristic.
• Reversible by design: keeps the native shell history so you can stop using it anytime — a graceful-degradation principle worth keeping for any KN-86 system that augments a plain store.
• Config in config.toml (color settings live here); env-var-driven for most behavior.

Single-color adaptation

• Full-screen ranked overlay ports cleanly: a framed (box-drawing) panel, /-or-custom prompt at the anchored edge, ranked rows below, matched substring inverted, the cursor row inverted or caret-marked. The whole thing is order + inversion + box-drawing — no hue.
• Score visualization without color: rank is communicated by position first; if an explicit score helps, render it as a Unicode block-density bar (▰▰▰▱▱) or braille meter in a right-aligned column — the single-color brightness/density channel doing the work color would otherwise do. This block-density-as-magnitude trick is broadly reusable across KN-86 (signal strength, progress, confidence).
• Match highlight = inversion, shared grammar with clipse.md’s filter and mynav.md’s search overlay — standardize “matched text inverts” as the KN-86 search convention.

LISP angle

KN-86’s headline interaction is an on-device Lisp REPL (TERM key, per-deck history persistence — see the runtime REPL spec and ADR-0002/ADR-0016). mcfly is the directly relevant reference for that REPL’s history recall: instead of a dumb recency ctrl-r, the REPL could rank prior s-expressions by context — current cart, current surface, whether the form last evaluated without error (mcfly’s exit-status factor → “don’t resurface forms that errored”), and prior reuse. The mcfly architecture (augmented store logging context at capture, tiny on-device ranker) is a concrete model for a context-aware Lisp-history recall that fits a constrained device. This is the strongest cross-link between the command-palette pattern and KN-86’s Lisp-first identity in the whole batch.

Notes

• The command-palette / ranked-recall reference for KN-86 — pair the interaction (full-screen overlay, live re-rank, match-highlight) with the architecture (log context at capture; rank, don’t just filter).
• Block-density-as-magnitude (▰▰▰▱▱) for score/confidence display is a single-color rendering idiom worth lifting into KN-86’s UI-pattern library generally.
• Cross-link clipse.md and mynav.md (the list-with-preview + fuzzy-overlay family — mcfly is the ranked member), and l123.md for the keyboard-first command-driven lineage.