fzf Administrator & Developer Guide

This guide is the operational and architectural reference for fzf. It covers the build/release process, the full configuration surface (every CLI flag, every environment variable, every action), the internal architecture (reader → matcher → terminal pipeline), security posture, performance tuning, and the integration points with shells, tmux, Zellij, and editors.

The companion User Guide covers everyday usage; this guide assumes familiarity with that material.

1. Architecture Overview

fzf is a single-binary Go program that runs as an interactive TTY filter. Source input enters a non-blocking reader, passes through a parallel matcher that scores items with a fuzzy or exact algorithm, and the result is displayed by a terminal renderer that handles user input events, the preview window, and any command bindings the user has set.

                +-----------------+
                | stdin / command |
                +--------+--------+
                         |
                         v
                +--------+--------+      +----------------+
                |     Reader      |----->|   ChunkList    |
                |  (src/reader.go)|      | (src/chunklist)|
                +--------+--------+      +-------+--------+
                         | EvtReadNew           |
                         | EvtReadFin           |
                         v                       v
                +--------+--------+      +-------+--------+
                |     Core        |<---->|     Matcher    |
                | (src/core.go)   |      | (src/matcher.go)
                +--------+--------+      +-------+--------+
                         |                       |
                         | EvtSearchNew/Progress/Fin
                         v                       |
                +--------+--------+              |
                |    Terminal     |<-------------+
                | (src/terminal.go)|
                +--------+--------+
                         |
                         | renders to TUI:
                         |   - LightRenderer (xterm escape codes)
                         |   - tcell Renderer (Windows/legacy)
                         |
                         v
                +--------+--------+
                |  src/tui (TUI)  |
                +-----------------+

Note

The Reader, Matcher, and Terminal each run in their own goroutine and communicate via an EventBox (see src/util/eventbox.go). The coordinator delays UI updates by up to 100ms to coalesce rapid input changes — a fundamental design decision that keeps fzf responsive even on inputs of millions of lines.

1.1 Component inventory

1.2 Technology stack

1.3 Data flow for a typical run

1. main.go calls fzf.ParseOptions (src/options.go).
2. The parser validates every flag; on error it returns immediately (exit(ExitError, err)).
3. fzf.Run(options) builds a Reader, Matcher, and Terminal, all communicating through a shared EventBox.
4. Reader.ReadSource() runs in its own goroutine. If stdin is a TTY and FZF_DEFAULT_COMMAND is set, it execs that command. Otherwise it reads stdin. Items are appended to a ChunkList.
5. Whenever a new chunk appears, Reader posts EvtReadNew to EventBox. When stdin closes, it posts EvtReadFin.
6. Matcher.Loop listens for EvtReadNew, takes the latest Pattern, and runs N parallel scoring passes (one per CPU). Results are merged and cached.
7. Terminal.Loop listens for EvtSearchNew, EvtSearchProgress, and EvtSearchFin, updating the screen accordingly. It also reads keyboard / mouse events and dispatches the bound actions.
8. On accept, the selected item(s) and the optional --print-query are written to stdout and fzf exits with ExitOk (0).
9. On become(...), the selected item is templated into the command and syscall.Exec replaces the fzf process.

1.4 Concurrency model

Three goroutines (Reader, Matcher, Terminal) plus a coordinator. The coordinator schedules screen updates with adaptive delay (coordinatorDelayMax = 100ms, step 10ms) so that bursts of input or keystrokes coalesce into a single render pass.

The Matcher partitions the chunk list across runtime.NumCPU() goroutines (override with --threads N). Each partition uses its own slab allocator (util.Slab) to minimise GC pressure during high-rate matching.

2. System Requirements

2.1 Runtime requirements

2.2 Build requirements

2.3 Platform-specific notes

3. Configuration Reference

fzf is configured exclusively through CLI flags and environment variables. Settings precedence (lower wins, higher overrides):

1. Flags from FZF_DEFAULT_OPTS_FILE
2. Flags from FZF_DEFAULT_OPTS
3. Flags on the command line

