Skip to content
tamia6Public

About

Command completion menus and history-based autosuggestions for zsh, Bash and Fish on macOS and Linux

Resources

Stars

29 stars

Watchers

0 watching

Forks

Repository files navigation

rfig — Rust Terminal Autocomplete for zsh, Bash, and Fish

English · 简体中文 · Website

An open-source terminal autocomplete tool with command menus and history-based suggestions.

Built in Rust, rfig brings IDE-style command-line autocomplete to zsh, Bash, and Fish on macOS and Linux. Candidates appear as you type; navigate with the arrow keys, insert one with the right arrow, and continue completing the next argument. Your shell executes the command.

rfig is an independent, Fig-inspired project and is not affiliated with Fig. It uses completion definitions and scripts available in your environment, with sandboxed help analysis as a conditional fallback; it does not promise completion for every command.

Built-in history-based suggestions appear as the first menu row, marked ◷. They match your current directory and typed prefix, so no separate history suggestion plugin is required. Ordinary completions use only what you actually type. There is no inline gray text; Enter always executes your actual input.

rfig demonstrating progressive Git completion, dynamic branches, Brew services, and npm scripts in zsh

The demo shows progressive Git completion from g to gi to git, then checkout and a real branch from the current repository. It also demonstrates dynamic Brew service candidates, npm scripts, arrow-key navigation, insertion, execution, and menu dismissal.

Installation · Usage · Shell support · Completion sources · Testing

rfig v0.3.1 supports macOS and Linux with zsh, Bash 4.4+, and Fish 3.6+. Install with Homebrew, a prebuilt binary, or the source code.

At a glance: terminal autocomplete and nested CLI completion · directory-scoped history at the top of the menu · local usage-based ranking · no AI service or cloud account required.

Features

Feature Behavior
Menus as you type Updates after typing or deleting, without pressing Tab or an artificial debounce delay
Dynamic, nested completion Queries available definitions for subcommands, branches, paths, and more; depth and content depend on the source
History-based autosuggestions Shows at most one directory-scoped history match first, marked ◷; accept explicitly with Right
Usage-based ranking Selections and executed commands affect ranking; up to three candidates with usage records are marked ① ② ③
Category icons and theme colors Category icons, an arrow pointer, and selected text use the terminal's ANSI palette
Multiple completion sources Native definitions, installed scripts, command-provided generators, the Cobra protocol, and cached help data
Background enrichment after setup Quickly scans $PATH, then analyzes eligible user commands sequentially on macOS/Linux when a sandbox is available
Shell coverage zsh ✅, Bash 4.4+ ✅, Fish 3.6+ ✅; other shells are not yet supported

Installation

From source

Requires Rust and Cargo. Run one of the following in the project directory:

sh install.sh                 # Choose integration based on $SHELL
# Or explicitly select a shell
sh install.sh --shell zsh
sh install.sh --shell bash
sh install.sh --shell fish

The installer builds rfig into ~/.local/bin/rfig, then runs rfig setup. It does not change your default shell. macOS ships with Bash 3.2, which is not supported; install Bash 4.4+ before enabling Bash integration.

Homebrew Tap

brew install tamia6/tap/rfig
"$(brew --prefix rfig)/bin/rfig" setup

Homebrew setup links the integration scripts for zsh, Bash, and Fish to the package's stable opt path. After brew upgrade rfig, open a new shell session to load the updated scripts; no additional setup is needed. For an older installation, run setup once with the updated version to migrate copied scripts. Already open sessions keep their loaded functions until restarted.

Prebuilt binaries (no Rust required)

Choose a package for your operating system and CPU from GitHub Releases. Package targets are macos-universal, linux-x86_64, and linux-aarch64; check the release for available assets. Extract it, enter the directory containing install.sh, and run:

sh install.sh

You can download and extract the package anywhere. Each archive includes the binary and installer. The script verifies the files, moves the binary to ~/.local/bin/rfig, and runs setup. Source and binary installations use the same script. New packages include a TARGET manifest; mismatched packages are rejected before the binary is moved. Linux binaries require glibc 2.36+. Options and package contents depend on the downloaded version.

Enable multiple shells

Configure each shell separately:

rfig setup --shell zsh
rfig setup --shell bash
rfig setup --shell fish

Open a new session of the configured shell afterward. Setup can be repeated: it installs the integration script (a stable package link for Homebrew, an embedded copy for source/binary installs), adds ~/.local/bin when needed, and avoids duplicate source lines. Background enrichment jobs for the same installation run sequentially.

Shell Configuration location
zsh $ZDOTDIR/.zshrc, or ~/.zshrc by default
Bash ~/.bashrc; adds a source line to the login configuration if it does not mention .bashrc
Fish $XDG_CONFIG_HOME/fish/conf.d/rfig.fish, or ~/.config/fish/conf.d/rfig.fish by default

