High-performance fuzzy matcher implementing Smith–Waterman with affine gaps; Unicode-grapheme aware, ASCII-optimized, aggressive prefiltering and fast heuristic fallback for very long matches.
This is a Kotlin Multiplatform line-by-line transliteration port of helix-editor/nucleo.
Original Project: This port is based on helix-editor/nucleo. All design credit and project intent belong to the upstream authors; this repository is a faithful port to Kotlin Multiplatform with no behavioural changes intended.
This is an in-progress port. The goal is feature parity with the upstream Rust crate while providing a native Kotlin Multiplatform API. Every Kotlin file carries a // port-lint: source <path> header naming its upstream Rust counterpart so the AST-distance tool can track provenance.
helix-editor/nucleoThe text below is reproduced and lightly edited from
https://github.com/helix-editor/nucleo. It is the upstream project's own description and remains under the upstream authors' authorship; links have been rewritten to absolute upstream URLs so they continue to resolve from this repository.
nucleo is a highly performant fuzzy matcher written in Rust. It aims to fill the same use case as fzf and skim. Compared to fzf nucleo has a significantly faster matching algorithm. This mainly makes a difference when matching patterns with low selectivity on many items. An (unscientific) comparison is shown in the benchmark section below.
Note: If you are looking for a replacement of the
fuzzy-matchercrate and not a fully managed fuzzy picker, you should use thenucleo-matchercrate.
uses the exact . That means you should get the same ranking quality (or better) as you are used to from fzf. However, has a more faithful implementation of the Smith-Waterman algorithm which is normally used in DNA sequence alignment (see ) with two separate matrices (instead of one like fzf). This means that finds the optimal match more often. For example if you match in will match but will match (you can increase the word length the result will stay the same). The former is the more intuitive match and has a higher score according to the ranking system that both and fzf.
Compared to skim (and the fuzzy-matcher crate) nucleo has an even larger performance advantage and is often around six times faster (see benchmarks below). Furthermore, the bonus system used by nucleo and fzf is (in my opinion) more consistent/superior. nucleo also handles non-ascii text much better. (skims bonus system and even case insensitivity only work for ASCII).
Nucleo also handles Unicode graphemes more correctly. Fzf and skim both operate on Unicode code points (chars). That means that multi codepoint graphemes can have weird effects (match multiple times, weirdly change the score, ...). nucleo will always use the first codepoint of the grapheme for matching instead (and reports grapheme indices, so they can be highlighted correctly).
Nucleo is used in the helix-editor and therefore has a large user base with lots of real world testing. The core matcher implementation is considered complete and is unlikely to see major changes. The nucleo-matcher crate is finished and ready for widespread use, breaking changes should be very rare (a 1.0 release should not be far away).
While the high level nucleo crate also works well (and is also used in helix), there are still additional features that will be added in the future. The high level crate also need better documentation and will likely see a few API changes in the future.
WIP currently more of a demonstration than a comprehensive benchmark suit most notably scientific comparisons with
fzfare missing (a pain because it can't be called as a library)
Benchmark comparing the runtime of various patterns matched against all files in the source of the linux kernel. Repeat on your system with BENCHMARK_DIR=<path_to_linux> cargo run -p benches --release (you can specify an empty directory and the kernel is cloned automatically).
For example in the following two screencasts the pattern ///. is pasted into fzf and nucleo (both with about 3 million items open).
fzf takes a while to filter the text (about 1 second) while nucleo has barely any noticeable delay (a single frame in the screencast so about 1/30 seconds). This comparison was made on a very beefy CPU (Ryzen 5950x) so on slower systems the difference may be larger:
fzf (mostly --no-sort and --tac)The name nucleo plays on the fact that the Smith-Waterman algorithm (that it's based on) was originally developed for matching DNA/RNA sequences. The elements of DNA/RNA that are matched are called nucleotides which was shortened to nucleo here.
The name also indicates its close relationship with the helix editor (sticking with the DNA theme).
This is only intended for those interested and will not be relevant to most people. I plan to turn this into a blog post when I have more time
The fuzzy matching algorithm is based on the Smith-Waterman (with affine gaps) as described in https://www.cs.cmu.edu/~ckingsf/bioinfo-lectures/gaps.pdf (TODO: explain). Nucleo faithfully implements this algorithm and therefore has two separate matrices. However, by precomputing the next m-matrix row we can avoid storing the p-matrix at all and instead just store the value in a variable as we iterate the row.
Nucleo also never really stores the m-matrix instead we only ever store the current row (which simultaneously serves as the next row). During index calculation a full matrix is however required to backtrack which indices were actually matched. We only store two bools here (to indicate where we came from in the matrix).
By comparison skim stores the full p and m matrix in that case. fzf always allocates a full mn matrix (even during matching!).
nucleos' matrix is only width n-m+1 instead of width n. This comes from the observation that the p char requires p-1 chars before it and m-p chars after it, so there are always p-1 + m-p = m+1 chars that can never match the current char. This works especially well with only using a single row because the first relevant char is always at the same position even though it's technically further to the right. This is particularly nice because we precalculate the m-matrix row. The m-matrix is computed from diagonal elements, so the precalculated values stay in the same matrix cell.
Compared to skim nucleo does couple simpler (but arguably even more impactful) optimizations:
dependencies {
implementation("io.github.kotlinmania:nucleo-kotlin:0.1.1")
}
./gradlew build
./gradlew test
See AGENTS.md and CLAUDE.md for translator discipline, port-lint header convention, and Rust → Kotlin idiom mapping.
This Kotlin port is distributed under the same MPL-2.0 license as the upstream helix-editor/nucleo. See LICENSE (and any sibling LICENSE-* / NOTICE files mirrored from upstream) for the full text.
Original work copyrighted by the nucleo authors.
Kotlin port: Copyright (c) 2026 Sydney Renee and The Solace Project.
Thanks to the helix-editor/nucleo maintainers and contributors for the original Rust implementation. This port reproduces their work in Kotlin Multiplatform; bug reports about upstream design or behavior should go to the upstream repository.
nucleonucleonucleofooxf foonucleox__foofzfxf_oonucleo| Method | Mean | Samples |
|---|
| nucleo "never_matches" | 2.30 ms | 2,493/2,500 |
| skim "never_matches" | 17.44 ms | 574/574 |
| nucleo "copying" | 2.12 ms | 2,496/2,500 |
| skim "copying" | 16.85 ms | 593/594 |
| nucleo "/doc/kernel" | 2.59 ms | 2,499/2,500 |
| skim "/doc/kernel" | 18.32 ms | 546/546 |
| nucleo "//.h" | 9.53 ms | 1,049/1,049 |
| skim "//.h" | 35.46 ms | 282/282 |
chars, so cache locality is improved a lot, and we can use memchar for superfast prefilters (even case-insensitive prefilter are possible that way)O(N) (and O(1) space complexity) to avoid the O(mn) blowup for large matches. This is fzfs old algorithm and yields decent (but not great) results.Surfaced from shared tags and platforms — no rankings paid for.