zz

A terminal session manager with fuzzy finding and smart ranking.

Pick a workspace, get a dedicated multiplexer session — that's it.

Features

• Auto-named sessions — each workspace directory becomes an isolated session. you don't need to think of the name.
• Auto-created sessions — no need to manually create or attach: zz personal over cd ~/repos/my-personal-project && zellij -s my-personal-project and zellij attach my-personal-project
• Frecency ranking — powered by zoxide: the repo you've been in most recently rises to the top
• Fuzzy navigation — zz to interactively select, or zz <query> to jump directly
• Path queries — zz . or zz ./path opens any directory as a session, not just managed repos

Before	After
git clone git@github.com:aster-void/my-personal-project ~/repos/my-personal-project	zz get git@github.com:aster-void/my-personal-project
cd ~/repos/my-personal-project && zellij -s my-personal-project	zz personal
zellij attach my-personal-project	zz personal

Dependencies

Tool	Required by	Notes
zellij	both variants	the multiplexer
fzf	both variants	interactive selection
zoxide	both variants	frecency ranking; falls back gracefully if not seeded
ghq	ghq variant only	repo discovery and cloning

Install

Copy a reference implementation and edit the CONFIG block at the top.

Selector variant — uses a shell glob for repo discovery; covers flat, multi-workspace, and nested layouts:

curl -fLo ~/.local/bin/zz https://raw.githubusercontent.com/aster-void/zz/main/zz-selector.sh
chmod +x ~/.local/bin/zz
${EDITOR:-vi} ~/.local/bin/zz   # set SELECTOR and GET_DEST in the CONFIG block

ghq variant — uses ghq for discovery and cloning:

curl -fLo ~/.local/bin/zz https://raw.githubusercontent.com/aster-void/zz/main/zz-ghq.sh
chmod +x ~/.local/bin/zz
# Configure ghq root if needed: git config --global ghq.root ~/repos

If something breaks or you want to customize behavior (different multiplexer, different layout, etc.), hand the file to a coding agent. If it's our bug, please open an issue.

Usage

zz                    # fuzzy select and attach
zz <query>            # attach to best frecency match
zz .                  # attach to current directory (any dir, not just managed repos)
zz ./path             # attach to a path relative to cwd
zz get <url>          # clone repo into workspace
zz ls                 # list sessions
zz ls -a              # list all repos (with session status)
zz -s                 # select from existing sessions only
zz delete <query>     # delete a session
zz delete --all       # delete all sessions
zz --help             # show help

Query matching

Given a keyword query, zz resolves the target in order:

1. Path query (starts with . or /) — resolves to that directory directly; any existing directory works, not just managed repos
2. Frecency match — zoxide picks the best match among managed repos based on recent visits
3. Substring fallback — all keywords must appear in the full path; first match wins (for repos not yet in the zoxide database)