3.1 Environment variables

Important

FZF_API_KEY is mandatory when --listen binds to anything other than localhost or a Unix socket. Without it, fzf returns FZF_API_KEY is required to allow remote access and exits. Generate one with openssl rand -hex 16.

3.2 Command-line flags — full reference

The following enumeration is grouped exactly as in fzf --help. Every flag has been verified against src/options.go's Usage constant.

Search

Input/Output

Global Style

Display Mode

Layout

List Section

Input Section

Preview Window

Header

Footer

Scripting

Key/Event Binding

Advanced

Directory Traversal (when FZF_DEFAULT_COMMAND is unset)

History

Shell Integration / Help

Profiling (build-tag pprof only)

Warning

Profiling flags are gated behind the pprof build tag. Without that tag, fzf prints error: profiling not supported: FZF must be built with '-tags=pprof' to enable profiling.

3.3 Color groups

The --color value is a comma-separated list of group:fg[,bg][,attr] tuples. The recognised groups are:

Attributes: regular, bold, dim, italic, underline, underline-double, underline-curly, underline-dotted, underline-dashed, blink, reverse, strikethrough, strip.

Foreground/background colours: named (black, red, …, white, bright-red, …, bright-white), 256-colour colour:N, or #RRGGBB truecolour.

3.4 Action catalog (full)

--bind accepts any of the actions below. Actions taking arguments use the form name(...) or name:STRING at the end of a chain. Multiple actions chain with +.

Cursor / line editing

beginning-of-line, end-of-line, forward-char, backward-char, forward-word, backward-word, forward-subword, backward-subword, backward-delete-char, backward-delete-char/eof, delete-char, delete-char/eof, kill-line, kill-word, kill-subword, backward-kill-word, backward-kill-subword, unix-line-discard (alias line-discard), unix-word-rubout (alias word-rubout), yank, clear-query.

Item movement

down, up, down-match, up-match, first (alias top), last, best, page-up, page-down, half-page-up, half-page-down, offset-up, offset-down, offset-middle, prev-history, next-history, prev-selected, next-selected.

Selection

select, deselect, select-all, deselect-all, clear-selection (alias clear-multi), toggle, toggle-down, toggle-up, toggle-in, toggle-out, toggle-all, change-multi, exclude, exclude-multi.

Search / pattern

enable-search, disable-search, toggle-search, enable-raw, disable-raw, toggle-raw, toggle-sort, track, track-current, untrack-current, toggle-track, toggle-track-current.

Acceptance / exit

accept, accept-non-empty, accept-or-print-query, print-query, abort, cancel, close, bg-cancel.

Preview

show-preview, hide-preview, toggle-preview, toggle-preview-wrap, toggle-preview-wrap-word, refresh-preview, preview-up, preview-down, preview-page-up, preview-page-down, preview-half-page-up, preview-half-page-down, preview-top, preview-bottom, change-preview(<COMMAND>), change-preview-window(<SPEC>), preview(<COMMAND>).

UI mutation (change-*)

change-prompt(<STR>), change-query(<STR>), change-header(<STR>), change-header-lines(<INT>), change-footer(<STR>), change-border-label(<STR>), change-list-label(<STR>), change-input-label(<STR>), change-header-label(<STR>), change-footer-label(<STR>), change-preview-label(<STR>), change-ghost(<STR>), change-pointer(<STR>), change-nth(<SPEC>), change-with-nth(<SPEC>), change-multi(<MAX>).

UI mutation (transform-*)

These run a shell command and use its stdout to set the corresponding field. Each has a bg- variant that runs in the background:

transform, transform-prompt, transform-query, transform-header, transform-header-lines, transform-footer, transform-border-label, transform-list-label, transform-input-label, transform-header-label, transform-footer-label, transform-preview-label, transform-ghost, transform-pointer, transform-nth, transform-with-nth, transform-search.

