# Skim Architecture
## Table of Contents
1. [High-Level Overview](#high-level-overview)
2. [Workspace & Crate Layout](#workspace--crate-layout)
3. [Entry Points](#entry-points)
4. [Core Data Flow](#core-data-flow)
5. [Operating Modes](#operating-modes)
- [Normal Interactive Mode](#normal-interactive-mode)
- [Filter Mode (`--filter`)](#filter-mode---filter)
- [Interactive / Command Mode (`--interactive`)](#interactive--command-mode---interactive)
- [Select-1 / Exit-0 / Sync Modes](#select-1--exit-0--sync-modes)
- [ANSI Mode (`--ansi`)](#ansi-mode---ansi)
- [Popup Mode (`--popup` / `--tmux`)](#popup-mode---popup----tmux)
6. [Item Ingestion Pipeline](#item-ingestion-pipeline)
7. [The Matching Subsystem](#the-matching-subsystem)
- [Match Engine Hierarchy](#match-engine-hierarchy)
- [Fuzzy Algorithms](#fuzzy-algorithms)
- [Parallel Matching](#parallel-matching)
- [Ranking & Sorting](#ranking--sorting)
8. [TUI Subsystem](#tui-subsystem)
- [Backend & Terminal Setup](#backend--terminal-setup)
- [Event Loop](#event-loop)
- [App State](#app-state)
- [Widget System](#widget-system)
- [Layout Engine](#layout-engine)
9. [Individual Widgets](#individual-widgets)
- [Input Widget](#input-widget)
- [ItemList Widget](#itemlist-widget)
- [ItemRenderer](#itemrenderer)
- [Preview Widget](#preview-widget)
- [Header Widget](#header-widget)
- [StatusLine / Info](#statusline--info)
10. [Key Bindings & Action System](#key-bindings--action-system)
11. [Preview System](#preview-system)
12. [Output & Result Collection](#output--result-collection)
13. [IPC / Listen Socket](#ipc--listen-socket)
14. [Theming](#theming)
15. [History](#history)
16. [Pre-Selection](#pre-selection)
17. [Threading Model](#threading-model)
18. [Important Call Sites (Cross-Reference)](#important-call-sites-cross-reference)
19. [Public Library API](#public-library-api)
---
## High-Level Overview
Skim (`sk`) is a terminal fuzzy-finder written in Rust, equivalent in spirit to `fzf`. It can operate as a standalone CLI binary or as an embedded library crate. At runtime it orchestrates four concurrent activities:
```
stdin / command
│
▼
┌──────────┐ batched items ┌──────────────┐
│ Reader │──────────────────▶│ ItemPool │
└──────────┘ │ (Arc<…>) │
└──────┬───────┘
│ take()
▼
┌──────────────┐
│ Matcher │◀── query string
│ (parallel) │
└──────┬───────┘
│ ProcessedItems
▼
┌──────────────────────────────────┐
│ TUI │
│ ┌────────┐ ┌────────┐ │
│ │ Input │ │Preview │ │
│ ├────────┤ ├────────┤ │
│ │ItemList│ │ Header │ │
│ └────────┘ └────────┘ │
└──────────────────────────────────┘
│
▼
SkimOutput
```
The **Reader** pulls raw text from stdin or a shell command and converts it into `Arc<dyn SkimItem>` batches, depositing them into the shared `ItemPool`.
The **Matcher** picks items up from the pool, evaluates every item against the current query string using a configured engine, and writes ranked `MatchedItem` results into `ProcessedItems`.
The **TUI** renders four composable widgets (Input, ItemList, Preview, Header), drives a `crossterm`-based event loop, and converts user keystrokes into typed `Action` values that are dispatched back to the `App` state machine.
---
## Workspace & Crate Layout
```
skim/ ← workspace root
├── src/ ← single `skim` crate (lib + binary)
│ ├── bin/
│ │ └── main.rs ← `sk` binary entry point
│ ├── lib.rs ← library root; re-exports public types
│ ├── skim.rs ← Skim<Backend> orchestrator
│ ├── options.rs ← SkimOptions (all CLI / library options)
│ ├── output.rs ← SkimOutput (returned to callers) + BinOptions/write_output (CLI serialization)
│ ├── reader.rs ← Reader + ReaderControl + CommandCollector trait
│ ├── matcher.rs ← Matcher + MatcherControl (parallel worker dispatcher)
│ ├── item.rs ← ItemPool, MatchedItem, Rank, RankBuilder
│ ├── skim_item.rs ← SkimItem trait
│ ├── binds.rs ← KeyMap, parse_key, parse_action_chain
│ ├── theme.rs ← ColorTheme, named palettes
│ ├── thread_pool.rs ← ThreadPool + parallel_work_queue
│ ├── field.rs ← field range parsing (--nth / --with-nth / --hide-nth)
│ ├── spinlock.rs ← lightweight SpinLock<T>
│ ├── util.rs ← printf helper, misc utilities
│ ├── popup/ ← tmux & zellij popup integration
│ │ ├── mod.rs ← SkimPopup trait, run_with(), check_env(), SkimPopupOutput
│ │ ├── tmux.rs ← TmuxPopup (builds/runs tmux display-popup)
│ │ └── zellij.rs ← ZellijPopup (builds/runs zellij action new-floating-pane)
│ ├── prelude.rs ← convenience re-exports
│ ├── manpage.rs ← man-page generation (cli feature); action list generated from ACTION_CATALOG
│ ├── shell.rs ← shell completion generation (cli feature)
│ ├── engine/ ← match engine implementations
│ │ ├── mod.rs
│ │ ├── factory.rs ← ExactOrFuzzyEngineFactory, AndOrEngineFactory, RegexEngineFactory
│ │ ├── andor.rs ← AndEngine, OrEngine
│ │ ├── exact.rs ← ExactEngine (prefix/postfix/inverse/exact string)
│ │ ├── fuzzy.rs ← FuzzyEngine + FuzzyAlgorithm enum
│ │ ├── all.rs ← MatchAllEngine (match-all / empty query)
│ │ ├── normalized.rs ← NormalizedEngine (Unicode normalization wrapper)
│ │ ├── regexp.rs ← RegexEngine (regex-mode)
│ │ ├── split.rs ← SplitMatchEngine (--split-match)
│ │ └── util.rs ← normalization helpers
│ ├── fuzzy_matcher/ ← raw fuzzy scoring algorithms
│ │ ├── mod.rs ← FuzzyMatcher trait, MatchIndices type alias
│ │ ├── skim.rs ← SkimMatcherV2
│ │ ├── clangd.rs ← ClangdMatcher
│ │ ├── fzy.rs ← FzyMatcher
│ │ ├── frizbee.rs ← FrizbeeMatcher (typo-resistant)
│ │ └── arinae/ ← ArinaeMatcher (default; Smith-Waterman based)
│ ├── helper/ ← higher-level item helpers
│ │ ├── mod.rs
│ │ ├── item.rs ← DefaultSkimItem (ANSI parsing, field transforms)
│ │ ├── item_reader.rs ← SkimItemReader + SkimItemReaderOption (stdin/cmd → items)
│ │ ├── selector.rs ← DefaultSkimSelector (pre-selection)
│ │ └── macros.rs ← helper macros
│ └── tui/ ← terminal UI
│ ├── mod.rs ← Size (fixed/percent/negative), Direction, BorderType, re-exports
│ ├── app.rs ← App struct + render + event dispatch (central state machine)
│ ├── backend.rs ← Tui<B> (ratatui terminal wrapper + crossterm event pump)
│ ├── event.rs ← Event enum (re-exports Action, ActionCallback, parse_action)
│ ├── actions.rs ← Action enum + name + parse_action + ACTION_CATALOG, all generated by define_action_catalog!
│ ├── widget.rs ← SkimWidget trait + SkimRender result type
│ ├── input.rs ← Input widget (query box + cursor + status info)
│ ├── item_list.rs ← ItemList widget (scrollable match result list)
│ ├── item_renderer.rs ← ItemRenderer (per-item ANSI/highlight rendering)
│ ├── preview.rs ← Preview widget (plain text, PTY, or image preview pane)
│ ├── header.rs ← Header widget (--header / --header-lines)
│ ├── statusline.rs ← Info / InfoDisplay status bar modes
│ ├── layout.rs ← LayoutTemplate + AppLayout (pre-computed areas)
│ ├── options.rs ← TuiLayout enum, PreviewLayout struct
│ └── util.rs ← cursor helpers, style merging
├── tests/ ← integration & snapshot tests
│ ├── common/
│ │ ├── insta.rs ← snap! / insta_test! macros for TUI snapshot testing
│ │ └── zellij.rs ← ZellijController + sk_test! DSL: cross-platform e2e harness driving sk in a Zellij pane
│ ├── snapshots/ ← committed .snap files
│ ├── ansi.rs ← ANSI rendering tests
│ ├── options.rs ← option coverage tests
│ ├── preview.rs ← preview pane tests
│ └── …
├── benches/ ← criterion benchmarks
└── Cargo.toml
```
The single crate exports:
- A **library** (`lib`): all types under `skim::*`, suitable for embedding.
- A **binary** (`sk`, requires feature `cli`): the `clap`-based CLI.
The `cli` feature gates `clap`, `clap_complete`, `shlex`, `env_logger`, and `clap_mangen`.
The `image` feature (enabled by default) gates image preview support, including the
`image` and `ratatui-image` dependencies, the `ImageProtocol` enum, the
`SkimOptions::image` / `SkimOptions::image_picker` fields, and the
`PreviewContent::Image` rendering path. With the feature off, the `--image` flag and
its supporting code are compiled out entirely and neither image crate is pulled in.
The `image` crate is built with only the common decoders enabled (`png`, `jpeg`,
`gif`, `webp`) rather than its full default set, keeping the binary small; previewing
other formats (TIFF, OpenEXR, QOI, BMP, …) will fail.
The `listen` feature (enabled by default) gates the IPC socket that lets other processes
drive skim via `--listen` / `--remote`, including the `interprocess`, `ron`, and `serde`
dependencies, the `SkimOptions::listen` / `SkimOptions::remote` fields, and the `serde`
derives on `Action`. See [IPC / Listen Socket](#ipc--listen-socket).
---
## Entry Points
### Binary (`src/bin/main.rs`)
```
main()
│
├─ SkimOptions::from_env() ← parses argv via clap (feature=cli)
├─ opts.build() ← applies defaults, loads history files
│
├─ if opts.shell → generate_completions() ← early exit
├─ if opts.man → manpage::generate() ← early exit
├─ if opts.remote → IPC relay mode ← early exit
│
├─ sk_main(opts)
│ ├─ SkimItemReader::new(reader_opts) ← configure stdin reader
│ ├─ opts.cmd_collector = cmd_collector
│ │
│ ├─ if --popup/--tmux && check_env() → popup::run_with(&opts)
│ │
│ └─ else:
│ ├─ if stdin not a TTY (piped) → cmd_collector.of_bufread(stdin)
│ └─ Skim::run_with(opts, rx_item?)
│
└─ print output / write history / exit
```
### Library (`src/lib.rs` + `src/skim.rs`)
Two public entry points exist on `Skim`:
| Method | Use case |
| --- | --- |
| `Skim::run_with(options, source)` | Takes a `SkimItemReceiver` channel (or `None` to use the configured command collector). The canonical entry point. |
| `Skim::run_items(options, items)` | Convenience wrapper: accepts any `IntoIterator<Item: SkimItem>`, batches them through a bounded channel, and calls `run_with`. |
Advanced embedders and tests can also drive the lifecycle manually: `Skim::init`, `start`, `init_tui` / `init_tui_with`, `enter`, `run`, `output`, plus accessors such as `app`, `app_mut`, `tui_ref`, `tui_mut`, `app_and_tui`, and `event_sender`.
The two high-level helpers return `Result<SkimOutput>`.
---
## Core Data Flow
### Initialisation sequence
```
Skim::run_with(options, source)
│
├─ Skim::init(options, source)
│ ├─ parse height (Size enum)
│ ├─ ColorTheme::init_from_options(&options)
│ ├─ Reader::from_options(&options).source(source)
│ ├─ resolve cmd / expand initial_cmd (interactive mode)
│ └─ App::from_options(options, theme, cmd)
│ ├─ Input::from_options(…)
│ ├─ Preview::from_options(…)
│ ├─ Header::from_options(…)
│ ├─ ItemList::from_options(…)
│ ├─ ItemPool::from_options(…)
│ ├─ Matcher::from_options(…)
│ └─ LayoutTemplate::from_options(…)
│
├─ Skim::start()
│ ├─ reader.collect(item_pool, initial_cmd) ← spawns reader thread(s)
│ └─ app.restart_matcher(force=true) ← kicks off first match pass
│
├─ Skim::should_enter() → decides whether to open TUI
│ (handles filter / select-1 / exit-0 / sync blocking)
│
├─ if should_enter:
│ ├─ Skim::init_tui() → Tui::new_with_height(height)
│ ├─ Skim::enter() → tui.enter_terminal(); resolve image picker; listener; event task
│ └─ Skim::run() → async event loop (tick())
│
└─ Skim::output() ← collect results + kill reader
```
### Steady-state loop (`Skim::tick()`)
Each call to `tick()` runs a `tokio::select!` on four concurrent futures:
| Branch | Source | Action |
| --- | --- | --- |
| `tui.next()` | crossterm keyboard/mouse/resize/paste events | Dispatch to `app.handle_event()` |
| `matcher_interval.tick()` | 10 ms periodic timer (adaptive: disabled once reader finishes and all items are matched) | `app.restart_matcher(false)` |
| `items_available.notified()` | `Notify` set by `ItemPool::append` | `app.restart_matcher(false)` |
| `listener.accept()` | IPC socket (when `--listen`) | Parse RON-encoded `Action`, push to event queue |
---
## Operating Modes
### Normal Interactive Mode
The default mode. The TUI is shown in full. Items arrive from stdin or a command, are matched against the live query, and displayed in the list. The user navigates with keyboard/mouse and presses Enter to accept.
**Key files:** `src/skim.rs`, `src/tui/app.rs`, `src/tui/backend.rs`
### Filter Mode (`--filter`)
When `--filter <query>` is set, skim never opens the TUI.
`Skim::should_enter()` enters a busy-wait loop:
```
loop {
if matcher.stopped() && reader.is_done() && pool.num_not_taken() == 0 {
break;
}
sleep(1ms);
app.restart_matcher(false);
}
```
Then `app.item_list.items` is populated from `processed_items` and `output()` is called immediately. The matched items are printed to stdout by the binary, one per line (or null-delimited with `--print0`).
In filter mode the `FuzzyEngine` is built with `filter_mode = true`, which uses `fuzzy_match_range` instead of `fuzzy_indices` to skip the per-character index computation and run faster.
**Key files:** `src/skim.rs` (`should_enter()`), `src/engine/fuzzy.rs` (`filter_mode` fast path), `src/bin/main.rs` (output loop)
### Interactive / Command Mode (`--interactive`)
When `--interactive` is set together with `--cmd <template>`, the query box controls a shell command rather than a fuzzy filter. Every change to the input re-expands the template and issues a `Reload` event.
Template placeholders:
- `{}` — the current query
- `{q}` — alias for `{}`
- `{n}` — ordinal of the current item
`App::expand_cmd()` handles placeholder expansion. On `Action::ToggleInteractive`, the mode flips between the query controlling the fuzzy filter and the query driving the command.
In interactive mode, the initial command is expanded against the initial query:
```rust
// src/skim.rs Skim::init()
let initial_cmd = if app.options.interactive && app.options.cmd.is_some() {
app.expand_cmd(&cmd, true) // true = initial call
} else { cmd.clone() };
```
A `Reload(new_cmd)` event is handled at the `Skim::tick()` level (not `App::handle_event()`), because it must kill the reader and restart cleanly:
```rust
// src/skim.rs tick()
if let Event::Reload(new_cmd) = &evt {
self.handle_reload(&new_cmd.clone());
}
```
`handle_reload()`:
1. Kills `reader_control` (waits for all reader threads to stop)
2. Clears `ItemPool`
3. Clears `ItemList` (unless `no_clear_if_empty`)
4. Calls `app.restart_matcher(force=true)`
5. Starts a new `reader.collect(…)`
**Key files:** `src/skim.rs` (`handle_reload`, `tick`), `src/tui/app.rs` (`expand_cmd`, `handle_action` → `RefreshCmd`)
### Select-1 / Exit-0 / Sync Modes
All three are handled in `Skim::should_enter()` before opening the TUI:
| Option | Meaning | Behaviour |
| --- | --- | --- |
| `--select-1` | Auto-accept if exactly one match | Waits until ≥ 2 matches or reader/matcher done; returns without TUI if exactly 1 match |
| `--exit-0` | Exit immediately if no matches | Waits until ≥ 1 match or done; returns without TUI if 0 matches |
| `--sync` | Block until all items processed | Waits until `num_matched == usize::MAX` (effectively waits for full scan) |
### ANSI Mode (`--ansi`)
When `--ansi` is set, `SkimItemReaderOption::from_options` sets `use_ansi_color = true`. Each input line then creates a `DefaultSkimItem` with:
1. **Escape detection**: `DefaultSkimItem::contains_ansi_escape()` checks for `\x1b`.
2. **Stripping**: `strip_ansi()` returns `(stripped_text, ansi_info)` where `ansi_info` is a `Vec<(byte_pos, char_pos)>` mapping from stripped to original coordinates.
3. **Matching**: `text()` returns the stripped text; the matcher works on plain text.
4. **Display**: `display()` reconstructs styled `ratatui::text::Line` using `ansi_to_tui::IntoText`, then overlays match-highlight spans on top.
The coordinate mapping is critical: match indices come back in terms of stripped text positions, but the highlight must be applied to the original ANSI-containing string. `DefaultSkimItem::display()` applies a char-index offset conversion using `ansi_info`.
Without `--ansi`, any ANSI escape codes are passed through to `text()` and displayed as literal characters. If the raw input happens to contain escape sequences (but `--ansi` is not set), `escape_ansi()` is called to make them visible.
ANSI input uses the same parallel pipeline as plain input — there is no separate serial path. `DefaultSkimItem::new` handles the stripping inline inside the worker threads.
**Key files:** `src/helper/item.rs` (`DefaultSkimItem::new`, `strip_ansi`, `display`)
### Popup Mode (`--popup` / `--tmux`)
When `--popup [direction[,size[,size]]]` (alias `--tmux`) is set, the binary calls `check_and_run_popup()`, which checks `popup::check_env()` and, if true, delegates to `popup::run_with()` instead of `Skim::run_with()`.
**`check_env()`** returns `true` only when:
- `$_SKIM_POPUP` is **not** set in the environment (prevents the child process from recursing back into popup mode), and
- at least one supported multiplexer is detected: tmux (`$TMUX` set) or Zellij (`$ZELLIJ` set).
The popup flow:
1. Creates a temp directory for IPC (`/tmp/sk-popup-XXXXXXXX/`).
2. If stdin is piped, creates a named FIFO (`tmp_stdin`) and spawns a thread to relay stdin into it incrementally so the child can stream-read.
3. Reconstructs the `sk` command line from `std::env::args()`, shell-quotes every retained argument, strips `--popup`/`--tmux`, `--output-format`, and `--print-cmd`, then appends `--print-query --print-header --print-current --print-score`.
4. Forwards all `SKIM_*`, `RUST*`, and `PATH` environment variables to the child via the multiplexer's `-e` flag, **plus `_SKIM_POPUP=1`** to prevent re-entry.
5. Launches the popup via the appropriate backend:
- **tmux**: `tmux display-popup -E … sh -c <cmd> > stdout_file`
- **Zellij**: `zellij action new-floating-pane … -- sh -c <cmd> > stdout_file`
6. Waits for the popup process to exit.
7. Parses the structured stdout file (`query\nheader\ncurrent_item\nitem1\nscore1\n…`) into a synthetic `SkimOutput`; `cmd` is reconstructed from the parent options because `--print-cmd` is deliberately stripped.
The internal `SkimPopup` trait abstracts the two multiplexer backends:
```rust
trait SkimPopup {
fn from_options(options: &SkimOptions) -> Box<dyn SkimPopup>;
fn add_env(&mut self, key: &str, value: &str);
fn run_and_wait(&mut self, command: &str) -> std::io::Result<ExitStatus>;
}
```
`TmuxPopup` and `ZellijPopup` each implement this trait. The active backend is selected at runtime: Zellij takes priority if both are available.
The child `sk` process runs fully independently inside the popup. The parent reads back a synthetic `SkimOutput` from the captured file. Because `_SKIM_POPUP=1` is set in the child's environment, `check_env()` returns `false` in the child, so it runs as a normal interactive skim session regardless of what `SKIM_DEFAULT_OPTIONS` contains. The stdin relay thread stops when the popup exits, avoiding broken-pipe noise if the child closes its FIFO early.
**Key files:** `src/popup/mod.rs` (`run_with`, `check_env`), `src/popup/tmux.rs` (`TmuxPopup`), `src/popup/zellij.rs` (`ZellijPopup`), `src/bin/main.rs` (`check_and_run_popup`)
---
## Item Ingestion Pipeline
All inputs — plain stdin, `--ansi`, `--nth`/`--with-nth`, and shell commands — flow through a
single unified parallel pipeline (`parallel_bufread`). There is no serial fallback path.
```
Source (stdin bytes or child process stdout)
│
│ SkimItemReader::of_bufread() or CommandCollector::invoke()
│
└── parallel_bufread() (all inputs)
├─ Thread 1: I/O reader — reads 256 KB chunks, splits at line boundaries,
│ assigns monotonic sequence numbers, sends to MPMC channel
├─ Thread 1: bounded dispatcher — uses in-flight tokens to limit queued/running jobs
├─ Pool workers: receive chunk jobs, validate UTF-8,
│ create DefaultSkimItem::new(line, ansi, trans_fields, matching_fields, delimiter)
│ .hidden_fields(hidden_fields, delimiter)
│ (handles ANSI stripping, --nth / --with-nth / --hide-nth inline),
│ send (seq, items) pairs
├─ Thread 1: reorder — collects (seq, items), emits in order through SkimItemReceiver;
│ drops tx_pipeline_done on exit (signals killer thread)
└─ Thread 1: killer — waits on rx_interrupt OR rx_pipeline_done (whichever fires first);
kills child process if one exists, then exits
SkimItemReceiver channel
│
│ Reader::collect()
│ collect_items() spawns a thread that blocks on recv_timeout (5ms) from the channel
│
└── ItemPool::append(items)
├─ respects --tac (reverse order)
├─ respects --header-lines (reserves first N items)
├─ notifies items_available (Notify) to wake matcher
└─ increments atomic length counter
```
### `DefaultSkimItem` construction matrix
| `with_nth` | `ansi` | `text` field | `orig_text` | `stripped_text` |
| --- | --- | --- | --- | --- |
| false | false | original line | None | None |
| false | true | original line | None | stripped (+ `ansi_info`) |
| true | false | transformed | original | None |
| true | true | transformed | original | stripped (+ `ansi_info`) |
Fields `/0` bytes are stripped from `text` (used for display/matching) but preserved in `orig_text` (used for output).
**`--hide-nth`** is orthogonal to the matrix above and applied through the builder method
`DefaultSkimItem::hidden_fields(hidden_fields, delimiter)` after construction (rather than a `new`
parameter). The requested fields are resolved to byte ranges (in the same coordinate space as
`text()` — the stripped text under `--ansi`, otherwise the `text` field) and stored as
`hidden_ranges` in the item metadata, exposed via the `SkimItem::hidden_ranges()` trait method. The
hidden fields **remain part of `text()`**, so they stay searchable and still participate in matching.
They only affect rendering:
- `DefaultSkimItem::display()` removes the hidden characters and remaps the match highlight
positions into the visible coordinate space (`project_visible_text` / `project_match_indices` in
`src/helper/item.rs`). This is integrated into **both** display branches: the plain branch projects
the text through `to_line`, and the ANSI branch drops the hidden characters from the already-parsed
styled spans (`retain_visible_spans`) so surviving characters **keep their ANSI colors**, then runs
the normal highlighting on the remapped visible-coordinate matches.
- `ItemRenderer::render_item` applies the same projection to derive the visible sub-line text and the
match range used for horizontal scrolling, so hidden characters are ignored for hscroll and never
highlighted.
---
## The Matching Subsystem
### Match Engine Hierarchy
Engines are composable through the factory pattern. Starting from `Matcher::create_engine_factory_with_builder()`:
```
options
│
├── if regex mode:
│ RegexEngineFactory (configured with the same RankBuilder / --tiebreak criteria)
│ └─ if normalize: NormalizedEngineFactory(RegexEngineFactory)
│
└── else (fuzzy/exact mode):
ExactOrFuzzyEngineFactory
└─ if split_match: SplitMatchEngineFactory(ExactOrFuzzyEngineFactory)
└─ AndOrEngineFactory(SplitMatchEngineFactory | ExactOrFuzzyEngineFactory)
└─ if normalize: NormalizedEngineFactory(AndOrEngineFactory)
```
When `create_engine_with_case(query, case)` is called at match time, the factory chain parses the query string and builds a concrete engine tree:
```
query: "'abc def | ghi ^xyz"
│
AndOrEngineFactory.parse_andor()
│
├─ "'abc" → ExactOrFuzzyEngineFactory
│ → ExactEngine (prefix=false, postfix=false, case-insensitive "abc")
│
├─ "def | ghi" → OrEngine
│ ├─ FuzzyEngine("def")
│ └─ FuzzyEngine("ghi")
│
└─ "^xyz" → ExactEngine(prefix=true, "xyz")
```
Query prefix semantics handled by `ExactOrFuzzyEngineFactory::create_engine_with_case()`:
| Prefix/suffix | Engine type |
| --- | --- |
| `'abc` | force ExactEngine (toggle from default) |
| `!abc` | ExactEngine with `inverse = true` |
| `^abc` | ExactEngine with `prefix = true` |
| `abc$` | ExactEngine with `postfix = true` |
| `!^abc` | ExactEngine inverse+prefix |
| `!^abc$` | ExactEngine inverse+prefix+postfix (exact string, inverted) |
| plain `abc` | FuzzyEngine (or ExactEngine if `--exact`) |
| empty / `!` | MatchAllEngine |
### Fuzzy Algorithms
All algorithms implement the `FuzzyMatcher` trait with two methods:
- `fuzzy_indices(choice, pattern) → Option<(score, Vec<usize>)>` — full match with per-character highlights
- `fuzzy_match_range(choice, pattern) → Option<(score, begin, end)>` — fast path without highlight indices (used in filter mode)
| Algorithm | Flag | Notes |
| --- | --- | --- |
| `Arinae` | `--algorithm arinae` (default) | Smith-Waterman with affine gaps; typo-resistant; picks last occurrence on ties when `--last-match` |
| `SkimV2` | `--algorithm skim_v2` | Skim's classic dynamic-programming scorer |
| `Clangd` | `--algorithm clangd` | Clangd-style subsequence scoring |
| `Fzy` | `--algorithm fzy` | Port of the `fzy` C algorithm; supports `--typos` |
| `Frizbee` | `--algorithm frizbee` | Edit-distance based; explicitly typo-tolerant |
Typo tolerance is configured via `Typos`:
- `Typos::Disabled` — no tolerance (default)
- `Typos::Smart` — adaptive: `query.len() / 4` typos allowed
- `Typos::Fixed(n)` — exactly n typos
### Parallel Matching
`Matcher::run()` dispatches work across the thread pool using `thread_pool::parallel_work_queue()`:
```
Matcher::run(query, item_pool, thread_pool, …)
│
├─ create matcher_engine from factory (synchronous)
├─ take items from pool synchronously (avoids race with restart)
│
└─ std::thread::spawn(coordinator closure)
│
├─ shares items as Arc<[Arc<dyn SkimItem>]>
│
├─ parallel_work_queue(pool, num_workers, items, CHUNK_SIZE=4096, …)
│ │
│ ├─ Worker threads (num_cpus - 1):
│ │ ├─ atomically grab next chunk
│ │ ├─ for each item: matcher_engine.match_item(item)
│ │ ├─ flush processed/matched counters (Relaxed atomic)
│ │ └─ accumulate into worker-local Vec<MatchedItem>
│ │ └─ sort_unstable() on worker thread (parallel sort)
│ │
│ ├─ AtomicCounter barrier (lock-free AtomicUsize + thread::park/unpark)
│ │
│ └─ coordinator:
│ └─ merge_worker_results(worker_results, no_sort, …)
│ ├─ concatenate k sorted runs
│ ├─ sort() (stable; driftsort detects k runs → O(n log k))
│ └─ validate query generation and write into Mutex<Option<ProcessedItems>>
│
└─ stopped.store(true)
```
Interruption is cooperative: each chunk checks `interrupt.load(Relaxed)` before processing. `MatcherControl::kill()` sets `interrupt = true`; `MatcherControl::drop()` also calls `kill()`. Each forced restart increments a shared query generation. Published `ProcessedItems` carry that generation; both publication and consumption reject stale generations, so a cancelled matcher cannot replace newer results.
### Ranking & Sorting
`MatchedItem` implements `Ord` through a lazy sort key computed by `Rank::sort_key(criteria)`. Items can also be disabled: `SkimItem::disabled()` returns `false` by default, and `--disable-pattern <regex>` marks matching items as disabled in the default item type. Disabled items stay visible but are dimmed by `ItemRenderer` and cannot be selected.
`Rank` fields:
| Field | Description |
| --- | --- |
| `score` | Raw match score (higher = better) |
| `begin` | First matched character index |
| `end` | Last matched character index |
| `length` | Total item text length in bytes |
| `index` | Ordinal position in the input stream |
| `path_name_offset` | Byte offset after last `/` or `\` (for path-name tiebreak) |
`RankCriteria` variants (configurable via `--tiebreak`): `Score`, `NegScore`, `Begin`, `NegBegin`, `End`, `NegEnd`, `Length`, `NegLength`, `Index`, `NegIndex`, `PathName`, `NegPathName`.
`MergeStrategy` (in `item_list.rs`):
| Strategy | When used |
| --- | --- |
| `Replace` | Fresh match pass (query changed, full re-sort) |
| `SortedMerge` | New items arrived during a running match (merge-insert) |
| `Append` | Incremental `--no-sort` mode |
| `Prepend` | Incremental `--tac --no-sort` mode, preserving global reverse-input order |
`Rank::index` always records the item's stable ordinal in the original input stream. `RankBuilder` makes both configured index criteria and the implicit final index tiebreak descending under `--tac`, so normal `SortedMerge` remains valid across independently reversed batches.
---
## TUI Subsystem
### Backend & Terminal Setup
`Tui<B>` (in `src/tui/backend.rs`) wraps `ratatui::Terminal<B>` and owns:
- A `tokio::sync::mpsc` channel (`event_tx` / `event_rx`) of capacity 1 M for events.
- A `JoinHandle` for a background Tokio task that reads `crossterm::event::EventStream` and sends `Event` values.
- A `CancellationToken` to stop the background task.
- An `is_fullscreen` flag that determines the `ratatui::Viewport`.
- The fixed viewport `Rect` for inline mode, which can move when the terminal scrolls.
**Viewport selection** (`Tui::new_with_height_and_backend()`):
- `Size::Percent(100)` → `Viewport::Fullscreen` (enters alternate screen).
- `Size::Fixed(lines)` → `Viewport::Fixed(Rect)` with that many rows.
- `Size::Percent(p)` → fixed viewport with `terminal_height * p / 100` rows.
- `Size::Neg(lines)` → fixed viewport with `terminal_height - lines` rows, saturating at zero.
Any fixed viewport is anchored at the current cursor position; the terminal is scrolled if needed to make room. After construction, `Tui::min_height()` can increase an inline viewport to `--min-height`. It limits the height to the terminal height and scrolls the terminal before it moves and resizes the viewport when there are too few rows below it.
The default backend is `CrosstermBackend<BufWriter<Stderr>>`. Skim always draws to **stderr** so stdout remains clean for piped output.
**Terminal lifecycle:**
```
Tui::enter()
├─ enable_raw_mode()
├─ execute!(EnableMouseCapture, EnableBracketedPaste)
├─ if fullscreen: execute!(EnterAlternateScreen, cursor::Hide)
└─ Tui::start() ← spawns event pump task
Tui::exit()
├─ Tui::stop() / cancel()
├─ cleanup_terminal()
│ ├─ execute!(DisableMouseCapture, DisableBracketedPaste, LeaveAlternateScreen, Show)
│ └─ disable_raw_mode()
└─ if inline: clear() + reset cursor to top of drawing area
```
A panic hook is installed once (`PANIC_HOOK_SET: Once`) to ensure `cleanup_terminal()` runs even on panics.
**Foreground `execute` actions:** the `execute(cmd)` action must hand the terminal to a child process (e.g. an editor or an interactive TUI like `ncdu`). `handle_action` only expands the command and returns `Event::RunExecute(cmd)`; the actual run happens in `App::handle_event` (which owns the `Tui`) via the `run_foreground(tui, cmd)` helper in `src/tui/app.rs`. `run_foreground` calls `Tui::stop_and_join()` — which cancels the event-pump task **and blocks until it has dropped its `EventStream`** — so skim's reader stops consuming terminal input before the child starts; otherwise the two race for keystrokes and interactive children appear to freeze. It then leaves the alternate screen / raw mode, spawns the child with its **own** stdin opened from the controlling terminal (`/dev/tty`, or `CONIN$` on Windows; falls back to inheriting skim's stdin), waits for it, restores terminal modes, and calls `Tui::start()` to respawn the reader. Giving the child its own tty stdin is what lets `execute` work when skim's own stdin is a pipe (`find | sk`). `execute-silent(cmd)` needs no terminal and is still spawned directly inside `handle_action` with stdout/stderr sent to `/dev/null`.
Two subtleties make the resume correct. First, `Tui::start` installs a **fresh** `CancellationToken` on every call: a token stays cancelled once cancelled, so reusing the one `stop_and_join` cancelled would make the respawned reader observe the cancellation immediately and exit without reading input. Second, the post-execute repaint uses `Tui::force_full_redraw` (which resets both of ratatui's diff buffers) followed by `Event::Render`, rather than `Event::Redraw`/`tui.clear()`: ratatui's `Terminal::clear` first queries the cursor position, and crossterm writes that query (`ESC [ 6 n`) to **stdout**. Since skim renders to stderr and its stdout is routinely redirected (`sk > file`, `find | sk | …`), that query would reach no terminal, get no reply, and stall the UI for seconds before erroring out. `force_full_redraw` performs no cursor query and works for both fullscreen and inline viewports.
Image preview protocol detection is owned by `Skim::enter()`, not `Tui::enter_terminal()`: `--image=detect` temporarily ensures an alternate screen is active, queries `ratatui_image::picker::Picker::from_query_stdio()`, falls back to `Picker::halfblocks()` on failure, then stores the picker in both `SkimOptions.image_picker` and the `Preview` widget. `--image=halfblocks` skips detection and installs `Picker::halfblocks()` directly.
### Event Loop
The crossterm event pump (background Tokio task in `Tui::start()`):
```
loop {
select! {
cancelled → break
crossterm_event →
Key(press) → send Event::Key(key)
Paste(text) → send Event::Paste(text)
Mouse(m) → send Event::Mouse(m)
Resize(c,r) → send Event::Resize + Event::Render
Error(e) → send Event::Error(e)
tick (1/12 s) → send Event::Heartbeat
}
}
```
The main loop (`Skim::run()`) calls `tick()` in a loop, which `select!`s on the same channel plus the matcher interval and IPC listener.
Frame rate is capped at 120 fps (`FRAME_TIME_MS = 1000/120`). `App::handle_event(Heartbeat)` checks `needs_render` (an `AtomicBool` set by the matcher when new results arrive) and emits `Event::Render` only when the last render was more than `FRAME_TIME_MS` ago.
### App State
`App` (in `src/tui/app.rs`) is the single mutable application state. It contains:
| Field | Type | Role |
| --- | --- | --- |
| `item_pool` | `Arc<ItemPool>` | Shared with reader; accumulates raw items |
| `matcher` | `Matcher` | Engine factory + case + rank config |
| `matcher_control` | `MatcherControl` | Handle to stop/query current match pass |
| `item_list` | `ItemList` | Display list + selection state |
| `input` | `Input` | Query text + cursor |
| `preview` | `Preview` | Preview pane state + process handle |
| `header` | `Header` | Static + dynamic header lines |
| `thread_pool` | `Arc<ThreadPool>` | Worker threads for matching |
| `options` | `SkimOptions` | Full configuration snapshot |
| `layout_template` | `LayoutTemplate` | Pre-computed widget constraints |
| `layout` | `AppLayout` | Last-frame widget areas (updated in render) |
| `needs_render` | `Arc<AtomicBool>` | Signal from matcher → event loop |
| `yank_register` | `String` | Cut/yank buffer |
| `query_history` / `cmd_history` | `Vec<String>` | History for ↑/↓ navigation |
| `last_left_click` | `Option<Instant>` | Detect two left clicks within the 500 ms `double-click` window |
**`App::handle_event()`** dispatches on `Event`:
```
Event::Render → tui.draw(|f| f.render_widget(&mut self, f.area()))
Event::Heartbeat → update_spinner(); check pending_matcher_restart; throttled render
Event::RunPreview → run_preview(tui)
Event::RunExecute(cmd) → run_foreground(tui, cmd); force_full_redraw(); send Render
Event::Key(k) → handle_key(k) → [Action…] → tui.event_tx.send(Event::Action)
Event::Action(a) → handle_action(a) → [Event…] → tui.event_tx.send(…)
Event::Paste(t) → input.insert_str(cleaned); on_query_changed()
Event::Resize(…) → app.resize(); run_preview()
Event::Mouse(…) → handle_mouse() → normal handling + optional `double-click` key event
Event::PreviewReady → apply preview offset; needs_render()
Event::AppendItems → item_pool.append(); restart_matcher(false)
Event::ClearItems → item_pool.clear(); restart_matcher(true)
Event::Quit/Close → tui.exit(); should_quit = true
Event::Reload(_) → (handled by Skim::tick, not here)
```
**`App::restart_matcher(force)`:**
```
restart_matcher(force)
├─ if !force && matcher not stopped → skip (debounce)
├─ if pool has no un-taken items && !force → skip
├─ kill existing matcher_control
├─ determine MergeStrategy
│ ├─ Replace → if query changed / force
│ ├─ Prepend → incremental --tac --no-sort
│ └─ SortedMerge / Append otherwise
└─ matcher.run(query, pool, thread_pool, processed_items, strategy, no_sort, needs_render)
→ returns new MatcherControl
```
A 200 ms debounce (`restart_matcher_debounced`) is applied to query-change events to avoid thrashing the matcher on rapid typing.
### Widget System
All TUI widgets implement `SkimWidget`:
```rust
pub trait SkimWidget: Sized {
fn from_options(options: &SkimOptions, theme: Arc<ColorTheme>) -> Self;
fn render(&mut self, area: Rect, buf: &mut Buffer) -> SkimRender;
}
pub struct SkimRender {
pub items_updated: bool,
pub run_preview: bool, // signals that preview should be (re)spawned
}
```
`App` itself implements `ratatui::widgets::Widget` via `impl Widget for &mut App`, which calls each sub-widget's `render()` and ORs their `SkimRender` results. After render, `App` sets `cursor_pos` to the absolute screen coordinates of the input cursor.
### Layout Engine
`LayoutTemplate` pre-computes area splits from `SkimOptions` once and stores constraint trees.
`apply(area: Rect) → AppLayout` is then a cheap, allocation-free split. Bordered
widgets share adjacent border rows and columns by default;
`SkimOptions::border_no_collapse` keeps their areas separate.
`AppLayout` has four optional areas:
```rust
pub struct AppLayout {
pub list_area: Rect,
pub input_area: Rect,
pub header_area: Option<Rect>,
pub preview_area: Option<Rect>,
}
```
Layout is rebuilt on `Event::Resize`, when the header height changes (multiline header items arriving), and on `TogglePreview`.
**Layout orientations** (`TuiLayout`):
| Mode | Description |
| --- | --- |
| `Default` | Input at bottom, list above, header above list (bottom-to-top reading) |
| `Reverse` | Input at top, list below (top-to-bottom reading) |
| `ReverseList` | List at top, input at bottom |
**Preview placement** is parsed from `--preview-window`:
- Direction: `left` / `right` / `up` / `down`
- Size: `50%` (default), fixed cells, or negative cells (`-N`, meaning the non-preview side keeps `N` cells)
- Modifiers: `hidden`, `wrap`, `pty`, `+offset`
---
## Individual Widgets
### Input Widget
`Input` (`src/tui/input.rs`) maintains:
- `value: String` — the query text (primary mode)
- `alternate_value: String` — the command text (interactive mode)
- `cursor_pos: usize` — character-level cursor position
Text operations (used by `handle_action`):
- `insert(char)` / `insert_str(&str)` — insert at cursor
- `delete(n)` — delete n characters forward
- `delete_backward_word()` / `delete_to_beginning()` / `delete_forward_word()`
- `move_cursor(delta)` / `move_cursor_to(pos)` / `move_to_end()`
- `move_cursor_forward_word()` / `move_cursor_backward_word()`
- `switch_mode()` — swaps primary and alternate buffers (interactive mode toggle)
The `StatusInfo` struct rendered inside the input line shows:
`{spinner} {matched}/{total} ({processed}) [{matcher_mode}] [{multi_count}]`
### ItemList Widget
`ItemList` (`src/tui/item_list.rs`) maintains:
- `items: Vec<MatchedItem>` — the currently displayed matched items
- `processed_items: Arc<Mutex<Option<ProcessedItems>>>` — shared with matcher
- `matcher_generation: Arc<AtomicUsize>` — identifies the active query generation
- `selection: Vec<usize>` — indices of multi-selected items
- `current: usize` — focused item index (0 = bottom in default layout)
- `offset: usize` — scroll offset (number of items scrolled)
- `manual_hscroll: i16` — user-driven horizontal scroll
On each render, `ItemList::render()` checks `processed_items`, rejects results from an old query generation, and swaps current results in through the mutex. Depending on `MergeStrategy`:
- `Replace`: replaces `items` entirely.
- `SortedMerge`: performs an O(n+m) merge preserving order.
- `Append`: extends `items`.
- `Prepend`: places a reversed incremental `--tac` batch before existing items; the cursor follows the head unless the user moved away from it.
**Selection state management:**
- `toggle_at(idx)` / `toggle()` / `toggle_all()` / `select_all()` / `clear_selection()`
- `scroll_by_rows(n)` — scroll by terminal rows (accounting for multiline items)
- `scroll_by(n)` — scroll by item count
- `jump_to_first()` / `jump_to_last()`
Pre-selection is applied when items first appear: `DefaultSkimSelector::should_select(index, item)` is checked for each item and matching items are added to `selection`.
### ItemRenderer
`ItemRenderer` (`src/tui/item_renderer.rs`) is an ephemeral struct created per render frame. It handles all per-item display concerns:
1. **Selector icon rendering** — `>` (single-select cursor) or configurable icon.
2. **Multi-select icon** — space / `>` or configurable icon per selection state.
3. **Match highlight** — builds a `DisplayContext` (`score`, `Matches`, width, base style, highlight style) and calls `item.display(context)` so custom items can render their own styled `Line<'_>`.
4. **Horizontal scroll** — `calc_hscroll()` finds the first matched character and auto-scrolls to show it; `apply_hscroll()` clips spans accordingly.
5. **Tab expansion** — `expand_tabs()` replaces `\t` with spaces at configurable width.
6. **Ellipsis truncation** — replaces overflowing content with `…` (or custom `--ellipsis`).
7. **Multiline items** — when `--multiline <sep>` is set, splits item text on the separator and renders sub-lines.
8. **Score / index display** — when feature flags `ShowScore` / `ShowIndex` are set.
9. **Disabled state** — dims all spans when `item.disabled()` is true.
### Preview Widget
`Preview` (`src/tui/preview.rs`) renders a side/top/bottom pane showing expanded information about the focused item. Its stored content is one of three variants:
**Plain text mode** (no `pty`): spawns `sh -c <cmd>` on Unix or `cmd /c <cmd>` on Windows. On Windows, `Command::raw_arg` is used so `cmd.exe` receives shell metacharacters exactly as written. The worker drains stdout and stderr concurrently, but retains at most `PREVIEW_MAX_BYTES` from each stream. Retained stdout is parsed with `ansi_to_tui::IntoText` and published while the command runs. Cancellation terminates the child process group (the process tree on Windows) and invalidates its output writer, so an old reader cannot replace content from a newer preview. At exit, successful stdout or failed stderr is stored as `PreviewContent::Text` and followed by `Event::PreviewReady`.
**PTY mode** (`--preview-window pty`): creates a real pseudo-terminal pair via `portable_pty`. The child process sees a properly sized terminal (via `ROWS`/`COLUMNS` env and PTY dimensions). Output is parsed by a `vt100::Parser` with a scrollback buffer, stored as `PreviewContent::Terminal(Arc<RwLock<vt100::Parser>>)`. This enables interactive preview programs (e.g. `bat`, `delta`).
**Image mode** (`--image[=detect|halfblocks]`, requires the default `image` feature): treats the expanded preview command as an image path instead of executing it. A worker thread decodes the image with the `image` crate and stores `PreviewContent::Image { source, protocol, size }`. Rendering uses `ratatui_image`; `detect` builds an image protocol picker after entering the alternate screen, while `halfblocks` skips terminal capability detection and uses the portable half-block renderer. The protocol is rebuilt when the preview area changes so the image keeps its aspect ratio within the pane.
`Preview::spawn()`:
```
kill() ← kill any running preview
reset scroll_y / scroll_x
if image mode:
decode <cmd> as image path
thread: content.write() = PreviewContent::Image or failure text
→ Event::PreviewReady
else if pty mode:
init_pty() ← create PtyPair
resize PTY to current (rows, cols)
spawn sh -c <cmd> in slave
thread: read master → filter_and_respond_to_queries → vt100::Parser::process
→ Event::PreviewReady when EOF
else:
start shell in a dedicated process group with piped stdout + stderr
thread: drain both streams with bounded retention; stream active stdout; poll child status
→ cancellation invalidates the writer and kills the process group
→ content.write() = PreviewContent::Text(…)
→ Event::PreviewReady
```
Scroll state: `scroll_y`, `scroll_x` (in lines/columns) and `total_lines` use `usize`; conversion to ratatui's `u16` coordinates saturates at render time. `page_up/down`, `scroll_up/down/left/right` modify these. `PreviewPosition` supports fixed, percentage, and negative offsets. When `PreviewReady` fires, an optional offset expression (from `--preview-window +expr`) is evaluated to auto-scroll to the matched line.
### Header Widget
`Header` (`src/tui/header.rs`) renders two kinds of content:
- **Static** (`--header <text>`): shown at the top or bottom depending on layout; expanded for tab characters once at init.
- **Dynamic** (`--header-lines N`): first N items from `ItemPool::reserved()` are treated as header lines instead of selectable items.
When `--multiline <sep>` is active, each header-line item may span multiple terminal rows. The `height()` method returns the total rows needed; if this changes between frames (multiline items arrive), `App::render()` detects it and rebuilds `LayoutTemplate`.
### StatusLine / Info
`StatusInfo` is computed inside `Input::render()` from the current `App` state:
```
Left side: "> " + spinner + " " + matched + "/" + total [+ "(N%)"]
Inline sep: " < " (when inline_info)
Right side: multi-select count when multi mode
```
`InfoDisplay` has six modes:
- `Default` — separate line above the prompt
- `Left` — separate line above the prompt, with all info left-aligned
- `Right` — separate line above the prompt, with all info right-aligned
- `Inline` — inside the prompt line (after the query text)
- `InlineRight` — inside the prompt line, right-aligned
- `Hidden` — not shown
---
## Key Bindings & Action System
### Key Parsing
`parse_key(key_str)` (in `src/binds.rs`) converts strings like `"ctrl-a"`, `"alt-shift-f"`, `"f10"`, `"enter"` into `crossterm::event::KeyEvent { code, modifiers }`.
`parse_action(raw)` (in `src/tui/actions.rs`, re-exported from `src/tui/event.rs`) converts strings like `"down:2"`, `"execute(ls {})"`, `"if-query-empty:reload+up"` into `Action` variants.
`parse_action_chain(chain)` splits on `+` (respecting `if-*{…+…}` syntax) into `Vec<Action>`.
`parse_keymap("key:action+action")` → `(&str, Vec<Action>)`.
### Default Key Map (`get_default_key_map`)
Notable defaults:
| Key | Action |
| --- | --- |
| `Enter` | `Accept(None)` |
| `Esc` | `Abort` |
| `Ctrl-C` / `Ctrl-D` / `Ctrl-G` | `Abort` |
| `↑` / `Ctrl-K` / `Ctrl-P` | `Up(1)` |
| `↓` / `Ctrl-J` / `Ctrl-N` | `Down(1)` |
| `Tab` | `Toggle` + `Down(1)` |
| `Shift-Tab` / `BackTab` | `Toggle` + `Up(1)` |
| `Ctrl-A` | `BeginningOfLine` |
| `Ctrl-E` | `EndOfLine` |
| `Ctrl-U` | `UnixLineDiscard` |
| `Ctrl-W` | `UnixWordRubout` |
| `Ctrl-Y` | `Yank` |
| `Ctrl-Q` | `ToggleInteractive` |
| `Ctrl-R` | `RotateMode` |
| `Shift-↑` / `Shift-↓` | `PreviewUp(1)` / `PreviewDown(1)` |
| `Alt-H` / `Alt-L` | `ScrollLeft(1)` / `ScrollRight(1)` |
User bindings from `--bind key:action[+action]` are parsed at startup and merged via `KeyMap::add_keymaps()`.
### Mouse Bindings
| Bind | Default | Fired when |
| --- | --- | --- |
| `double-click` | `Accept(None)` | two left-button presses occur within 500 ms; the first press still performs normal item selection |
`App::handle_mouse` recognizes the gesture after normal click handling and routes
it through the keymap using the reserved `SkimEvent::DoubleClick` key code.
### Synthetic Events (`SkimEvent`)
Besides real key presses, skim fires a few *synthetic* events that can be bound
to actions just like keys. Because the keymap is keyed by
`crossterm::event::KeyEvent`, these events are represented *transparently* as
reserved function-key codes in the high-`F` range that no real terminal emits.
The [`SkimEvent`](src/binds.rs) enum gives them named variants so the reserved
codes live in one place rather than being scattered as magic `F(255)` literals,
and `parse_key` accepts the friendly names below:
| Bind name | `SkimEvent` | Reserved code | Fired when |
| --- | --- | --- | --- |
| `change` | `SkimEvent::Change` | `F(255)` | the query changes |
| `start` | `SkimEvent::Start` | `F(254)` | skim has started and entered its event loop (once) |
| `load` | `SkimEvent::Load` | `F(253)` | the reader finishes producing items (once per read; a `reload` fires it again) |
| `result` | `SkimEvent::Result` | `F(252)` | filtering for the current query completes and its results are ready |
| `focus` | `SkimEvent::Focus` | `F(251)` | the focused item changes on cursor movement or a result update |
| `zero` | `SkimEvent::Zero` | `F(250)` | the reader is done and the final search has no matches |
| `one` | `SkimEvent::One` | `F(249)` | the reader is done and the final search has exactly one match |
Events are injected from the nearest state-change site:
- **`change`** — `App::on_query_changed`.
- **`focus`** — `App::on_selection_changed` handles cursor movement;
`Event::Render` checks again after matcher output is merged into the list so
result-driven focus changes are also observed. `take_focus_event` de-duplicates
both paths.
- **`start`** — `Skim::fire_start_event` (`src/skim.rs`). `Skim::check_reader`
only records the `reader_done` state; it does not itself emit `load`.
- **`load`/`result`/`zero`/`one`** — these track *async* reader/matcher
completion, which has no synchronous callback, so `App::poll_completion_events`
owns and edge-triggers them from the `Heartbeat` handler (not the render path). A
`Render` is queued just before them so a binding that inspects the list (e.g.
`load:first`) sees the finished results. `result` may fire for intermediate
matcher passes while input is streaming; `zero`/`one` wait for `reader_done`
before reading `MatcherControl::get_num_matched()`, so a transient empty or
one-item pass cannot terminate the finder before later input arrives.
Each event flows through `handle_key` and its keymap lookup like any other key,
so an unbound event is a harmless no-op.
### Actions as Events (follow-up bindings)
Any **action** can also be bound as if it were an event: after the action runs,
a follow-up chain bound to its name is dispatched directly. For example,
`reload:first` runs `first` right after a `reload`, and `first:last` ends on the
last item.
- **Keys win.** If a bind's "key" resolves to a real key it stays in the key
map, so a name shared by a key and an action (e.g. `up`) always binds the key.
Prefix with `act-` to target the action instead: `act-up:down`.
- **Non-recursive.** Follow-up actions use `noremap` semantics: actions in the
right-hand chain do not trigger their own follow-up bindings.
- **`suppress`.** Including [`Action::Suppress`] in the follow-up chain cancels
only the triggering action's default behaviour. Thus
`act-up:suppress+down+up` executes `down` then `up` once. On its own,
`suppress` is a no-op (equivalent to `ignore`).
Follow-up chains are parsed by `binds::parse_action_binds` into
`SkimOptions::action_binds` (keyed by `Action::name`), and applied in
`App::handle_action`, which dispatches each chain member through the private
per-variant `App::dispatch_action` without re-entering `handle_action`.
Conditional actions likewise dispatch their selected subaction chain immediately
through `dispatch_action`, preserving the same non-recursive semantics. When a
directly dispatched subaction accepts or aborts, `App::final_action` records it
and `Skim::tick` copies it to `Skim::final_event`, so output and exit status
reflect the actual terminating action rather than its outer trigger.
The runtime `bind`/`unbind` actions manage action triggers as well as keys:
`bind(act-up:last)` merges into `action_binds` and `unbind(act-up)` removes the
trigger (resolved via `binds::action_trigger_name`), with the same keys-win
precedence as `--bind`.
### Action Dispatch
```
Event::Key(k) → handle_key(k)
├─ lookup k in options.keymap → [Action…]
├─ fallback: Ctrl-C → Quit
├─ fallback: printable char → AddChar(c) or AddChar(uppercase)
└─ emit Vec<Event::Action(a)> to event queue
Event::Action(a) → handle_action(a) → Vec<Event>
```
`handle_action` is a large match statement covering all ~70+ `Action` variants. The local
`define_action_catalog!` macro (in `src/tui/actions.rs`) is the single source for the `Action` enum itself, each
variant's canonical bind name, its parser arm, and the `ACTION_CATALOG` documentation list the manpage's action
section is generated from — so the enum, `Action::name`, `parse_action` and the manpage cannot drift. Key action categories:
| Category | Actions |
| --- | --- |
| Navigation | `Up/Down(n)`, `HalfPageUp/Down`, `PageUp/Down`, `First/Last/Top` |
| Text editing | `AddChar`, `BackwardChar/DeleteChar/Word`, `ForwardChar/Word`, `KillLine`, `Yank`, `UnixLineDiscard/WordRubout` |
| Selection | `Toggle`, `ToggleAll`, `ToggleIn/Out`, `Select`, `SelectAll`, `DeselectAll`, `AppendAndSelect` |
| Query | `SetQuery`, `NextHistory`, `PreviousHistory` |
| Preview | `TogglePreview`, `PreviewUp/Down/Left/Right`, `PreviewPageUp/Down`, `RefreshPreview`, `SetPreviewCmd` |
| Command | `Execute(cmd)`, `ExecuteSilent(cmd)`, `Reload(cmd?)`, `RefreshCmd` |
| Mode | `ToggleInteractive`, `ToggleSort`, `RotateMode` |
| Conditional | `IfQueryEmpty(then, else?)`, `IfQueryNotEmpty(then, else?)`, `IfNonMatched(then, else?)` |
| Lifecycle | `Accept(key?)`, `Abort`, `Cancel` |
| UI | `ClearScreen`, `Redraw`, `SetHeader(text?)`, `SelectRow(n)` |
| Bindings | `Bind(spec)` — add `trigger:action[+action]` bindings (keys or action triggers) at runtime; `Unbind(triggers)` — remove bindings for a comma-separated list of keys or action triggers |
| Custom | `Custom(ActionCallback)` — async or sync closure receiving `&mut App` |
`Action::Custom(ActionCallback)` is the library extension point: callers can inject arbitrary async logic into the action pipeline without forking skim.
---
## Preview System
The preview command string supports placeholder substitution via `App::expand_cmd()`:
| Placeholder | Expands to |
| --- | --- |
| `{}` | text of the focused item |
| `{q}` | current query string |
| `{n}` | index of the focused item |
| `{+}` | space-separated texts of all selected items |
| `{+n}` | space-separated indices of selected items |
Preview execution is debounced (`DEBOUNCE_MS` in `run_preview`). A change in the focused item or query triggers `pending_preview_run = true`; the next `Heartbeat` after the debounce window calls `Preview::spawn()`.
The `ItemPreview` enum (returned by `SkimItem::preview()`) gives library users full control:
```rust
pub enum ItemPreview {
Command(String), // run command, capture stdout
Text(String), // display plain text
AnsiText(String), // display ANSI-colored text
CommandWithPos(String, PreviewPosition),
TextWithPos(String, PreviewPosition),
AnsiWithPos(String, PreviewPosition),
Global, // fall back to --preview option
}
```
---
## Output & Result Collection
`Skim::output()` is called after the event loop exits:
```
Skim::tick()
└─ app.final_action.take() → final_event ← includes nested follow-up/conditional actions
Skim::output()
├─ reader_control.kill() ← stop reader threads
├─ is_abort = !matches!(final_event, Action::Accept)
├─ selected_items = app.results()
│ └─ item_list.items[selection indices] or [current] if no multi
├─ query = app.input.to_string()
├─ cmd = (interactive? input : options.cmd_query? : initial_cmd)
├─ current = item_list.selected() ← focused item
└─ header = app.header.header
```
`SkimOutput` fields returned to caller:
```rust
pub struct SkimOutput {
pub final_event: Event, // Action::Accept or Action::Abort
pub is_abort: bool,
pub final_key: crossterm::event::KeyEvent,
pub query: String,
pub cmd: String,
pub selected_items: Vec<MatchedItem>,
pub current: Option<MatchedItem>,
pub header: String,
}
```
The output phase is `SkimOutput::write_output(&mut out, &BinOptions)` (`src/output.rs`), called by the CLI binary with a buffered stdout. `BinOptions` (also in `src/output.rs`, built via `BinOptions::from_opts`) captures the output-related flags. Keeping the serialization independent of stdout lets it be unit-tested by passing a `Vec<u8>`. It writes, in order:
1. `query` if `--print-query`
2. `cmd` if `--print-cmd`
3. `header` if `--print-header`
4. current item text if `--print-current`
5. `accept_key` if `--expect` matched
6. For each selected item: strips ANSI if `--ansi && !--no-strip-ansi`, prints text + score if `--print-score`
7. If `--output-format <template>`: uses `printf()` to expand a format string with placeholders (this path is exclusive — it replaces steps 1–6)
Exit codes: `0` = items selected, `1` = no items selected, `130` = abort, `135` = tmux launch failed.
---
## IPC / Listen Socket
This subsystem is gated behind the default `listen` Cargo feature, which also pulls in the
`interprocess`, `ron`, and `serde` dependencies. With the feature off, the `--listen` /
`--remote` flags, the `Skim::listener` field, the `select!` listener branch, and the
`serde` derives on `Action` are all compiled out. The `select!` branch cannot carry a
`#[cfg]` attribute (tokio's macro rejects it), so it stays in place but its future becomes
a never-resolving `pending()` and its handler is unreachable (the stream type alias
`RemoteStream` is uninhabited).
When `--listen <socket_name>` is set, `Skim::init_listener()` creates an `interprocess` local socket. The main event loop's `select!` accepts connections and spawns Tokio tasks to read RON-encoded `Action` values line by line:
```
listener.accept() → stream
tokio::spawn:
BufReader(stream).lines()
for each line:
ron::from_str::<Action>(&line)
→ tui.event_tx.send(Event::Action(act))
```
The remote client mode (`--remote <socket_name>`) reads action strings from stdin and sends them to an existing skim instance:
```
// src/bin/main.rs main()
if let Some(remote) = opts.remote {
stream = LocalSocket::connect(socket_name)
loop: read_line → parse_action_chain → ron::to_string → stream.write_all
}
```
This enables scripted control of a running skim session.
---
## Theming
`ColorTheme` (`src/theme.rs`) holds 13 named `ratatui::style::Style` values:
| Field | Covers |
| --- | --- |
| `normal` | Default item text |
| `matched` | Highlighted match characters |
| `current` | Focused item background |
| `current_match` | Match highlights on focused item |
| `query` | Query text in input box |
| `spinner` | Spinner animation character |
| `info` | Status info line |
| `prompt` | Prompt character |
| `cursor` | Cursor indicator |
| `selected` | Multi-selected item marker |
| `header` | Header text |
| `border` | Border lines |
| `scrollbar` | Item list scrollbar thumb |
Built-in palettes: `none`, `bw`, `default16`, `dark256`, `molokai256`, `light256`, `catppuccin_mocha`, `catppuccin_macchiato`, `catppuccin_latte`, `catppuccin_frappe`.
Selected via `--color base_theme[,component:color[:modifier]]`. Individual component overrides use CSS-style RGB hex (`#RRGGBB`), ANSI 256-color indices, or named modifiers (`bold`, `italic`, `underline`, `dim`, `reverse`).
`BorderType` mirrors Ratatui's border styles but adds two internal no-border states:
- `None` is the default `--border=none`; widgets do not draw boxes, but preview separators may still be drawn between panes.
- `ForceOff` is set by `--no-border`; it disables all borders, including tmux/zellij popup borders.
Passing `--border` without a value means `plain`. Passing a value accepts Ratatui styles such as `rounded`, `double`, `thick`, dashed variants, and quadrant variants.
---
## History
Query and command histories are managed in `SkimOptions`:
- Loaded at startup via `SkimOptions::init_histories()` from files specified by `--history-file` / `--cmd-history-file`.
- Stored in `App::query_history` / `App::cmd_history`.
- Navigation with `Action::NextHistory` / `Action::PreviousHistory` uses `history_index: Option<usize>` and `saved_input: String` to restore the original input when returning to the live query.
- Written back to file at exit in `sk_main` via `write_history_to_file()`, which deduplicates the last entry and enforces `--history-size`.
---
## Pre-Selection
`DefaultSkimSelector` (`src/helper/selector.rs`) implements the `Selector` trait:
```rust
pub trait Selector {
fn should_select(&self, index: usize, item: &dyn SkimItem) -> bool;
}
```
Three modes (combinable):
- `first_n(N)` — selects the first N items by index
- `preset(iter)` — selects items whose `text()` is in a `HashSet`
- `regex(pattern)` — selects items matching a regex
Configured via `--pre-select-n`, `--pre-select-items`, `--pre-select-pat`, `--pre-select-file`.
Applied during `ItemList::from_options()` and re-applied when items are appended.
---
## Threading Model
Skim uses a mix of OS threads (for blocking I/O) and Tokio async tasks:
```
Main thread (Tokio runtime)
├─ Skim::run() async loop → tick() → select!
│ ├─ process events synchronously (App::handle_event is sync)
│ └─ block_in_place for ActionCallback::call (async closures)
│
└─ Tokio task: Tui event pump (crossterm EventStream + tick timer)
Matcher ThreadPool (persistent)
└─ Worker threads process atomic match chunks; one separate coordinator thread waits for completion
Reader ThreadPool (persistent)
└─ Short chunk jobs parse items; an in-flight token limit bounds the work queue
Reader threads (OS threads, per invocation):
├─ collect_items thread: blocks on SkimItemReceiver (recv_timeout 1ms), calls ItemPool::append
├─ I/O reader thread: reads large byte chunks, splits lines, assigns sequence numbers
├─ Bounded dispatcher thread: submits chunk jobs only while an in-flight token is available
├─ Reorder thread: sequence-ordered output; drops tx_pipeline_done on EOF
└─ Killer thread: waits for rx_interrupt or rx_pipeline_done; kills a command child if present
Preview threads (OS threads, per preview spawn):
├─ PTY reader, image decoder, or plain-child monitor
└─ Plain mode also has bounded stdout and stderr drain threads
→ writes PreviewContent Arc<RwLock> and sends Event::PreviewReady
IPC handler task (Tokio, per connection):
└─ reads RON actions → sends Event::Action to TUI channel
Popup stdin relay thread (OS thread, only in --popup/--tmux mode):
└─ copies stdin → FIFO for child sk process
```
**Synchronization primitives used:**
- `Arc<Mutex<Option<ProcessedItems>>>` — matcher-to-ItemList result handoff without CPU-spinning under merge contention
- `Arc<AtomicBool>` — `needs_render` (matcher → event loop), `stopped` / `interrupt` (MatcherControl)
- `Arc<AtomicUsize>` — `processed` / `matched` counters, matcher query generation, reader `components_to_stop`
- `Arc<tokio::sync::Notify>` — `items_available` (ItemPool → Skim::tick wakeup)
- `Arc<std::sync::RwLock<PreviewContent>>` — preview thread → Preview widget
- `kanal::Sender/Receiver<Vec<Arc<dyn SkimItem>>>` — item batches through pipeline
The global allocator is `mimalloc` (v3), chosen for its low-latency multi-threaded allocation characteristics critical to the concurrent item-creation pipeline.
---
---
## Public Library API
The minimum surface to embed skim in a Rust application:
```rust
use skim::prelude::*;
// 1. Build options
let options = SkimOptionsBuilder::default()
.height("40%")
.multi(true)
.preview(Some("cat {}"))
.build()
.unwrap();
// 2a. Run with a static item slice
let output = Skim::run_items(options, ["foo", "bar", "baz"]).unwrap();
// 2b. Or stream items through a channel
let (tx, rx) = unbounded::<Vec<Arc<dyn SkimItem>>>();
// … send batches to tx from another thread …
let output = Skim::run_with(options, Some(rx)).unwrap();
// 3. Inspect results
if !output.is_abort {
for item in &output.selected_items {
println!("{}", item.output());
}
}
```
**Implementing `SkimItem`** for custom types:
```rust
struct MyItem { id: u32, label: String }
impl SkimItem for MyItem {
fn text(&self) -> Cow<'_, str> {
Cow::Borrowed(&self.label) // used for matching
}
fn display(&self, context: DisplayContext) -> ratatui::text::Line<'_> {
context.to_line(self.text()) // default implementation; override for custom styling
}
fn output(&self) -> Cow<'_, str> {
Cow::Owned(self.id.to_string()) // printed on accept
}
fn preview(&self, _ctx: PreviewContext<'_>) -> ItemPreview {
ItemPreview::Text(format!("ID: {}\nLabel: {}", self.id, self.label))
}
fn disabled(&self) -> bool {
false // disabled items are visible but cannot be selected
}
}
```
`DisplayContext` exposes the current score, match spans (`Matches::CharIndices`, `CharRange`, `ByteRange`, or `None`), container width, and base/highlight styles. `PreviewContext` exposes the current query, command query, preview dimensions, current index/selection, and multi-selection lists.
**Custom `ActionCallback`** for inline async logic:
```rust
let cb = ActionCallback::new(|app| async move {
// mutate app state, return follow-up events
Ok(vec![Event::Action(Action::Accept(None))])
});
// bind it: options.keymap.insert(key, vec![Action::Custom(cb)]);
```
**`CommandCollector` trait** for custom item sources (e.g. async databases):
```rust
impl CommandCollector for MySource {
fn invoke(&mut self, cmd: &str, components_to_stop: Arc<AtomicUsize>)
-> (SkimItemReceiver, Sender<i32>)
{
// spawn a thread, send batches of Arc<dyn SkimItem>, return rx + kill-tx
}
}
```
Set `options.cmd_collector = Rc::new(RefCell::new(my_source))` before calling `Skim::run_with`.