Use command -v rfig to check the active installation. If a previous source/binary install at ~/.local/bin/rfig shadows Homebrew, back it up outside $PATH and remove that duplicate executable. Keep a single installation method so the executable and integration scripts stay in sync. Reconfigure each shell you use with "$(brew --prefix rfig)/bin/rfig" setup --shell zsh (or bash / fish), then open new sessions. History and usage records in ~/.config/rfig/ are preserved.

Usage

Start typing to see candidates. Available completion definitions determine which subcommands and dynamic arguments appear; no menu is shown without a usable source. For example, a Git completion definition can query branches in the current repository.

Key Behavior
↑ / ↓ Select a candidate when a menu is visible; otherwise browse history
→ At the end of the line, insert the selected item; a history row fills the whole command without executing it; within the line, move right
Ctrl+E Move to the end of the line without accepting a suggestion
Enter Execute only the actual input; never implicitly accept history or the highlighted menu item
Tab Use the shell's native completion without executing the command
Ctrl+C Cancel the current input

The menu displays up to five rows; use the arrow keys to browse the rest. For ordinary option candidates, a - prefix shows only single-hyphen options; -- shows only double-hyphen options. This rule applies to all commands.

History and usage-based ranking

  • History suggestions: rfig maintains its own directory-scoped history. Typing gi may show ◷ git checkout master first; ordinary candidates still complete only gi. Select history with Right, then Enter to execute. With no history match, ordinary candidates start the menu. History does not use the ① ② ③ usage markers.
  • Fresh installations: history starts empty. Old shell history without working-directory information is not imported automatically.
  • Ranking: scores are accumulated per command context. Selecting a candidate adds 3; recording an execution adds 1. With equal scores, non-option candidates come first. Up to three candidates with usage records receive circled numbers; the rest keep their category icons.
  • Local storage: history and ranking records stay on your computer. Bash/Fish omit commands beginning with a space; zsh follows that rule when HIST_IGNORE_SPACE is enabled.

When using rfig's autosuggestions, remove the zsh-autosuggestions source line from .zshrc or your plugin manager configuration, then open a new session. Fish integration disables Fish's native autosuggestions and uses rfig's directory-scoped history instead.

Icons and colors

Category Icon ANSI color
Command ⌘ Cyan
Subcommand ↳ Magenta
Argument ● Green
Option that takes a value ◇ Blue
Boolean flag ⚑ Yellow

Colors follow the terminal's ANSI palette; rfig does not parse individual terminal theme files. Circled numbers keep the category color, and the selected item uses → and cyan text. Moving between candidates adds brief shifts, glyph changes, and bold text—a character animation rather than actual font scaling.

Categories use available metadata. Without option analysis, -- entries are provisionally treated as options and single - entries as flags, so classification may be approximate.

Shell support

Capability zsh Bash 4.4+ Fish 3.6+
Menus, nested candidates, autosuggestions separate from typed input ✅ ✅ ✅
Directory-scoped history, usage ranking, category colors, circled numbers ✅ ✅ ✅
Setup integration and completion for rfig itself ✅ ✅ ✅
Multiline paste without automatic execution ✅ ✅ Returns to native editor ✅ Returns to native editor

zsh uses ZLE; Bash/Fish share a Rust editing layer. cd, functions, and variable changes still run in the current shell. Bash/Fish support default Emacs editing and Vi insert mode. Esc returns to the native editor; Ctrl+R uses native history search. Stale completion results are discarded.

Linux requirements: x86_64 and ARM64 are supported, with the shell versions listed above. Help analysis uses built-in Landlock + seccomp and needs no additional sandbox tool. It requires Landlock ABI 3+ (typically Linux 6.2+) and permission to use the relevant system calls. Older kernels or restricted containers refuse help probing; menus, history, and existing completion definitions remain available. Check the kernel with uname -r and actual probing with rfig analyze <command>. A distribution name alone does not determine kernel capabilities.

macOS uses the system sandbox-exec. Linux binaries target glibc 2.36; older userspaces may try building from source. Windows and other shells are not yet supported.

Completion sources and background enrichment

While typing: candidates from your environment

rfig does not maintain a fixed completion database for every command. Each adapter uses available sources:

Entry point Lookup behavior
zsh Registered definitions first; otherwise $fpath scripts, generated zsh scripts, external sources, and cached help data
Bash/Fish Current-shell definitions and autoloaded scripts, generated scripts for that shell, external sources, and cached help data
External sources Recognized Cobra __complete protocols and locally installed Fish/Bash scripts
Help cache Cached subcommands and options for each analyzed command path when no other source is available; dynamic arguments still need a completion provider