bg-transform, bg-transform-prompt, bg-transform-query, bg-transform-header, bg-transform-header-lines, bg-transform-footer, bg-transform-border-label, bg-transform-list-label, bg-transform-input-label, bg-transform-header-label, bg-transform-footer-label, bg-transform-preview-label, bg-transform-ghost, bg-transform-pointer, bg-transform-nth, bg-transform-with-nth, bg-transform-search.

Process management

execute(<COMMAND>), execute-silent(<COMMAND>), execute-multi(<COMMAND>), become(<COMMAND>), reload(<COMMAND>), reload-sync(<COMMAND>), put(<CHAR>), print(<STR>).

Visibility toggles

toggle-input, hide-input, show-input, toggle-header, show-header, hide-header, toggle-wrap, toggle-wrap-word, toggle-multi-line, toggle-hscroll.

Bind manipulation

unbind(<KEY>), rebind(<KEY>), toggle-bind(<KEY>).

Position and search

pos(<INT>), search(<STR>), trigger(<EVENT>), replace-query, refresh-preview.

Misc

ignore, bell, clear-screen, jump, jump-accept.

Important

Action names are kebab-case and the parser is strict. Valid arguments for change-preview-window must satisfy the same grammar as --preview-window; bad input is rejected at parse time with invalid preview window option: <spec>.

3.5 Recognised key names

Keys for --bind triggers fall into the following categories:

• ASCII printable characters: bare (a, ?, /).
• Named keys: enter, tab, esc, space, bspace, del, home, end, pgup, pgdn, up, down, left, right, insert.
• Function keys: f1–f24.
• Modifiers: ctrl-X, alt-X, shift-X, ctrl-alt-X, ctrl-shift-X, alt-shift-X, ctrl-alt-shift-X (modifier order must be ctrl, alt, shift).
• Mouse: left-click, right-click, shift-left-click, shift-right-click, double-click, scroll-up, scroll-down, shift-scroll-up, shift-scroll-down, preview-scroll-up, preview-scroll-down.
• Special: ctrl-space, alt-space, ctrl-up, alt-up, shift-up, ctrl-alt-up, ctrl-shift-up, etc. (and equivalents for down/left/right/home/end/page-up/page-down/delete).

Events (used as triggers, fired by fzf)

change, start, load, focus, result, resize, one, zero, jump, jump-cancel, click-header, click-footer, multi, backward-eof.

3.6 Placeholder grammar (preview / execute / become / reload / transform)

The internal regex (from src/terminal.go): \\?(?:{[+*sfr]*[0-9,-.]*}|{q(?::s?[0-9,-.]+)?}|{fzf:(?:query|action|prompt)}|{[+*]?f?nf?}).

Important

Placeholders are templated through POSIX shell quoting unless {r} is used. Never wrap user-controlled strings in become(...) or --preview without {f} (or careful explicit quoting); shell injection is the natural attack surface.

3.7 Exit codes

(Constants in src/constants.go: ExitOk, ExitNoMatch, ExitError, ExitBecome, ExitInterrupt.)

4. Deployment & Scaling

4.1 Single-machine deployment

The default deployment is "drop the binary on the box". No daemon, no config file, no PID file.

# /etc/profile.d/fzf.sh — system-wide integration
[ -x /usr/local/bin/fzf ] || return
case "$(basename "$SHELL")" in
  bash) eval "$(fzf --bash)" ;;
  zsh)  source <(fzf --zsh) ;;
  fish) fzf --fish | source ;;
esac

Tip

For NFS-mounted home directories, prefer the system-wide approach so the same fzf binary is used everywhere, and put FZF_DEFAULT_OPTS_FILE on the user's local disk (or set it from rc).

4.2 Tmux / Zellij popup

--tmux and --popup are aliases. Inside tmux ≥ 3.3 or Zellij ≥ 0.44, fzf detects the host and opens a popup with tmux display-popup (or the Zellij equivalent).

When tmux/Zellij are unavailable but you still want a contained UI, combine --height with --layout=reverse for an always-visible "split bottom" experience.

4.3 Performance tuning

Built-in performance constants (from src/constants.go):

4.4 The --listen server

