autojump — Shell Directory Navigation That Learns Your Habits

Introduction

autojump is a faster way to navigate your filesystem from the command line. It works by maintaining a weighted database of directories you visit through cd, then allowing you to jump to the best match using just a few characters of the directory name.

What autojump Does

• Tracks directory visit frequency in a local database updated on every cd command
• Provides the j command for jumping to the highest-weighted matching directory
• Supports partial name matching and multiple arguments for disambiguation
• Opens directories in your file manager with the jo command
• Works with bash, zsh, and fish shells

Architecture Overview

autojump is written in Python and hooks into your shell via a function that wraps cd. Each time you change directories, the wrapper increments the weight for that path in a local text-based database stored in ~/.local/share/autojump/. When you invoke j, the tool scans the database for the best match by weight and recency, then changes to that directory.

Self-Hosting & Configuration

• Install via package managers (Homebrew, apt, pacman) or from source
• Source the autojump shell script in your shell's rc file to enable the cd hook
• The database file is plain text and can be manually edited or backed up
• Configure ignored directories by adding paths to ~/.config/autojump/
• Works without root privileges; all data lives in the user's home directory

Key Features

• Zero-configuration learning: starts working immediately after installation
• Handles partial directory names and fuzzy matches
• Supports tab completion for multiple match candidates
• Lightweight with minimal shell startup overhead
• Cross-platform: runs on Linux, macOS, and Windows (via Cygwin or WSL)

Comparison with Similar Tools

• zoxide — Rust rewrite inspired by autojump; faster startup and more active development
• fasd — tracks files and directories but is no longer actively maintained
• z (rupa/z) — similar concept in pure shell script; lighter but fewer features
• fzf — general fuzzy finder that can be combined with cd for directory jumping but requires more setup
• broot — interactive directory navigator with tree view; different workflow paradigm

FAQ

Q: Does autojump slow down my shell startup? A: The overhead is minimal. Sourcing the script adds a few milliseconds to shell initialization.

Q: What happens if I rename or delete a directory? A: autojump will try to match the old path and fail silently. You can purge stale entries with j --purge.

Q: Can I use it alongside zoxide? A: They serve the same purpose and would conflict on the j alias. Pick one or configure different aliases.

Q: Does it work in fish shell? A: Yes. autojump includes a fish plugin that integrates with the fish completion system.

Sources

• https://github.com/wting/autojump
• https://github.com/wting/autojump/wiki