gd

go dir — a modern cd.

gd >= cd

English | 繁體中文

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

---

Why gd?

	cd	gd
Local dirs	cd src	gd src
Go home	cd	gd
Previous dir	cd -	gd -
Full path	cd /tmp	gd /tmp
Fuzzy search	-	gd conf
History ranking	-	gd proj (remembers your picks)
Shortcuts	-	gd link k ~/code/kernel
Boost dirs	-	gd boost ~/work

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

Use cases

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

Quick start

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

Manual install

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)

Usage

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.

Ranking

Priority	Source	Description
1	Link	gd link editor ~/code/editor — permanent shortcut
2	Selected	Dirs you've picked via gd, always above unselected
3	Visited	Dirs you've cd'd into, ranked by recency
4	Index	Filesystem scan by background daemon

Selected once > never selected, regardless of match quality.

Commands

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)

Comfort by design

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.
• 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, never polling.
• One safe store — daemon and CLI share a single SQLite database in WAL mode: concurrent, consistent, corruption-free.

Architecture

                    +-----------+
  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.

Service	~/.config/systemd/user/gd-daemon.service
Capability	CAP_SYS_ADMIN + CAP_DAC_READ_SEARCH
RAM	~15 MB
Query latency	< 25 ms

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

Shell support

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

License

MIT