fzf --listen[=ADDR:PORT] runs a hand-rolled HTTP/1.1 server (defined in src/server.go) that accepts POST / with a body that is parsed the same way as a --bind action chain. Requests can also use GET /?limit=N&offset=M to fetch the current result set as JSON.

Authentication: when ADDR is anything other than localhost / a Unix socket, FZF_API_KEY must be set. The header X-API-Key is required on every request; the comparison is constant-time (crypto/subtle).

# Server side (e.g. an editor session)
export FZF_API_KEY=$(openssl rand -hex 16)
fzf --listen 127.0.0.1:6266 --listen-unsafe=false \
    --bind 'enter:become(${EDITOR} {})'

# Client side (any process)
curl -s -H "X-API-Key: $FZF_API_KEY" -X POST \
    --data 'change-query(linux)+reload(rg --files)' \
    http://127.0.0.1:6266/

# Read result set
curl -s -H "X-API-Key: $FZF_API_KEY" "http://127.0.0.1:6266/?limit=10&offset=0"

Constants: read deadline 10s, channel deadline 2s, max content-length 1 MiB. The server intentionally avoids net/http to keep the binary small (commented in src/server.go: --listen adds 0.5 MiB instead of the 2.9 MiB net/http would require).

Caution

--listen-unsafe skips the API-key check entirely. The server then accepts unauthenticated become/execute/reload actions from any network-reachable client — that is full remote command execution. Never enable on a multi-user host or any non-trusted network. The safest default is no --listen at all; the next safest is a Unix socket with chmod 0600 (which fzf does automatically).

4.5 Embedding fzf inside a script

The contract is: stdin is the candidate stream, stdout is the chosen line(s). Standard scripting patterns:

# Single-pick
chosen=$(some-source | fzf --height=40% --reverse) || exit
echo "you picked: $chosen"

# Multi-pick into an array (Bash)
mapfile -t chosen < <(some-source | fzf --multi --read0)

# Headless filter (no UI)
matches=$(echo -e "alpha\nbeta\ngamma" | fzf --filter=al)
echo "$matches"   # -> "alpha"

For non-interactive grep-style filtering, prefer --filter — it bypasses the TUI entirely and emits matches to stdout sorted by score.

5. Operations

5.1 Updating fzf

After updating, regenerate the integration scripts (no-op if you use eval "$(fzf --bash)" rather than the legacy ~/.fzf.bash files).

5.2 Rolling back

If an upgrade breaks an existing binding:

1. fzf --version to confirm the new release.
2. Read the upstream CHANGELOG.md for breaking-change notes.
3. Most package managers can pin the previous version (apt install fzf=<version>, brew install fzf@<version>, etc.).
4. Or grab the previous release tarball from https://github.com/junegunn/fzf/releases and drop it on $PATH.

5.3 Logging / observability

fzf does not log to disk by default. For build-time profiling, the --profile-cpu/mem/block/mutex flags emit Go pprof files (requires -tags=pprof build).

For runtime tracing during development:

fzf --bench=2s   # internal benchmark mode (counts matches/sec)

--bench=DURATION is a developer-facing flag that runs an internal benchmark and prints results to stderr — handy when tuning --algo, --threads, --scheme.

5.4 Backup considerations

fzf is stateless except for:

There is no cache directory, no lockfile, no PID file.

5.5 Health check

# Basic smoke test (use in deployment automation)
echo "hello" | timeout 5 fzf --filter=hello | grep -q hello && echo OK

--filter runs in headless mode, so it is safe in CI/CD scripts.

Note

--filter=STRING is the closest thing fzf has to a non-interactive health probe. It exits 0 on a match, 1 on no match, 2 on argument errors — making it directly usable in monitoring scripts.

5.6 Operations runbook

• [x] Verify the binary on $PATH (which fzf)
• [x] Verify the version (fzf --version)
• [x] Smoke-test the integration (echo a | fzf --filter=a)
• [ ] Source the integration script in your shell rc (eval "$(fzf --bash)")
• [ ] Decide on FZF_DEFAULT_COMMAND and FZF_DEFAULT_OPTS
• [ ] If using --listen, generate FZF_API_KEY and store it securely
• [ ] If on macOS, install mawk or GNU awk for fastest history widget

