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
📷 Screenshot placeholder: Wayfinder browsing a project folder.
📷 Screenshot placeholder: Action mode showing cd, open, copy path, and reveal commands.
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
cdinto 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
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.
- 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
cdinto 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
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 ~/.zshrcgit clone <repo-url>
cd wayfinder
./scripts/install.sh
source ~/.zshrcThe installer:
- Installs or replaces
~/.local/bin/way - Adds
~/.local/bintoPATHin~/.zshrcif needed - Installs zsh shell integration into
~/.zshrcautomatically - Backs up
~/.zshrcbefore 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
waywayWayfinder 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.
| 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.qonly quits in 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 |
o— open equivalent toopen <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 toopen -R <path>. Opens the containing folder in Finder with the item highlighted.
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.
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+rto 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.
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/bintoPATH - A shell integration block that defines the
wayfunction
Re-running the installer replaces these blocks in place and does not create duplicates.
This section is for Friction Lab maintainers only.
./scripts/package-release.sh v0.1.0-rc1 macos-arm64Produces 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.
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, andTab→p - Feedback and bug reports are welcome — see below
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.