gd

go dir — a modern cd.

gd >= cd

English | 繁體中文

Type a name, land in the right directory. No full paths, no mental overhead.

Everything cd does, plus smart search when you need it.

Mobile SSH + AI coding

You're on a phone, SSH'd into a VPS. Typing /home/deploy/projects/myapp-backend/src on a touch keyboard is miserable. With gd:

gd myapp        # jump — you remember the name, not the path
claude           # launch Claude Code and start coding

You have a vague memory of the name? Good enough. gd finds it. You used it before? It's already at the top.

Deep project trees

Monorepo with 200 packages, microservices spread across /opt, /srv, /home. You don't maintain a mental map — gd does it for you:

gd auth-service  # don't care where it lives
gd payments      # picked it last week? still ranked first

Ditch the file manager

You're on your local machine, no SSH. You open a terminal — and never leave it. Instead of clicking through Nautilus/Dolphin/Thunar to find that folder, just type the name:

gd Downloads    # no more ~/Downloads in the address bar
gd wallpapers   # buried in ~/Pictures/2024/wallpapers? don't care
gd taxes        # ~/Documents/finance/2025/taxes — gd knows

Move, copy, preview — all from the terminal:

gd projects     # jump to your project folder
ls              # see what's there
gd taxes        # jump to taxes, grab a file
cp report.pdf ~/Desktop/
gd projects     # back in one command

Once you alias cd=gd, your terminal becomes the file manager. Every directory you visit is remembered and ranked — the more you use it, the fewer keystrokes you need.

Server admin

Jumping between /etc/nginx, /var/log/app, /opt/services/monitoring:

gd link ng /etc/nginx
gd link logs /var/log/app
gd ng           # instant

curl -sSL https://raw.githubusercontent.com/123hi123/gd/main/install.sh | bash

git clone https://github.com/123hi123/gd.git && cd gd
cargo install --path crates/gd-cli
cargo install --path crates/gd-daemon
gd setup

gd setup handles everything:

• Install the systemd daemon service
• Set CAP_SYS_ADMIN on the daemon binary
• Add the shell hook to your rc file
• Ask if you want alias cd=gd (recommended)

gd                  # go home
gd src              # local ./src/ exists? jump instantly
gd config           # no local match? fuzzy-search, pick from TUI
gd proj             # picked before? ranked first — always
gd /tmp             # full path? jump directly
gd ../lib           # relative path? jump directly
gd -                # previous directory

The rule: argument contains / = path mode (jump or fail). No / = search mode.

Selected once > never selected, regardless of match quality.

gd <query>              search and jump
gd link <alias> <path>  create shortcut
gd unlink <alias>       remove shortcut
gd boost [path]         boost ranking (default: cwd, 5x)
gd unboost <path>       remove boost
gd list                 show links, boosts, stats
gd clean                remove dead entries
gd export               dump database as JSON
gd doctor               check installation health
gd setup                install daemon + hook + cd alias
gd update               rebuild and restart (developers)

Everything we do behind the scenes so the foreground feels effortless — one by one.

Matching bends to your memory

• Three-layer matching — exact match first, then fuzzy subsequence (gd cbz rdr finds cbz-reader), then edit-distance typo tolerance (gd raeder cbz still lands). Abbreviate it, misremember it, fat-finger it — you still arrive.
• Forgiving multi-keyword search — keywords match in any order, and a half-remembered query like gd open cbz still surfaces candidates from your history instead of a dead-end "no matches".
• Names, not paths — you only ever type a basename. Every parent directory is indexed in its own right, so any folder anywhere is reachable by the name you actually remember — no hierarchy to recall.

Ranking that learns you

• Frecency — frequency × recency with time decay. The dirs you live in rise to the top on their own; the ones you've abandoned quietly sink.
• Your picks always win — a directory you've selected once outranks any never-selected index match, regardless of match quality.
• Pin what matters — gd link for permanent shortcuts, gd boost to weight a whole subtree the way you think about it.

Never the wrong guess

• You choose, gd suggests — when several directories match, an interactive TUI picker lets you pick the right one; gd never silently jumps somewhere wrong.
• Best match where your eyes rest — the picker opens inline right where you typed, with the top result on the very line your cursor is on and the rest flowing downward, so your gaze never has to move. Prefer a full-screen list? gd config layout traditional (or centered).
• No dead ends — paths that no longer exist are filtered out at query time, so you're never offered a folder that's already gone.
• cd, only better — local ./src, absolute /paths, ../relative, gd -, and bare gd for home all still work. Alias cd=gd and lose nothing.

Invisible, lightweight infrastructure

• Always-fresh index — a fanotify watcher tracks creates, deletes, and moves in real time. No periodic find scans, no stale results.
• Stays out of your way — ~15 MB RAM, ~7 s of CPU per hour of uptime, < 25 ms queries. Event-driven wherever the kernel allows it.
• One safe store — daemon and CLI share a single SQLite database in WAL mode: concurrent, consistent, corruption-free.

                    +-----------+
  gd <query> ----→ | gd (CLI)  | ----→ print path → shell cd
                    +-----------+
                         |
                    +-----------+
                    | gd-daemon | ← fanotify filesystem watcher
                    +-----------+
                         |
                    ~/.local/share/gd/
                    └── gd.db   (SQLite — index + history + links + boosts)

gd-daemon uses Linux fanotify to watch the filesystem in real-time. Directory creates, deletes, and moves are tracked incrementally — no periodic find scans. Both daemon and CLI share one SQLite database with WAL mode for safe concurrent access.

Self-healing. If the kernel event queue ever overflows (a huge npm install or rm -rf burst), the daemon notices the FAN_Q_OVERFLOW marker and runs one catchup scan after the burst settles — no periodic rescans needed. Paths that stop existing retire from the index lazily, the first time a search touches them (gd clean does a full sweep on demand).

Fallback mode. On filesystems where fanotify FID marks are unavailable — most commonly a btrfs home split into subvolumes (the kernel rejects the mark with EXDEV) — the daemon degrades to a catchup rescan every 30 minutes at idle CPU/IO priority, so it never competes with foreground work; there is no periodic full rescan, since dead paths already retire lazily at query time. It keeps retrying fanotify every 30 minutes and switches back seamlessly if it succeeds. gd setup reports the active watch mode right after install, gd doctor shows it any time, and gd config daemon.fallback off disables background scanning entirely (the index then grows only from the directories you actually visit).

1 hour uptime, 7 seconds CPU — event-driven, not polling.

zsh, bash, fish, nushell, powershell — auto-detected by gd setup.

MIT