# Peco: Interactive Filtering in the Shell for Logs and Lists

> A lightweight, single-binary tool for interactively filtering input from the command line. As you type, results narrow down in real time. Output is piped to other commands. Written in Go.

**peco/peco** — Simplistic interactive filtering tool

- Repository: https://github.com/peco/peco
- Stars: 7,914 · Forks: 234
- Language: Go
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/peco-peco

## Real-Time Query Results as You Type

Peco is an interactive filter for the terminal. Based on the Python tool percol, but written in Go as a single binary. Instead of typing a command like `grep foo` and getting all matches at once, peco lets you type as you think: each keystroke narrows the results, and you see the matching lines update in real time. This is useful for filtering logs (find the error line), process lists (kill the right process), file listings (open the right file), or anything piped to it. The README notes that peco can filter logs, process stats, and find files because unlike grep, you can type as you think and look through the current results. When you find the line you want, press Enter and it goes to stdout, ready for the next command in the pipeline.

## Single-Binary Installation and Piping Input

Peco is a single binary. You can grab binary releases from GitHub and drop it in your PATH. The go.mod file shows it depends on gdamore/tcell/v2 (terminal rendering), goccy/go-yaml (configuration), google/btree (data structures), jessevdk/go-flags (CLI parsing), and other libraries, but the build produces a standalone executable with no runtime dependencies. After installation, pipe any input to peco. Type to filter the results. The results update as you type. Press Enter to select a line, and it is printed to stdout. You can pipe the output to other commands. The workflow is simple: peco filters input, you select, and the result goes to the next command in the pipeline. The Makefile shows that building uses goreleaser for cross-platform compilation to create binaries for different operating systems and architectures (Linux, macOS, Windows).

## Incremental Search and Multiple Filters

Peco offers six built-in filters that you can toggle between. The default is IgnoreCase (case-insensitive). SmartCase uses case-sensitive matching only if the query contains uppercase letters; `foo` matches any case but `Foo` matches only capitalization. CaseSensitive requires exact case matching. Regexp allows regular expressions. IRegexp (case-insensitive regexp) applies regex but ignores case. Fuzzy matches partial patterns: search `ALS` to find `ALongString`. With the FuzzyLongestSort option enabled in the configuration file, it ranks matches by longer substring match, earlier left position, and shorter line length. You can toggle between filters interactively while typing. Multiple search terms form an AND query: typing `foo bar` matches lines with both "foo" and "bar".

## Negative Matching and Exclusion

Peco supports exclusion. Prefix a term with `-` to exclude it. The query `SSO -tests -javadoc` matches lines with "SSO" but not "tests" or "javadoc". The negation prefix is configurable: pass `--negation-prefix=` (empty string) if your input has many hyphens (like shell history), or `--negation-prefix='!'` to use a different character. Escape a literal hyphen with backslash: `\-foo` matches literal "-foo". The README details the behavior: `foo -bar` matches foo but not bar, `-foo -bar` matches lines not containing foo or bar, and `-` alone matches a literal hyphen. The negation feature was redesigned in v0.6.0; earlier versions had different behavior where `test -v` matched both "test" and literal "-v". Only positive terms produce match highlighting; lines matched solely by negative exclusion are shown without highlighting.

## Multi-Select and Range Selection

Peco can select multiple lines at once. You can select lines one by one. You can also select a range of lines using the ToggleRangeMode action, which is not bound to a key by default. To enable range selection, add a key binding to your configuration. For example, add this to your config file JSON:

```json
{
    "Keymap": {
        "M-r": "peco.ToggleRangeMode"
    }
}
```

This is useful when you need to process or remove multiple matching items at once. Multiple selection is available but requires binding keys to actions in the config. Once selected, all lines are output to stdout separated by newlines.

## Multi-Stage Filtering

Peco supports freezing results to filter in stages. Use the `peco.FreezeResults` action to snapshot the current results and clear the query. Continue filtering on top of the frozen set. Use `peco.UnfreezeResults` to discard the frozen set and revert to the original input. For example, type `_test` to filter files, press a bound key to freeze (making those results the new base), then type `filter` to search within the frozen set. These actions are not bound by default; add them to your config file in the Keymap section:

