hmemcpy / hmemcpy/toolkata

Tutorial: zoxide for cd users (zoxide-cd pairing)

Open
#7 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Summary

Add a new tutorial pairing: **Learn zoxide if you know cd**.

## Motivation

zoxide is a smarter cd command that learns your habits. It replaces `cd` with an intelligent navigation system that uses ML-based ranking (frecency) to guess where you want to go. Low barrier to entry, immediate productivity gain.

**Why this works:**
- Universal utility (everyone uses cd)
- Immediate productivity boost
- Zero learning curve for basic usage
- Powerful features when needed (interactive selection, fzf integration)

## Proposed Structure (~6 steps, ~20 min)

| Step | Concept | cd → zoxide |
|------|---------|-------------|
| 1 | Install zoxide | `brew install zoxide` |
| 2 | Initialize shell | Add to `.zshrc` / `.bashrc` |
| 3 | Basic navigation | `z foo` instead of `cd ~/long/path/to/foo` |
| 4 | Frecency algorithm | How zoxide learns (frequency + recency) |
| 5 | Interactive selection | `zi` for fzf-based directory selection |
| 6 | Advanced: multiple matches | `z foo bar` matches path segments |

## Key Comparison Points

| cd workflow | zoxide equivalent | Benefit |
|-------------|-------------------|---------|
| `cd ~/projects/work/frontend/src/components` | `z front` or `z w front` | Type partial match, go anywhere |
| `cd ../../..` then `cd ~/other/project` | `z other` | Direct jump, no counting dots |
| Tab completion hunting | `zi` | Fuzzy interactive selection |
| Aliasing directories | Automatic, learns from usage | No manual alias management |
| `cd -` (previous dir) | Same, works with zoxide history | Familiar, enhanced |

## Pedagogical Notes

**The "aha" moment:** Typing `z tool` and landing in `~/projects/work/toolkata/packages/web` without thinking about the path.

**Key insight:** zoxide removes the cognitive load of "where am I and how do I get there?" You think in terms of project names, not directory trees.

**Migration path:** zoxide can coexist with cd. Start with `z`, fall back to `cd` when needed. Eventually `z` becomes muscle memory.

## Shell Integration

```bash
# In .zshrc / .bashrc
eval "$(zoxide init zsh)" # or bash

# Optional: replace cd entirely
# eval "$(zoxide init zsh --cmd cd)"
```

## Resources

- https://github.com/ajeetdsouza/zoxide
- https://github.com/junegunn/fzf (for `zi` integration)

## Category

`Shell & Navigation`

## Notability

- Universal utility (everyone navigates directories)
- Zero-config productivity tool
- Perfect "gateway drug" to modern CLI tools

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.