peco — Interactive Filtering Tool for the Unix Pipeline

Introduction

peco is a simplistic interactive filtering tool inspired by Percol. It reads lines from standard input, presents them in an interactive interface where you can type to filter, then outputs the selected line. It fits naturally into Unix pipelines and works with any text-producing command.

What peco Does

• Reads lines from stdin and presents an interactive selection interface in the terminal
• Supports fuzzy matching, regular expression, and exact match modes
• Allows multi-line selection for batch operations
• Outputs selected lines to stdout for downstream pipeline consumption
• Provides customizable keybindings and display options via JSON configuration

Architecture Overview

peco is a single Go binary that creates a full-screen terminal UI using escape sequences. Input lines are indexed in memory and filtered in real time as the user types a query. The matching engine supports multiple algorithms (fuzzy, regexp, prefix) and can be switched at runtime. Selected output goes to stdout while the UI renders on stderr, keeping the Unix pipeline contract intact.

Self-Hosting & Configuration

• Install via Homebrew, apt, pacman, or build from source with Go
• Configuration lives in ~/.config/peco/config.json
• Customize keybindings, default matcher, colors, and prompt style
• Define custom filter modes and external command integrations
• No daemon or background process required; runs only when invoked

Key Features

• Single static binary with no runtime dependencies
• Switchable match modes: fuzzy, regex, and exact match (toggle with Ctrl-R)
• Multi-select with Ctrl-Space for choosing multiple lines at once
• Custom actions that pipe selected lines to external commands
• Fast startup and low memory usage even with large input sets

Comparison with Similar Tools

• fzf — more widely adopted fuzzy finder with preview support and shell integration; peco is simpler with a different keybinding philosophy
• percol — Python predecessor that inspired peco; peco is faster due to Go implementation
• skim — Rust-based fzf alternative; faster than peco in benchmarks but similar workflow
• dmenu/rofi — graphical selection menus for X11/Wayland; peco stays in the terminal
• gum filter — Charm's filtering component; more opinionated styling but less standalone

FAQ

Q: How does peco differ from fzf? A: Both are interactive filters, but peco was created independently in Go. fzf has more features (preview windows, shell bindings) while peco prioritizes simplicity and configurability via JSON.

Q: Can I use peco in shell functions? A: Yes. A common pattern is to wrap peco in shell functions for tasks like history search, directory jumping, or process selection.

Q: Does peco work on Windows? A: Yes. The Go binary compiles for Windows and works in PowerShell and cmd terminals.

Q: Can I change the match algorithm at runtime? A: Yes. Press Ctrl-R while peco is running to cycle through fuzzy, regex, and exact match modes.

Sources

• https://github.com/peco/peco
• https://github.com/peco/peco#readme