```json
{
    "Keymap": {
        "M-f": "peco.FreezeResults",
        "M-u": "peco.UnfreezeResults"
    }
}
```

This two-stage approach is cleaner than a single complex query. You can freeze multiple times to progressively narrow down results. Unfreezing always reverts to the original unfiltered input.

## Horizontal Scrolling for Long Lines

When input lines are longer than the terminal width, they are clipped at the edge of the screen. Peco supports horizontal scrolling to reveal the rest of the line using the `peco.ScrollLeft` and `peco.ScrollRight` actions. This is useful when filtering long lines like configuration files, JSON payloads, or logs with long messages. The scrolling position is maintained as you navigate through results, allowing you to inspect the full content of each line. You can bind these actions to keyboard shortcuts in your configuration.

## Active maintenance and configuration

Peco is actively maintained by the peco development team. The last push was on 2026-09-26, indicating active development. The current stable release is v0.6.0 (released on 2026-02-24). Prior versions include v0.5.11 (2023-03-21) and v0.5.10 (2021-06-08), showing a history of updates. The repository is open on GitHub at peco/peco. The README notes important changes in negation behavior from v0.5.x to v0.6.0 that may require configuration updates if upgrading from older versions. The project welcomes community contributions and has a sponsorship program. Configuration is done via JSON files in the Keymap section, allowing you to customize keybindings for selection, scrolling, range mode, and freeze/unfreeze operations.

## When Peco is the wrong tool

Peco excels at interactive filtering in the terminal for human-driven exploration, but it is not suitable for every use case. If you need complex data transformation or filtering logic, a proper scripting language (awk, sed, Python, Ruby) is better suited. Peco requires you to type and select interactively; it does not automate filtering from scripts or in CI/CD pipelines without user input. The README does not detail performance on very large inputs (millions of lines or gigabyte-sized datasets); you may discover that it slows significantly when processing huge log files. If you need a graphical search tool with a GUI or a web-based interface for filtering, peco is not the answer. For complex shell workflows requiring advanced features, fzf is another popular alternative command-line filter tool, though the README does not compare them directly. Peco is best for interactive terminal use, not batch processing.

## Conclusion

Peco is for shell users who need to pluck one item from a long list (logs, processes, files) without remembering exact names or crafting complex grep patterns. Adopt it if you spend time in the terminal and want to reduce grep-based searching and manual work. Skip it if you are not comfortable with shell piping or need graphical search. Before adopting, verify that the six built-in filters (IgnoreCase, Fuzzy, Regexp, and others) cover your use case. The last push was 2026-09-26, indicating active maintenance.

## FAQ

### What does peco stand for?

The README does not define the acronym. Peco is inspired by percol, a Python filtering tool. The name peh-koh (as noted in the README) likely relates to that heritage or is simply a short, memorable identifier.

### How do I use peco with multiple search terms?

Type terms separated by spaces. For example, `foo bar` matches lines containing both "foo" AND "bar". Prefix a term with `-` to exclude it: `foo -bar` matches "foo" but not "bar". All built-in filters support multiple terms.

### Can I select multiple lines in peco?

Yes. Peco supports selecting multiple lines one at a time. You can also select a range of lines using the ToggleRangeMode action if you bind it in your config file.

### What filters does peco support?

Peco has six built-in filters: IgnoreCase (default), CaseSensitive, SmartCase (case-insensitive unless query has uppercase), Regexp, IRegexp (case-insensitive regexp), and Fuzzy (partial pattern matching). Toggle between them while typing.

### How do I install peco?

Download a binary from the releases page at github.com/peco/peco and add it to your PATH. Peco is a single binary with no dependencies, so installation is straightforward.

## Sources

- [Issues](https://github.com/peco/peco/issues)
- [License: MIT](https://github.com/peco/peco/blob/master/LICENSE)
- [peco/peco on GitHub](https://github.com/peco/peco)
- [README](https://github.com/peco/peco/blob/master/README.md)
- [Releases](https://github.com/peco/peco/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/peco-peco