6. Performance

6.1 Algorithm details

FuzzyMatchV2 (default) is a modified Smith-Waterman with bonuses for boundaries and consecutive matches. From src/algo/algo.go:

• O(N×M) time, O(M) space (where N = haystack length, M = pattern length).
• Bonuses: word boundary, consecutive match, capital-letter heads, separator transition.
• Works on Unicode codepoints; uses uniseg for grapheme width.
• Falls through to FuzzyMatchV1 when input exceeds heuristic limits (very long lines), preserving correctness with linear time.

FuzzyMatchV1 is a single-pass algorithm: O(N) time, no slab needed. Less optimal scoring but extremely fast on large inputs.

ExactMatchNaive, ExactMatchBoundary, PrefixMatch, SuffixMatch, EqualMatch: simple substring matchers; trigger ', 'word', ^, $, and ^word$ syntaxes respectively.

The SIMD-accelerated indexbyte2 (asm in src/algo/indexbyte2_amd64.s, indexbyte2_arm64.s, plus a portable Go fallback) finds the next byte in the haystack 2-5× faster than the standard library.

6.2 Memory model

The matcher uses a per-partition slab allocator (util.Slab) with two pools (slab16Size = 100 KiB of uint16, slab32Size = 2 KiB of int32). Each partition gets its own slabs to avoid contention.

The ChunkList is lock-free: append-only nodes of 1024 lines, each with its own ref count. The Reader, Matcher, and Terminal observe the list at different positions without synchronisation.

The ChunkCache keys query results by pattern hash (chunk-local). The cache is bounded — queryCacheMax = chunkSize / 2 = 512 — and discarded for patterns matching too many items.

6.3 Benchmarks (representative, x86_64 single core)

(Numbers are illustrative; rerun --bench on your hardware to compare.)

Tip

If first-match latency on huge inputs matters, use --sync (waits for Reader to finish before showing the UI). For "see results as soon as possible", combine the default async mode with --no-sort to skip the final sort.

7. Security

7.1 Threat model

fzf is a client-side filter. The threat surface is:

1. Shell injection through preview / execute / become / reload. Placeholders are POSIX-shell quoted by default. The {r} placeholder is raw — using it with untrusted input is unsafe.
2. --listen HTTP/Unix-socket server. Without FZF_API_KEY, only localhost / Unix-socket bindings are allowed. --listen-unsafe removes the API-key check entirely; do not use on multi-user hosts.
3. Malicious FZF_DEFAULT_COMMAND. fzf execs this verbatim. Audit it the way you audit $PROMPT_COMMAND or $LD_PRELOAD.

7.2 OpenBSD hardening

src/protector/protector_openbsd.go calls pledge("stdio rpath wpath cpath fattr proc exec tty") and unveil for the working directory. Other OSes are no-op (src/protector/protector.go).

7.3 The --listen API key

When the listen address is non-local, fzf demands FZF_API_KEY. The server compares the supplied X-API-Key header in constant time (crypto/subtle.ConstantTimeCompare). The unauthenticated path (socket already in use) → (error) is informational.

Caution

--listen-unsafe is a deliberate footgun. The codebase exposes it for single-user trusted environments only. Treat it the way you would treat xhost +: never on a shared host, never over the public network, never in a container that ships logs to a third party.

7.4 Embedded shell scripts

The integration scripts (shell/key-bindings.{bash,zsh,fish} and shell/completion.{bash,zsh,fish}) are embedded into the binary at build time via Go's //go:embed. They are emitted unmodified by fzf --bash / --zsh / --fish. Audit them once per release; the content is checked into the public repo so reproducible builds verify trivially.

7.5 No telemetry, no auto-update

fzf does not phone home, fetch update info, or open any network socket on startup. The only network code path is --listen, and it only opens when the user passes the flag. There is no auto-update; new releases come via your package manager.

