zoxide란
cd는 디렉토리를 이동하는 가장 기본적인 명령어다. 문제는 경로를 정확히 알아야 한다는 것이다. 깊이 중첩된 프로젝트 디렉토리로 이동하려면 매번 전체 경로를 타이핑하거나, 탭 완성을 연타해야 한다.
zoxide는 이 문제를 해결하는 스마트 디렉토리 점프 도구다. 사용자의 디렉토리 이동 패턴을 학습해서, 경로의 일부만 입력해도 원하는 곳으로 바로 이동시켜 준다.
핵심 명령어는 두 가지다:
z - 자동 점프
# 기존 cd 방식
cd ~/projects/my-blog
# zoxide 방식 - 키워드만으로 점프
z techblogz는 입력한 키워드와 가장 잘 매칭되는 디렉토리로 즉시 이동한다. 과거에 자주, 최근에 방문한 디렉토리일수록 우선순위가 높다.
zi - 인터랙티브 선택
zi blogzi는 키워드에 매칭되는 디렉토리 후보를 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, imaginaryfile 명령이 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의 전체 코드는 이것이 전부다:
---
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.사용 흐름은 이렇다:
- 사용자가
/z blog을 입력 - Agent가
zoxide query -l -s blog을 실행 - 매칭 결과가 하나면 바로 경로를 기억, 여러 개면 사용자에게 선택지를 제시
- 이후 대화에서 해당 경로를 자연스럽게 활용
zi의 인터랙티브 선택 과정을 agent와의 대화로 치환한 셈이다. z 명령과 -l(목록), -s(점수) 쿼리 옵션만으로 fzf 없이도 동일한 기능을 구현할 수 있었다.
덕분에 “그 블로그 레포에서 뭐 좀 확인해줘”라고 말할 때, 정확한 경로를 몰라도 /z blog 한 번이면 agent가 알아서 경로를 파악한다. zoxide의 DB가 사용자와 agent 사이의 공유 지식 역할을 하는 것이다.