Skip to content
FrictionLab-DevPublic

About

Interactive terminal navigation for projects, folders, and files.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

Repository files navigation

Wayfinder

Navigate your terminal like a map, not a maze.

Wayfinder is a keyboard-driven file and folder navigator for macOS terminals, built by Friction Lab. It gives developers a Finder-like way to move through projects from the terminal, while keeping shell-native actions like cd, open, copy path, and reveal in Finder one keystroke away.

Wayfinder v0.1.0-rc1 · macOS · zsh · Rust TUI


Screenshots

📷 Screenshot placeholder: Wayfinder browsing a project folder.

📷 Screenshot placeholder: Action mode showing cd, open, copy path, and reveal commands.


Why Wayfinder

Terminal navigation is powerful, but it is not always fast. Moving through a deep project often means chaining ls, cd, find, pwd, open, and copy-paste operations just to get to the file or folder you already know visually.

Finder is visual, but it is disconnected from your shell. Fuzzy finders are fast, but they usually focus on opening files rather than changing your terminal context. Wayfinder sits between those workflows: it gives you a keyboard-first navigation view while still letting the shell remain the source of truth.

Use Wayfinder when you want to:

  • jump around a project without repeatedly typing paths
  • preview folder structure before deciding where to go
  • cd into a selected folder from a full-screen TUI
  • open files or folders without leaving the terminal
  • reveal an item in Finder when the visual location matters
  • copy a path without manually selecting terminal text

How Wayfinder compares

Wayfinder is not trying to replace every navigation tool. It focuses on one specific workflow: visual terminal navigation with shell-aware actions.

Tool / workflow Best at Where Wayfinder differs
cd, ls, find Universal shell navigation Wayfinder gives you an interactive view and reduces path typing.
Finder Visual browsing Wayfinder keeps you inside the terminal and can update your shell directory.
fzf-style pickers Fast fuzzy selection Wayfinder is folder-navigation first, with action mode for cd, open, copy, and reveal.
nnn / ranger-style file managers Full terminal file management Wayfinder is intentionally smaller: navigate, search, open, copy, reveal, and cd.
zoxide / autojump Jumping to frequently used directories Wayfinder helps when you want to inspect and choose, not only jump by history.

Wayfinder is intentionally not a full file manager. It does not try to move, rename, delete, or edit files. That keeps the tool focused, predictable, and safe for daily terminal navigation.

Highlights

  • Finder-like navigation inside a terminal TUI
  • Launches in the current working directory
  • Keyboard-first browsing with search-as-you-type filtering
  • Local search for the current folder and global search for common developer roots
  • Shell-integrated cd into selected folders
  • Open files and folders with default macOS behavior
  • Copy paths and reveal selected items in Finder
  • Single installer for release users; Cargo only needed for source installs
  • Focused macOS + zsh release candidate

Installation

Release zip (no Cargo required)

Download the latest release zip from the releases page, then:

unzip wayfinder-v0.1.0-rc1-macos-arm64.zip
cd wayfinder-v0.1.0-rc1-macos-arm64
./install.sh
source ~/.zshrc

Source install (requires Rust / Cargo)

git clone <repo-url>
cd wayfinder
./scripts/install.sh
source ~/.zshrc

The installer:

  • Installs or replaces ~/.local/bin/way
  • Adds ~/.local/bin to PATH in ~/.zshrc if needed
  • Installs zsh shell integration into ~/.zshrc automatically
  • Backs up ~/.zshrc before modifying it
  • Is safe to re-run when upgrading Wayfinder

After the installer finishes, run source ~/.zshrc or open a new terminal to activate the way command.

The installer is safe to re-run and will update the existing ~/.local/bin/way binary in place.

Verify the install:

type way   # should show: way is a shell function
way

Quick start

way

Wayfinder opens in the current directory. Type to search. Use arrow keys to move. Press Enter to open a file or navigate into a folder. Press Tab to open Action mode.


