🦘 djump

Jump to nearby directories with a single keystroke.

A fast, minimal TUI tool written in Rust that shows a tree of directories around your current location and lets you jump to any of them instantly.

✨ Features

• 🌳 Tree view — directories displayed as an actual hierarchy so you always know where you are
• ⌨️ Single-keystroke jump — keys assigned starting with vim home row (h j k l a s d f g ...)
• 🧠 Frecency ranking — directories you jump to often get the most accessible keys
• 🔍 Filter mode — press / to fuzzy-filter the tree, with highlighted matches
• 📐 Dynamic levelling — intelligently decides how many levels up/down to show (capped at 25 entries), prioritizing the most relevant directions
• 🌍 Keyboard layout aware — auto-detects QWERTY/AZERTY from your system, or set DJUMP_LAYOUT to override
• ⚡ Fast — built in Rust with release-mode LTO, launches instantly

📦 Installation

git clone https://github.com/yourusername/djump.git
cd djump
cargo build --release

The binary will be at target/release/djump.

🔧 Setup

Add the shell wrapper to your ~/.bashrc or ~/.zshrc:

j() {
    local dir
    dir="$(djump)"
    if [ -n "$dir" ] && [ "$dir" != "$(pwd)" ]; then
        cd "$dir" || return
    fi
}

Make sure the djump binary is in your $PATH, or use the full path in the wrapper.

🚀 Usage

Key	Action
h j k l ...	Jump to the labelled directory
/	Enter filter mode (fuzzy search)
Enter	Jump to first match (filter mode)
Backspace	Edit filter / return to normal
Esc or q	Cancel and stay in current directory

🔍 Filter mode

Press / to start typing. The tree filters down to matching entries using fuzzy matching, with matched characters highlighted in yellow. Press Enter to jump to the first visible result, or Esc to go back to normal mode.

🧠 Frecency

Every jump is recorded in ~/.local/share/djump/history.json. Directories you visit frequently and recently get higher scores, and the most accessible keys are assigned to them first. Frecent directories are highlighted in cyan.

🌍 Keyboard layout

djump auto-detects your keyboard layout at startup by reading /etc/default/keyboard or /etc/vconsole.conf. AZERTY layouts (Belgian, French) get home-row-optimized key assignments that match the physical key positions.

To override detection, set the DJUMP_LAYOUT environment variable:

export DJUMP_LAYOUT=azerty  # or: qwerty

🏗️ How it works

1. Scans directories around your CWD (up to 2 levels up, 2 levels down)
2. Dynamically adjusts depth based on how many entries each level adds — if going 2 levels up would flood the view, it stops at 1 (or 0)
3. Builds a tree and renders it as a centered TUI popup
4. Waits for a single keypress, prints the selected path to stdout
5. The shell wrapper cds to it

🛠️ Dependencies

• ratatui — TUI framework
• crossterm — terminal handling
• serde — frecency history serialization

👤 Credits

Conceived by Tom Deneire, entirely written by Claude (Anthropic).

📄 License

MIT