Jelani John

Developer Tool · 2025

Live

cdj

Root / 02 Imagination

A live index of unfinished thoughts, working toys, small systems, animation studies, and tools built to see what would happen.

Signal 01 / 38

Signal // 01

cdj

Live

Signal_01 · Developer Tool · 2025

Premise

Could terminal navigation feel more like muscle memory than typing paths?

Testing vector

How few keystrokes a directory jump can take before it stops feeling like a command at all — and whether a deterministic, positional mapping beats fuzzy frecency jumpers for a tree you already know.

Project metadata

Object_type
Utilities
Tech_stack
Bash, npm, CLI
Status
Live

Signal index [38_items]

Developer Tool · 2025

cdj

Live

Premise

Navigating between many project directories is a constant, tiny tax: cd ~/Projects/whatsnext/lib/screens is long to type and easy to fumble. Fuzzy jump tools (z, autojump, zoxide) solve this with frecency databases and fuzzy matching — powerful, but unpredictable: the same input can land somewhere different depending on history. cdj takes the opposite stance: deterministic, positional, letter-by-letter navigation over a known base directory. p always means the first directory starting with p, sorted case-insensitively; p2 always means the second. No database, no history, no surprises — the mapping is stable as long as the directory tree is.

Each character of the pattern descends one directory level by first-letter match, with numeric disambiguation between siblings — cdj wsc jumps three levels deep, w3d picks the third w* directory and then its first d* child. Dead ends fail soft: the jump lands in the deepest directory the pattern could reach.

The subshell problem

A child process can't change its parent shell's directory, so the binary never cds — it prints the resolved path to stdout, and a small shell function wraps it to perform the actual cd. An npm postinstall script writes that hook into .zshrc/.bashrc between marker comments so upgrades can replace it in place, and preuninstall removes it cleanly. A second command walks the tree and emits a full set of memorable cd aliases (cdjw for whatsnext, cdjwl for whatsnext/lib) to a configurable depth.

npm install -g cdj
cdj p2      # second directory starting with 'p'
cdj wsc     # w*/s*/c*, three levels deep
cdj -g      # generate a tree of cd aliases

The whole thing is two pure-bash executables with zero runtime dependencies — Node.js only touches the install/uninstall lifecycle hooks. Published to npm as cdj and in daily use at v1.0.8.

What I was testing
How few keystrokes a directory jump can take before it stops feeling like a command at all — and whether a deterministic, positional mapping beats fuzzy frecency jumpers for a tree you already know.
What I learned
Tools you use two hundred times a day earn their polish; everything else is decoration. Determinism beat cleverness — the same keystrokes landing in the same place every time is what turns a command into muscle memory.
Status
Live
Bench object
Utilities
Stack
  • Bash
  • npm
  • CLI
Links