Keyboard shortcuts

Normal mode

Key Action
Type any character Filter the current folder
↑ / ↓ Move selection
Enter Open file · or navigate into folder
Esc Clear search · go up one level · return from global search
Tab Enter Action mode
Ctrl+C Quit (works from any mode)

All printable characters — including q — go into the search field in Normal mode. q only quits in Action mode.

Action mode

Press Tab from Normal mode to enter Action mode. Press Esc or Tab again to return.

Key Action
c cd into the selected folder (or its parent if a file is selected)
o Open the selected item with its default macOS app
p Copy the selected path to clipboard
s Reveal the selected item in Finder
f Toggle local / global search scope
r Rebuild global index (in global scope only)
q Quit
Esc / Tab Return to Normal mode

Open vs Reveal

  • o — open equivalent to open <path>. Opens the item with its default macOS handler. A file opens in its default app; a folder opens in Finder.
  • s — show in Finder equivalent to open -R <path>. Opens the containing folder in Finder with the item highlighted.

Search

Wayfinder has two search scopes that share the same input field.

Local search (default) filters the current folder as you type.

Global search searches across your developer roots. Toggle with Tab → f.

Global search

Default roots:

  • ~/Desktop
  • ~/Documents
  • ~/Downloads

Two engines are available:

Engine Notes
Wayfinder index (default) Builds on first use, caches results, skips noisy folders
Spotlight macOS system index; depends on Spotlight privacy settings

Switch engines: Option+r

Some terminals require Use Option as Meta key to be enabled for Option+r to work.

Rebuild the Wayfinder index: Tab → r (in global scope)

The Wayfinder index is conservative:

  • Does not scan your entire home directory
  • Skips .git, node_modules, target, dist, DerivedData, __pycache__, cmake-build-*
  • Does not follow symlinks
  • Cache path: ~/Library/Caches/Friction Lab/Wayfinder/global_index.json

In global search, Enter on a folder navigates into it and returns to local scope. Enter on a file opens it directly.


Shell integration

The way command is a zsh shell function installed by ./install.sh. The installer handles everything — no separate shell integration step is needed.

Why is shell integration needed for Tab → c?

A binary process cannot change the working directory of its parent shell. The way shell function wraps the Wayfinder binary, captures its result after the TUI exits, and runs cd on your behalf. The same mechanism handles Tab → o (calls open) and Tab → p (calls pbcopy).

Enter on a file and Tab → s (Finder reveal) are executed directly by Wayfinder and do not need the shell function.

The installer writes two managed blocks into ~/.zshrc:

  • A PATH block that adds ~/.local/bin to PATH
  • A shell integration block that defines the way function

Re-running the installer replaces these blocks in place and does not create duplicates.


Maintainer: release packaging

This section is for Friction Lab maintainers only.

./scripts/package-release.sh v0.1.0-rc1 macos-arm64

Produces a GitHub-release-ready zip under releases/<version>/. Generated release artifacts are ignored by Git.

If README.md has changed since the last package run, regenerate the release zip before uploading.


Release status

Wayfinder v0.1.0-rc1 is a release candidate.

  • Platform: macOS
  • Shell: zsh
  • Status: release candidate / pre-release
  • Feature expansion is paused while the tool is tested and hardened
  • Shell integration is required for Tab → c, Tab → o, and Tab → p
  • Feedback and bug reports are welcome — see below

Support and feedback

Wayfinder is in release-candidate testing. If you run into issues, have feedback, or want to request a feature:

  • GitHub Issues — bugs, installation problems, feature requests
  • Email — contact@frictionlab.dev for general feedback or private reports

When reporting a bug, please include:

  • macOS version
  • terminal app and shell version
  • Wayfinder version (from the zip filename or git tag)
  • what you ran
  • what you expected
  • what actually happened

Wayfinder is a Friction Lab project.

About

Interactive terminal navigation for projects, folders, and files.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages