█▀▀▀▀▀▀▀█▀▀▀▀▀▀▀█▀▀▀▀▀▀▀█▀▀▀▀▀▀▀█
█   ▄▄▄▄█   ▄   █   ▄▄▄▄█▄▄   ▄▄█
█       █       █       ███   ███
█   █████   █   █▀▀▀▀   ███   ███
█▄▄▄█████▄▄▄█▄▄▄█▄▄▄▄▄▄▄███▄▄▄███

FAST is a Shell Traverser

Table of Contents

• Features
• Installation
• Shell Integration
• Usage
• License

Features

fast is a small, cross-platform TUI for ls + cd.

• Responsive on huge directories

  Directory entries are discovered and rendered in chunks instead of waiting for the complete scan. The first results appear while the rest are still being scanned, so browsing can start immediately.

• Skip repeat scans

  Visited directories are cached and reused when unchanged, avoiding a full scan. Missing or stale cache entries trigger a fresh scan instead.

• Keyboard-first navigation

  Start in the current directory, browse its child directories, return to the parent, rescan, and select a directory without leaving the keyboard. A directory without a remembered selection highlights its `.` current-directory entry; remembered selections are restored when available and fall back to `.` if the entry is gone.

• Simple filtering

  Switch to predictable, case-insensitive substring matching with Tab. The .. and . navigation entries remain available while filtering.

• Fuzzy filtering

  Fuzzy matching is the default filter mode. Query characters only need to appear in order, and better-scoring names are ranked first when an exact substring is not convenient. Press Tab to switch to simple matching.

• On-demand file listing

  Press F to include files and other non-directory entries from the current directory, but fast never launches files or opens them through MIME associations.

• Clipboard path copy

  Press y to copy the highlighted logical path through OSC 52 without leaving the navigator. The terminal emulator or multiplexer must permit OSC 52 clipboard commands.

• Shell integration

  Bash, Zsh, and Nushell wrappers read the selected path and apply it with cd in the parent shell. Confirm with q to change directories, or cancel with Esc without changing the shell.

Installation

Download a Release

Download an archive from the Releases page. Extract it, put the fast binary in PATH, and keep the bundled shell/ directory available for shell integration.

Build from Source

Install the binary with Cargo:

cargo install --path .

If Cargo's binary directory is not already in PATH, add it before using the wrapper:

# Bash/Zsh
export PATH="$HOME/.cargo/bin:$PATH"

# Nushell
$env.PATH = ($env.PATH | prepend ($nu.home-dir | path join ".cargo" "bin"))

For a local checkout without installing, build the binary and set FAST_BIN:

cargo build

# Bash/Zsh
export FAST_BIN="$PWD/target/debug/fast"

# Nushell
$env.FAST_BIN = (pwd | path join "target" "debug" "fast")

Shell Integration

Source the matching wrapper in the shell where the directory should change:

# Bash
source /path/to/fast/shell/fast.bash

# Zsh
source /path/to/fast/shell/fast.zsh

# Nushell
source /path/to/fast/shell/fast.nu

Run fast from that shell. The wrapper keeps the TUI attached to the terminal, then changes the parent shell's directory after q confirms the highlighted selection. Esc or Ctrl-C leaves the directory unchanged.

Usage

• Cache directory: Set FAST_CACHE_DIR to override the platform cache directory.
• Default selection: A directory without a remembered selection selects its . current-directory entry. A remembered selection is restored when available and falls back to . if the entry is gone.
• Parent: Press Backspace/Left or h to go to the parent directory (..).
• Current: The . entry represents the current directory. Select it with q to finish in the current directory; opening it is a no-op. Pressing q on a file also finishes in the current directory.
• Files: Press F in normal navigation mode to toggle direct child files and other non-directory entries. Press it again to return to directory-only mode.
• Move: Use Up/Down or j/k to move the selection.
• Open: Press Enter/Right or l to open the selected directory. These keys have no effect on files or other non-directory entries.
• Jump: Use Home/g for the first entry or End/G for the last entry.
• Select: Press q to select the highlighted directory; on a file, it selects the current directory instead.
• Copy path: Press y in normal navigation mode to copy the highlighted logical path through OSC 52. The terminal emulator or multiplexer must permit OSC 52 clipboard commands.
• Cancel: Press Esc to clear an active filter; press it again, or use Ctrl-C, to cancel without selecting a directory.
• Rescan: Press r to bypass the cache and scan the current directory again.
• Filter: Press / to enter filter mode. Typed text uses fuzzy matching by default.
• Toggle filter: Press Tab in filter mode to switch between fuzzy and simple matching.
• Edit filter: Type to extend the query, use Backspace to edit it, and press Enter to keep the filter and return to navigation.

License

Distributed under the MulanPSL-2.0 license. See LICENSE for details.

Why MulanPSL-2.0?

The Mulan Permissive Software License v2 (MulanPSL-2.0) may be less familiar than more widely used licenses. To provide clarity and context, the following table (cited from Choose a License) compares key aspects of MulanPSL v2 with popular licenses including Apache-2.0, BSD-3-Clause, and MIT.

License	Commercial Use	Distribution	Modification	Patent Use	Private Use	Disclose Source	License and Copyright Notice	Network Use is Distribution	Same License	State Changes	Liability	Trademark Use	Warranty
Apache-2.0	🟢	🟢	🟢	🟢	🟢		🔵			🔵	🔴	🔴	🔴
BSD-3-Clause	🟢	🟢	🟢		🟢		🔵				🔴		🔴
MIT	🟢	🟢	🟢		🟢		🔵				🔴		🔴
MulanPSL-2.0	🟢	🟢	🟢	🟢	🟢		🔵				🔴	🔴	🔴

The drafter of the MulanPSL-2.0 license addressed similar concerns in this comment:

Thank you for raising this issue. Please allow me to explain. (I'm the one responsible for drafting MulanPSL-2.0 and getting it approved by OSI.)

Actually at the beginning we just say in the license, english and chinese version have the same legal effect (because we carefully translated the two versions word by word, sentence by sentence). However, the OSI community suggested that IN CASE, in case there is a conflict between the two languages, we should indicate which language prevails.

However, I must say, there is a tiny chance (close to zero) that this circumstance will happen. On the one hand, many people (including technical experts and lawyers) did careful proofreading between english version and chinese version; on the other hand, MulanPSL-2.0 is such a loose license that really doesn't have constrains, what conflict will you expect? We worry about conflict because we worry about legal risk that may bring, but since the legal terms are so loose we hardly see a risk.