umn - Async File Finder in Zig 0.16

A fast, interactive fuzzy file finder built with Zig 0.16's new std.Io interface.

Quick Start

# Build (Debug)
zig build

# Build (optimized)
zig build -Doptimize=ReleaseFast

# Install to a prefix (puts binary under <prefix>/bin)
zig build -Doptimize=ReleaseFast -p ~/.local
# or manually copy the staged artifact
cp zig-out/bin/umn ~/.local/bin/

# Run (current directory)
umn

# Run (specific directory, supports ~ expansion)
umn ~/projects

Running Tests

# Run all tests (silent on success)
zig build test

# Run tests with detailed feedback
zig build test --summary all

# Format code (recommended before committing)
zig fmt .

Artifacts are staged under zig-out/ by default. When installing to a prefix, ensure <prefix>/bin is in your PATH (e.g. ~/.local/bin).

Usage

Once running, use:

• Type to filter files
• ↑/↓ arrow keys to navigate
• Enter to select a file
• Backspace to delete query characters
• Esc or Ctrl-C to exit

Requirements

• Zig 0.16.0 or later
• Unix-like system (Linux, macOS, BSD) or Windows
• Terminal with ANSI escape code support

Verify your Zig version:

zig version

Architecture

src/
├── main.zig       # Entry point & file collection
├── fuzzy.zig      # Fuzzy matching algorithm
├── terminal.zig   # Terminal control & raw mode
└── ui.zig         # Interactive UI loop

The fuzzy matching algorithm adapts sequence alignment techniques from computational biology, particularly the Smith-Waterman algorithm (1981) for local sequence alignment, which established the scoring approach used in modern fuzzy finders.

Related Projects

• zio - Full async I/O framework for Zig
• fzf - The original fuzzy finder (Go)
• skim - Fuzzy finder in Rust

Resources

• Zig Documentation
• std.Io API Reference