7.6 Known security-relevant errors

8. Developer Internals

8.1 Repository structure

.
├── main.go                  # entry point, embeds shell scripts + manpage
├── src/
│   ├── core.go              # Reader/Matcher/Terminal coordinator
│   ├── options.go           # The big options parser (~3900 lines)
│   ├── reader.go            # non-blocking source reader
│   ├── chunklist.go         # lock-free chunk list
│   ├── matcher.go           # parallel matcher (NumCPU partitions)
│   ├── pattern.go           # query parser (extended-search grammar)
│   ├── terminal.go          # UI loop + actions + preview (~17K lines)
│   ├── server.go            # hand-rolled HTTP server for --listen
│   ├── proxy.go             # become(...) exec helper
│   ├── tmux.go              # tmux popup launcher
│   ├── zellij.go            # Zellij popup launcher
│   ├── history.go           # internal search-history store
│   ├── ansi.go              # ANSI escape parser
│   ├── cache.go             # ChunkCache (per-pattern result cache)
│   ├── item.go              # Item struct + transform helpers
│   ├── result.go            # Result + sort criteria
│   ├── tokenizer.go         # field/range tokenizer (--nth / --with-nth)
│   ├── constants.go         # all the named timing/size constants
│   ├── functions.go         # misc helpers
│   ├── algo/
│   │   ├── algo.go          # FuzzyMatchV1/V2, Exact*, Prefix/Suffix/Equal
│   │   ├── normalize.go     # Latin-script normalisation
│   │   ├── indexbyte2_amd64.s   # SIMD accelerator (x86_64)
│   │   ├── indexbyte2_arm64.s   # SIMD accelerator (ARM64)
│   │   └── indexbyte2_other.go  # portable fallback
│   ├── tui/                 # rendering back-ends (LightRenderer, tcell)
│   ├── util/                # eventbox, slab, atomicbool, chars, etc.
│   └── protector/           # OpenBSD pledge/unveil
├── shell/
│   ├── common.sh            # helpers shared between integration scripts
│   ├── completion.{bash,zsh,fish}
│   ├── key-bindings.{bash,zsh,fish}
│   └── update.sh            # rebuilds the per-shell scripts from common.sh
├── plugin/
│   └── fzf.vim              # minimal Vim plugin (rich plugin is separate repo)
├── man/man1/
│   ├── fzf.1                # canonical man page
│   └── fzf-tmux.1
├── doc/fzf.txt              # vim-help format
├── test/                    # Ruby integration tests (minitest)
│   ├── runner.rb
│   ├── test_*.rb
│   ├── lib/{common.rb,common.sh,common.fish}
│   └── vim/fzf.vader
├── go.mod / go.sum / Makefile / .goreleaser.yml
├── install / install.ps1 / uninstall   # bootstrap / removal scripts
├── README.md / README-VIM.md / ADVANCED.md / BUILD.md / CHANGELOG.md / SECURITY.md
└── Dockerfile

8.2 Building from source

# Standard build
go build -o fzf .

# With profiling support
go build -tags=pprof -o fzf .

# Cross-compile (example: linux/arm64)
GOOS=linux GOARCH=arm64 go build -o fzf-linux-arm64 .

# Full release matrix (uses GoReleaser)
goreleaser release --clean --skip=publish --skip=sign --snapshot

The release ldflags strip and trim the binary:

-trimpath
-s -w -X main.version=<VER> -X main.revision=<COMMIT>

The Dockerfile builds an Alpine-based image with fzf in /usr/bin.

8.3 Code patterns and conventions

