# fzy ALGORITHM.md

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | fuzzy-matching-selectors |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | fzy ALGORITHM.md |
| Source URL | https://github.com/jhawthorn/fzy/blob/master/ALGORITHM.md |
| Source publisher / author | jhawthorn (fzy maintainer) |
| Source type | repository |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-25 |
| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
| Research method | direct page fetch |
| Confidence | Medium |
| Status | Active |

## Summary

The design note of fzy, a terminal fuzzy selector. It frames fuzzy scoring as a modified edit-distance problem solved with a dynamic program, and compares fzy to other finders. The page names the bonuses and penalties but the fetched text carries no numeric values or complexity analysis.

## Key findings

- Scoring is treated as a modified edit distance related to Levenshtein, with dynamic programming similar to Wagner-Fischer and Needleman-Wunsch.
- The matrix is n-by-m (search length by candidate length); an affine gap penalty inspired by the Gotoh algorithm is used.
- A second matrix D holds the best score which ends in a match, computed alongside the score matrix.
- Penalties (negative): gaps at the start of the match, at the end, and inside the match. Bonuses (positive): consecutive match, after a slash, start of a word (after space, underscore or dash), a capital letter (CamelCase), after a dot.
- Comparison: fzf takes the first match with some logic to find a shorter one but is not guaranteed shortest; ctrlp, pick and selecta (<= 0.0.6) score by the length of the first match; pick can find the absolute shortest match at a speed cost; selecta master compares only the shortest match from the same start; fuzzaldrin-plus uses Smith-Waterman.
- Stated limitations: every search is case-insensitive (scoring favors uppercase matches; smart case is suggested), and the page says fuzzy matching only accepts insertions, not deletions or substitutions.

## Pros / strengths

A clear statement of the model (consecutive + word-start + camelCase bonuses, gap penalties) and a useful comparison of why first-match and shortest-match schemes misrank.

## Cons / limitations / caveats

No constants and no complexity in the fetched text; the recurrences live in src/match.c. The Command-t section is marked incomplete by the author. Not a measured evaluation, a design note.

## Relevance to tai

Gave the bonus taxonomy and the D/M two-matrix recurrence structure that tai's `FuzzyMatcher::Subsequence` follows. Constants were taken from fzf instead (see the fzf-algo-go dossier) because they were actually retrieved.

## Changelog

| Date | Change |
|---|---|
| 2026-10-25 | Initial dossier created. |