Zoxide Has Forever Improved the Way I Navigate in the Terminal

For the longest time, I've used cd exclusively for navigating in the terminal. However, when it comes to nested directories, the only way to speed this up was to either use aliases or my shell history.

Since discovering zoxide, that's all changed...

Introduction

cd (change directory) is undoubtedly one of my most used commands. Having used it for as long as I've been working in the terminal, I've never felt like anything was missing or anything more was needed. So when I came across zoxide, which describes itself as "the smarter cd command," I was intrigued. What more could I possibly need?

Well, as it turns out, quite a lot. After using it for about a week in my system, I can confidently say that it's improved the way I work in the terminal for the better. The command allows me to navigate around my projects and directories at a much greater speed and does so whilst saving me brain cycles in the process. All of this translates to saving me time, keeping me focused, and making me more productive.

Let me show you how it works.

Installation and Setup

Installing Zoxide

The first thing you'll need to do is install zoxide onto your system. This takes a couple of steps:

1. Download and install the zoxide binary onto your operating system. You can do this with either cargo or your operating system's package manager. As I'm using Arch (by the way), I'll install it using pacman:

sudo pacman -S zoxide

1. Set it up on your shell. The documentation lists instructions for all of the major shells such as bash, zsh, fish, and even POSIX. In my case, I'm using zsh, so all I need to do is add the following line to the end of my .zshrc:

echo 'eval "$(zoxide init zsh)"' >> ~/.zshrc

Now if I open up a new terminal, I have the z command available to me.

Getting Started: Training Zoxide

So what can it do? Well, nothing special yet. In order to unlock zoxide's true potential, we need to first train it by navigating around our file system like we would do normally, but using the z command instead.

Basic Usage

To do so is pretty much the same as using cd:

• Change into another directory: Use the z command and pass in the directory's path (relative or absolute)
• Return to home directory: Just use the z command by itself
• Return to previous directory: Pass in a dash (z -) instead of a path

So far, all of this is pretty much in parity with the way that cd works. As I said, none of this is special. However, after you've used zoxide for a little bit, that's when things start to become interesting.

The Magic: Smart Navigation

Let's say I want to make some changes to my Neovim config. In order to do so, I need to navigate to the directory that contains my Neovim configuration files. This is all the way in my ~/.config/nvim/lua/custom directory, which is nested pretty deep.

In order to get there with cd, I have to use the full path every time, which can be rather tedious. The only way to speed this up is by using either my shell history or defining a custom alias for any directories that I use frequently.

With zoxide, however, if I want to get there quickly, all I have to do is type:

z nvim custom

And it takes me straight there. Yeah, that's pretty awesome!

How Zoxide Works: The Algorithm

As I've been navigating around, zoxide has been working in the background, adding weights to my most frequently visited paths. This means that if I want to jump into a directory that I've already visited with zoxide, I can do so using path fragments rather than specifying the entire thing. Zoxide will then use its internal matching algorithm to determine which path to use.

The Four Matching Rules

This algorithm has four main properties:

1. Case insensitive: The search term is case insensitive, meaning you can write your terms in lowercase and they'll still match to any mixed or uppercase path components.

2. Order matters: All of the terms that you provide must be contained within the path in the same order. For example, whilst "nvim lua" matches, "lua nvim" will not, because there is no path entry that contains those terms in that order.

3. Last component matching: The last component of the last keyword must match the last component of the path. For example, "dreams recorder" will match a path ending in "recorder", but "dreams tools" won't match if no path entries end with "tools".

4. Weight-based ordering: All matches are returned in descending order of their weights. This means that any conflicts are resolved with the path containing the highest weight being chosen.

The Frecency Algorithm

This weight value is known as the "frecency" (an amalgamation of frequency and recency), and these two properties define the value of the weight or score:

Frequency: The number of times that the directory has been visited. Each time it is visited, its rank goes up by one point.

Recency: How long ago the directory was last visited. Each score has a modifier based on the amount of time since it was last accessed:

• Within 1 hour: score multiplied by 4
• Within the last day: score multiplied by 2
• Within the last week: score divided by 2
• Otherwise: score divided by 4

All of this makes zoxide incredibly dynamic, especially compared to alternatives such as creating aliases, which are typically static and require you to create and manage them manually.