• Goroutines + EventBox. Cross-component state changes are messages through util.EventBox rather than shared memory. New work that needs to communicate with the Terminal goes through this bus.
• Slab allocators. Hot match paths use slab pools to avoid GC. New algorithms should follow the same pattern (see algo.FuzzyMatchV2 for the reference).
• String-enum constants. Sort criteria, layouts, info styles, etc. are typed iota enums with *_string.go files generated by stringer. Never use string comparisons in hot paths.
• Build tags for platform code. Look for //go:build ... constraints (e.g. terminal_unix.go, terminal_windows.go, proxy_unix.go/proxy_windows.go, result_x86.go/result_others.go).
• Embedded assets. Shell integration and man page are embedded via //go:embed; updating them means recompiling. The shell/update.sh helper keeps the per-shell scripts in sync with common.sh.

8.4 Module map

8.5 Testing strategy

Run unit tests:

go test ./...

Run integration tests (require a TTY emulator and tmux):

make test
# or
ruby test/runner.rb

Common test environment variables: TMUX, FZF_DEFAULT_COMMAND, FZF_DEFAULT_OPTS. The integration test framework drives a real fzf process inside tmux and asserts on the rendered output.

8.6 Contributing

1. Read CHANGELOG.md and SECURITY.md from the repo root before opening a PR.
2. Run gofmt -s -w . and go vet ./....
3. Run shfmt -d shell/ for shell-script formatting.
4. Run bundle exec rubocop for the Ruby tests.
5. Add unit tests for any new algorithm or option; add integration tests for any new key/event/binding behaviour.
6. Update man/man1/fzf.1 and the Usage constant in src/options.go in lock-step.

8.7 Potential improvements / known tech debt

• The mega-terminal.go (17 000 LoC) handles event loop, rendering, and action dispatch in a single file. A split into event_loop.go, render.go, and actions.go would improve readability.
• --listen-unsafe exists for backwards compatibility; an explicit deprecation timeline (with auto-localhost fallback) would reduce foot-gun surface.
• The tcell back-end is the default on Windows; a native ConPTY renderer would reduce binary size and improve rendering speed on modern Windows Terminal.
• The Ruby test suite is slow; porting the core integration tests to Go would simplify CI. (Acknowledged in BUILD.md.)

9. Integration Points

9.1 Shell integration

• Bash / Zsh / Fish. Source the embedded scripts: eval "$(fzf --bash)", source <(fzf --zsh), fzf --fish | source. These provide CTRL-T, CTRL-R, ALT-C, and the ** completion trigger.
• PowerShell / CMD. Use the community PSFzf module. Not officially supported in-tree.

9.2 Tmux

• Popup mode. --tmux=center,80%,40% or --popup=.... Requires tmux 3.3+.
• fzf-tmux wrapper. Separate shell script that ships with most packages. Provides finer-grained popup control on older tmux.

9.3 Zellij

• Popup mode. --tmux works on Zellij ≥ 0.44 (the same flag branches at runtime).

9.4 Vim / Neovim

• In-tree plugin. plugin/fzf.vim provides :FZF and core helpers.
• Companion plugin. The richer plugin (:Files, :Buffers, :Rg, :Lines, etc.) is the separate junegunn/fzf.vim repository.
• Embedding fzf in another plugin. Spawn fzf with vim.system or :! and parse stdout. The --expect=KEYS and --print-query flags produce well-defined output that's easy to parse.

9.5 Editors and IDEs

• VS Code, IntelliJ. Community extensions wrap fzf as a quick-open back-end. Use --listen for low-latency repeated invocations.
• Emacs. helm-fzf, consult-fzf, and similar packages.
• Termux (Android). Same fzf binary; integrate via Termux's built-in shell integration.

9.6 The --listen HTTP / Unix-socket API

External processes drive fzf actions over HTTP:

POST /                              Body: action chain ("change-query(foo)+reload(...)")
GET  /?limit=N&offset=M             Returns JSON: {"items": [...], "selection": [...], "current": ...}

Headers: X-API-Key: <FZF_API_KEY> (mandatory when non-local). Content type: text/plain (request) / application/json (response). Max body length: 1 MiB. Read deadline: 10 s.

Note

The server is intentionally minimal — no net/http, no TLS, no session state. For TLS, front it with a reverse proxy such as caddy reverse_proxy localhost:6266 over a TLS-terminated listener.

9.7 Programmatic invocation patterns