Definitions and loading behavior differ between shells, so candidates may differ. Background enrichment does not eliminate queries while typing: dynamic completion scripts still run when needed. Use trusted completion scripts.

Help analysis walks declared subcommands breadth first, querying each path with --help / -h until it reaches a leaf, with no fixed depth limit. Each path has its own cached options and children, shared by zsh, Bash, and Fish. Probes remain sequential and sandboxed with existing per-process limits; repeated parent help stops that branch. Failed probes keep existing cache data and are reported. Menus read this cache without running new help scans while typing. Help cannot discover dynamic resource names or positional values by itself. At a known subcommand group, filesystem-only fallback does not override cached children; an empty source can also use the cache. Native dynamic results at leaf commands remain preferred.

After setup: quick scan, then sequential enrichment

  1. Scan: enumerate executables and symbolic links in the current $PATH, and index zsh definitions and common zsh/Fish/Bash completion directories. This is not a whole-disk scan; programs outside $PATH may not be discovered.
  2. Select: skip commands with existing definitions. Automatically probe only permitted, common user installation directories. System commands and other sources may be cataloged without being executed automatically.
  3. Enrich: on macOS/Linux, read --help, then -h if needed, one command at a time in an available sandbox. Identify advertised generators, generate and syntax-check scripts for installed shells, recognize Cobra protocols, and cache subcommands and option categories. Recognition and syntax checks do not guarantee semantic correctness for every candidate.
  4. Constrain: probing denies file writes and network access, with a 500 ms timeout per process invocation plus CPU and output limits. Linux additionally limits file metadata changes, process-group escape, address space, and process count. Writes to pre-opened output pipes/files and /dev/null are allowed. Script syntax checks also use the sandbox and timeout. Complex, resource-intensive, or network-dependent commands may yield no results. See Linux implementation and boundaries (Chinese).
  5. Refresh: rerunning setup reanalyzes caches older than the command executable or rfig. Some commands may have no menu until enrichment finishes or a usable definition is available.
rfig setup                         # Rescan after PATH or installed commands change
cat ~/.config/rfig/enrich.status    # View analyzed / skipped / failed counts
rfig analyze <command>             # Refresh a command and its nested help tree's cache; requires a sandbox
rfig --help                        # List public commands and usage

In enrich.status, done means processing has finished, not that every command succeeded. unavailable means the environment lacks the required isolation support. rfig setup --help only prints help; it does not install or scan.

Local data and uninstalling

Path relative to ~/.config/rfig/ Purpose
commands.txt / supported.txt Discovered command names / commands with discovered definitions
rfig.zsh / rfig.bash / rfig.fish Integration scripts: stable package links for Homebrew, embedded copies for source/binary installations
generated/*.{zsh,bash,fish} / protocol/* Generated, syntax-checked scripts / recognized protocols
options/*.tsv / fallback/*.tsv Root option categories / legacy root candidates
help/<command>/ Per-path help cache, including nested subcommands and leaf options
enrich.status / enrich.lock Background progress / lock preventing duplicate jobs
usage.log Candidate selection and command execution records for ranking
history.tsv Command history with working directories, permissions 0600

Delete usage.log to reset ranking, or history.tsv to clear autosuggestion history, then restart the shell. History contains command text; manage it according to your needs.

To uninstall, remove rfig's source line from each configured shell. For Fish, remove conf.d/rfig.fish. Delete ~/.local/bin/rfig for source/binary installations, or run brew uninstall rfig for Homebrew. Remove ~/.config/rfig/ when its data is no longer needed, then restart the shell.

FAQ

Is rfig a Fig alternative?

rfig is an independent, open-source terminal autocomplete project inspired by Fig. It is not affiliated with Fig and does not claim compatibility with every Fig feature or specification.

Does rfig complete every command?

No. Candidate coverage depends on completion definitions, scripts, generators, and cached help available on your system. Some commands may have no candidates or only basic help-derived candidates.

Does rfig use AI?

No. Completion, history suggestions, and usage ranking run locally; no AI service or cloud account is required.

Testing

Tests send real keystrokes through tmux/PTY and check the screen and arguments received by commands. Coverage includes autosuggestions, menus, ranking, directory-scoped history, special characters, multiline paste, and process cleanup.

cargo test
cargo build
sh tests/docker/run.sh
RFIG_TEST_IMAGE=rust:1.91-slim BUILD_BASH44=0 sh tests/docker/run.sh

Docker tests use an isolated HOME, an unprivileged user, resource limits, and no network during testing. Results are saved in target/docker-results/. See the test instructions.

About

Command completion menus and history-based autosuggestions for zsh, Bash and Fish on macOS and Linux

Resources

Stars

29 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages