zoxide - 디렉토리 경로를 잊어도 되는 터미널

zoxide란

cd는 디렉토리를 이동하는 가장 기본적인 명령어입니다. 문제는 경로를 정확히 알아야 한다는 것입니다. 깊이 중첩된 프로젝트 디렉토리로 이동하려면 매번 전체 경로를 타이핑하거나, 탭 완성을 연타해야 합니다.

zoxide: A smarter cd command. Supports all major shells.

A smarter cd command, inspired by z and autojump. Remembers which directories you use most frequently.

github.com

zoxide는 이 문제를 해결하는 스마트 디렉토리 점프 도구입니다. 사용자의 디렉토리 이동 패턴을 학습해서, 경로의 일부만 입력해도 원하는 곳으로 바로 이동시켜 줍니다.

핵심 명령어는 두 가지입니다:

z - 자동 점프

# 기존 cd 방식
cd ~/projects/my-blog
 
# zoxide 방식 - 키워드만으로 점프
z techblog

z는 입력한 키워드와 가장 잘 매칭되는 디렉토리로 즉시 이동합니다. 과거에 자주, 최근에 방문한 디렉토리일수록 우선순위가 높습니다.

zi - 인터랙티브 선택

zi blog

zi는 키워드에 매칭되는 디렉토리 후보를 fzf 기반 인터랙티브 리스트로 보여줍니다. 비슷한 이름의 디렉토리가 여러 개일 때 유용합니다.

사용 소감

터미널 인생이 달라졌다는 말이 과장이 아닙니다.

설치 직후에는 z로 이동이 안 되는 디렉토리가 있어서 결국 cd를 쓰게 됩니다. zoxide의 DB에 아직 데이터가 쌓이지 않았기 때문입니다. 하지만 며칠만 쓰면 자주 가는 디렉토리는 전부 학습되고, 그때부터 cd를 입력할 일이 급격히 줄어듭니다.

문제는 여기서 발생합니다. 너무 편해진 나머지, 디렉토리가 어디에 있는지 자체를 잊어버리기 시작합니다. 예를 들어 프로젝트 디렉토리가 ~/projects/에 있는지 ~/work/에 있는지 기억이 안 납니다. 그냥 z techblog 하면 되니까 경로를 외울 이유가 없어진 것입니다.

DB에 데이터가 쌓일수록 이 현상은 심해집니다. z에 키워드 하나 던지면 알아서 도착하니, 전체 경로를 의식적으로 인지할 기회가 사라집니다. 편의성과 기억력의 트레이드오프라고 할 수 있습니다 - 불편하진 않은데, 가끔 당황스럽긴 합니다.

zoxide의 원리

Frecency 알고리즘

zoxide의 핵심은 frecency(frequency + recency) 알고리즘입니다. 단순히 방문 횟수만 세는 것이 아니라, 얼마나 자주 + 얼마나 최근에 방문했는지를 종합하여 각 디렉토리에 점수를 매깁니다.

$ zoxide query -l -s
  60.0 /home/user/projects/my-blog
  50.0 /home/user/dotfiles
  20.0 /home/user/projects/blog-framework
  18.0 /home/user/projects/side-project
  16.5 /home/user/work/app-server
  12.0 /home/user/projects
   ...

-l은 목록 조회, -s는 점수 표시 옵션입니다. 점수가 높을수록 z 명령 시 우선적으로 매칭됩니다. 오래 방문하지 않은 디렉토리는 시간이 지나면서 점수가 자연스럽게 감소합니다.

자체 바이너리 DB

zoxide는 데이터를 어딘가에 저장해야 합니다. 플랫폼별 기본 경로는 다음과 같습니다:

플랫폼	경로
macOS	~/Library/Application Support/zoxide/db.zo
Linux	~/.local/share/zoxide/db.zo
Windows	%LOCALAPPDATA%\zoxide\db.zo

SQLite를 쓴다는 이야기가 있지만, 실제로는 아닙니다. db.zo 파일은 Rust의 bincode 시리얼라이제이션 포맷으로 저장된 자체 바이너리 DB입니다.

$ file ~/Library/Application\ Support/zoxide/db.zo
db.zo: Matlab v4 mat-file (little endian), rows 37, columns 0, imaginary

file 명령이 MATLAB 파일로 인식하는데, 이는 바이너리 시그니처가 우연히 겹치기 때문입니다. 실제 구조는 각 디렉토리 엔트리가 경로(String), 랭크(f64), 마지막 접근 시간(u64 epoch seconds)으로 구성된 직렬화 데이터입니다.

SQLite 같은 범용 DB 엔진 대신 자체 포맷을 사용하는 이유는 단순합니다 - zoxide가 저장하는 데이터는 단순한 리스트 구조이고, cd 명령만큼 빨라야 하기 때문입니다. 파일을 통째로 읽고 쓰는 것이 DB 쿼리보다 훨씬 가볍습니다.

AI Agent에게 zoxide 먹이기

zoxide의 편의성에는 한 가지 부작용이 있었습니다. 앞서 말한 것처럼 디렉토리 경로를 잊어버리기 시작하는데, 이게 AI agent와 작업할 때 문제가 됩니다.

AI agent에게 현재 작업 디렉토리 외부의 경로를 전달해야 할 때, 정확한 경로를 모르면 말해줄 수가 없습니다. z blog이면 되는 걸 agent한테는 /home/user/projects/blog-framework라고 알려줘야 하는데, 그 경로가 기억이 안 나는 것입니다.

z Skill - zi를 모킹하다

이 문제를 해결하기 위해 Claude Code에 z Skill을 만들었습니다. 원리는 간단합니다 - zoxide query 명령을 agent가 직접 실행하게 해서, 터미널의 zi와 동일한 경험을 제공하는 것입니다.

Skill의 전체 코드는 이것이 전부입니다:

~/.claude/skills/z/SKILL.md

---
name: z
description: Resolve zoxide directory shorthand to full path
argument-hint: [query]
allowed-tools: Bash
---
 
Run `zoxide query -l -s $ARGUMENTS` to list all matching directories with scores.
 
- If there's only one result, that's the answer. Remember it for the rest of this conversation.
- If there are multiple results, show them all and ask the user which one they meant.
- If no match, let the user know.

사용 흐름은 이렇습니다:

1. 사용자가 /z blog을 입력
2. Agent가 zoxide query -l -s blog을 실행
3. 매칭 결과가 하나면 바로 경로를 기억, 여러 개면 사용자에게 선택지를 제시
4. 이후 대화에서 해당 경로를 자연스럽게 활용

zi의 인터랙티브 선택 과정을 agent와의 대화로 치환한 셈입니다. z 명령과 -l(목록), -s(점수) 쿼리 옵션만으로 fzf 없이도 동일한 기능을 구현할 수 있었습니다.

덕분에 “그 블로그 레포에서 뭐 좀 확인해줘”라고 말할 때, 정확한 경로를 몰라도 /z blog 한 번이면 agent가 알아서 경로를 파악합니다. zoxide의 DB가 사용자와 agent 사이의 공유 지식 역할을 하는 것입니다.