Project 14: Interactive Fuzzy Finder (Full fzf Clone)

A complete interactive fuzzy finder with: terminal UI, incremental input, parallel matching with worker goroutines, result streaming, preview pane.

Quick Reference

Attribute Value
Primary Language Go
Alternative Languages Rust, C++
Difficulty Level 3: Advanced
Time Estimate 3-4 weeks
Knowledge Area TUI / Concurrency
Tooling Custom Implementation
Prerequisites Project 13, terminal programming basics

What You Will Build

A complete interactive fuzzy finder with: terminal UI, incremental input, parallel matching with worker goroutines, result streaming, preview pane.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Terminal UI (raw mode, escape sequences) → maps to TUI rendering
  • Incremental search (update as you type) → maps to debouncing and cancellation
  • Parallel matching → maps to worker pools and result merging
  • Streaming large inputs → maps to handling unbounded data

Key Concepts

  • Terminal Raw Mode: Reading characters without waiting for Enter
  • ANSI Escape Codes: Cursor movement, colors, clearing
  • Worker Goroutines: Parallel matching with cancellation
  • Result Merging: Combining ranked results from multiple workers

Real-World Outcome

$ find . -type f | ./mini_fzf
[Interactive TUI appears]

> src/ma
  4/1234
  > src/main.rs
    src/matcher.go
    src/main_test.go
    src/map.rs

Features:
- Type to filter
- Arrow keys to navigate
- Enter to select
- Ctrl-C to cancel
- Preview pane (--preview) shows file content

Performance:
- 100K items loaded in 50ms
- Typing latency <10ms (feels instant)
- Matches update incrementally as you type

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: TEXT_SEARCH_TOOLS_DEEP_DIVE.md
  • fzf source code