Enhanced Navigation with Interactive Mode

In addition to the speed benefits, because zoxide removes the need for me to type uppercase characters and symbols, my fingers never travel far from the home row, which increases my typing speed for navigation. And because I no longer need to remember the full path, it's much easier on my brain to remember where I need to go.

Even with this, I can still sometimes forget. When that happens, I find that looking at a list helps to give my brain a friendly nudge. Fortunately, that's where another feature of zoxide comes in handy.

Setting Up Interactive Mode

In order to enable this feature, we need to install another package on our system: fzf. fzf is a fuzzy finder tool for the terminal.

sudo pacman -S fzf

By itself, fzf lists all of the files in a directory and allows you to search for them in a fuzzy way. But when combined with zoxide, it becomes incredible.

Using Interactive Commands

The zi command: If I type zi (zoxide interactive), I'm shown an fzf window containing a list of all the directories I've visited using zoxide in descending order of their score. I can scroll through this list using Ctrl+P and Ctrl+N, or I can search for a directory with fuzzy finding by typing out the name.

Interactive prefix search: You can also bring up an interactive menu whilst you're typing out your terms. Start typing out the prefix of the directory you wish to change to, then press the space key followed by the Tab key. This brings up another fuzzy finder window that shows only a subset of entries that match the given prefix.

Both of these features are really useful for those times you need a visual clue to give you a nudge in the right direction.

Database Management

As you can imagine, the list of entries in the zoxide database can start to grow rather large. Fortunately, zoxide does age these off once the total score gets above 10,000 by default. This triggers a rebalancing event, causing all of the scores in the database to be recalculated. Afterwards, any scores that fall below a certain threshold are removed from the database.

CRUD Operations

Zoxide also provides a number of commands to perform CRUD operations on the entries:

• zoxide add: Add a directory or increment its rank without having to travel to it
• zoxide query: Search for a directory in the database
  • Use the -s flag to display scores
  • Use -l to list all entries
• zoxide remove: Delete directories from the database (handy if zoxide resolves to unwanted paths)
• zoxide edit: Brings up an interactive window to modify entries in the database

Through the edit menu, you can increment or decrement the rank of an entry or remove an entry entirely using the keys listed at the top of the menu.

The Perfect Setup: Aliasing CD

At this point, I'm pretty convinced zoxide definitely improves my workflow. However, there's a catch. As I mentioned at the start, cd is one of my most used commands. Therefore, undoing that muscle memory is going to be very difficult. Not only that, but if I have to change to using the z command for navigation, anytime I move or SSH onto another machine that doesn't have zoxide installed, I'll need to adjust my muscle memory again. This results in the zoxide command becoming a crutch.

The Solution: Rebinding CD

To prevent this from happening, I can rebind the cd command to use zoxide instead. The easiest way to do this is to use a shell alias, however I prefer to take a different approach.

The zoxide init command allows us to pass in an option called --cmd which changes the prefix of both the z and zi commands. We can add this to the init command inside of our shell RC file:

eval "$(zoxide init zsh --cmd cd)"

Once that's added, save and close the file and open up a new terminal to test it out.

Now I no longer have the z command available. However, if I run which on the cd command, you can see that it's aliased to the zoxide command instead. Now I can use cd as I would normally whilst also taking advantage of the features of zoxide. Additionally, by aliasing this way, we also now have access to interactive mode using cdi.

Note: This doesn't work for nushell or any POSIX-compliant shells. However, for zsh, bash, and fish, this works absolutely fine.

Conclusion

For me, I'm pretty happy with this setup. Because I live in the terminal so much, using zoxide for my cd command has improved my workflow considerably. So much so that I don't think I could ever go back to just the vanilla cd command.

The combination of intelligent path matching, frecency-based scoring, and seamless integration with existing workflows makes zoxide an indispensable tool for anyone who spends significant time navigating directories in the terminal. It's not just about speed—it's about reducing cognitive load and keeping you in the flow state while working.

Resources

• Zoxide GitHub Repository
• Wallpaper used in video

Are you planning on giving zoxide a go, or perhaps you were using it already? The smart navigation and muscle memory preservation make it a game-changer for terminal productivity.