zoxide — A Smarter cd Command That Learns Your Habits

What it is

zoxide is a Rust-based replacement for the cd command that ranks directories by frequency and recency (a metric called frecency). Instead of typing full paths, you type z proj and zoxide jumps to ~/code/my-project because that is where you go most often when you type 'proj'.

It targets developers and sysadmins who navigate deeply nested directory trees dozens of times per day. zoxide works with every major shell: bash, zsh, fish, PowerShell, nushell, elvish, and Xonsh.

How it saves time or tokens

Directory navigation is a constant tax in terminal workflows. A developer working on a monorepo might type cd ~/company/services/api/internal/handlers fifty times a week. With zoxide, after the first visit, z handlers gets you there instantly. The frecency algorithm prioritizes recent visits, so your navigation adapts as your work focus shifts.

For AI agent workflows, zoxide's z command reduces the length of shell scripts and instructions. Instead of hardcoding absolute paths, agents can use z with partial names.

How to use

1. Install zoxide:

# macOS
brew install zoxide

# Linux
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

# Or via Cargo
cargo install zoxide --locked

1. Add the shell hook to your config:

# For zsh (add to ~/.zshrc)
eval "$(zoxide init zsh)"

# For bash (add to ~/.bashrc)
eval "$(zoxide init bash)"

1. Use z to jump and zi for interactive fuzzy selection.

Example

# Basic usage
z tokrepo        # Jump to the most frecent dir matching 'tokrepo'
z web api        # Match dirs containing both 'web' and 'api'
z -              # Go to previous directory

# Interactive mode (requires fzf)
zi               # Opens fuzzy picker of all tracked directories

# Check what zoxide has learned
zoxide query --list
# /Users/dev/projects/tokrepo    12.5
# /Users/dev/work/web-api        8.2
# /Users/dev/dotfiles            3.1

Related on TokRepo

• CLI and Automation Tools -- More terminal productivity tools for developers
• AI Tools for Coding -- AI-powered development tools that complement CLI workflows

Common pitfalls

• zoxide needs a shell hook to track directory changes. If you forget to add eval "$(zoxide init zsh)" to your rc file, it will never learn your habits.
• The interactive mode (zi) requires fzf to be installed separately. Without fzf, zi is not available.
• zoxide stores its database in ~/.local/share/zoxide/db.zo. If you wipe this file, all learned directory rankings are lost.