Zellij Yazi 터미널 환경 만들기: 3페인 개발 워크플로 완성

Zellij Yazi 터미널 환경은 파일 탐색기와 작업 셸, 로그 창을 한 화면에 고정해 두고 명령 한 줄로 복원하는 개발 환경이다. Zellij는 레이아웃을 KDL 파일로 선언해 두면 같은 화면을 그대로 재현해 주고, Yazi는 그 안에서 비동기로 동작하는 파일 매니저 역할을 맡는다. 작업을 시작할 때마다 터미널 탭을 세 개 열고, 하나는 프로젝트 디렉터리를 오가며 파일을 찾고, 하나는 에디터를 띄우고, 나머지 하나는 로그를 tail로 흘려보내는 패턴을 반복해 본 사람이라면 이 과정을 매번 손으로 재현하는 일이 얼마나 지루한지 안다. tmux로 세션을 저장해 두는 방법도 있지만 설정 파일을 손보는 순간부터 학습 비용이 만만치 않다. 두 도구 모두 Rust로 작성됐고 MIT 라이선스이며, 설정을 거의 건드리지 않은 상태에서도 바로 쓸 만하다는 공통점이 있다. 이번 포스팅에서는 Zellij와 Yazi를 각각 설치하고 설정한 뒤, 두 도구를 묶어 파일 탐색·작업·로그를 한 화면에 담는 3페인 레이아웃을 완성하는 과정을 정리하고자 한다.

터미널 창 여섯 개로 버티던 시절, Zellij와 Yazi는 무엇을 해결하나

Zellij는 “A terminal workspace with batteries included”를 표방하는 터미널 멀티플렉서이고, Yazi는 모든 I/O를 비동기로 처리하는 터미널 파일 매니저다. 하나는 화면을 나누고 세션을 유지하는 역할, 다른 하나는 그 화면 안에서 파일을 찾고 미리 보고 옮기는 역할을 맡는다. 둘을 합치면 GUI 없이도 IDE에 가까운 작업 공간이 만들어진다.

두 프로젝트 모두 Rust로 작성돼 단일 바이너리로 배포되며 MIT 라이선스다. 2026년 7월 기준 Zellij 저장소는 GitHub 스타 34.6k, 포크 1.3k를 기록하고 있고, Yazi 저장소는 스타 40.9k로 오히려 더 앞선다. 다만 Yazi는 아직 공개 베타 단계라 개발이 활발한 만큼 키바인딩이나 설정 키 이름이 바뀔 수 있다는 점은 감안해야 한다.

Zellij가 tmux와 갈라지는 지점은 floating pane, stacked pane, 그리고 선언적 레이아웃 시스템이다. 여기에 WebAssembly 기반 플러그인, 실시간 협업(multiplayer), 내장 웹 클라이언트까지 들어 있다. Yazi 쪽은 CPU 작업을 여러 스레드에 분산하고 Kitty·iTerm2·WezTerm·Ghostty의 이미지 프리뷰 프로토콜을 지원하며, Lua로 UI와 커스텀 프리뷰어를 확장할 수 있다.

5분이면 끝나는 Zellij 설치와 첫 세션

Zellij는 설치 없이 한 줄로 먼저 체험해 볼 수 있다. 공식 launch 스크립트를 실행하면 임시 바이너리를 내려받아 세션을 띄우므로, 시스템에 무언가를 남기기 전에 감을 잡기 좋다. 마음에 들면 그때 Cargo나 패키지 매니저로 정식 설치하면 된다.

# 설치 없이 즉시 체험 (임시 바이너리로 세션 실행)
bash <(curl -L https://zellij.dev/launch)

# Rust 툴체인이 있다면 Cargo로 설치
cargo install --locked zellij

# macOS Homebrew
brew install zellij

# 설치 없이 즉시 체험 (임시 바이너리로 세션 실행)
bash <(curl -L https://zellij.dev/launch)

# Rust 툴체인이 있다면 Cargo로 설치
cargo install --locked zellij

# macOS Homebrew
brew install zellij

첫 번째 명령은 바이너리를 시스템 경로에 설치하지 않고 그 자리에서 Zellij를 띄운다. 두 번째의 --locked 플래그는 저장소에 커밋된 Cargo.lock의 의존성 버전을 그대로 쓰라는 뜻이다. 빌드 재현성이 필요하면 반드시 붙인다. Zellij는 주요 배포판의 패키지 매니저도 지원하므로 apt나 pacman 계열을 쓴다면 그쪽이 더 빠르다.

설치가 끝나면 zellij 한 번으로 세션이 시작되고, 화면 아래에 상태 바가 뜬다. 이 상태 바가 지금 어떤 모드에 있고 어떤 키를 누를 수 있는지를 계속 표시해 준다. tmux처럼 치트시트를 따로 띄워 놓을 일이 없다. 버전별 변경 내역은 Zellij 릴리스 페이지에 정리돼 있으며, 최신 안정 버전은 v0.44.3(2026-05-13)이다.

세션은 붙이고 떼는 것이다, Zellij CLI 최소 세트

Zellij 세션 관리는 attach, list, kill 세 동사로 거의 끝난다. 각 명령에는 한 글자 단축형이 있어서 실제로 손에 익는 건 a, ls, k 정도다. 세션을 떼어 놓고(detach) 나중에 다시 붙이는 흐름은 tmux와 동일하다.

zellij attach my-project      # 세션 접속 (단축: zellij a)
zellij list-sessions          # 세션 목록 (단축: zellij ls)
zellij kill-session my-project  # 세션 종료 (단축: zellij k)
zellij kill-all-sessions      # 전체 세션 종료 (단축: zellij ka)

zellij run -- tail -f /tmp/my-log-file   # 새 페인에서 명령 실행
zellij action new-pane                    # 현재 세션에 페인 추가
zellij action new-tab --layout /path/to/layout.kdl --name "my tab"

zellij attach my-project      # 세션 접속 (단축: zellij a)
zellij list-sessions          # 세션 목록 (단축: zellij ls)
zellij kill-session my-project  # 세션 종료 (단축: zellij k)
zellij kill-all-sessions      # 전체 세션 종료 (단축: zellij ka)

zellij run -- tail -f /tmp/my-log-file   # 새 페인에서 명령 실행
zellij action new-pane                    # 현재 세션에 페인 추가
zellij action new-tab --layout /path/to/layout.kdl --name "my tab"

앞의 네 줄이 세션 생명주기를 다루는 명령이고, 뒤의 세 줄이 실행 중인 세션을 외부에서 조작하는 명령이다. zellij run -- 뒤에 오는 것은 새 페인에서 실행할 명령이며, 로그를 따로 띄울 때 자주 쓴다. zellij action 계열은 스크립트에서 세션을 조립할 때 유용한데, v0.44.0(2026-03-23)에서 CLI 자동화가 대폭 보강되면서 활용 폭이 넓어졌다.

여기서 detach 키를 짚고 넘어갈 필요가 있다. Session 모드 진입키인 Ctrl+o를 누른 뒤 d를 누르면 세션이 떨어진다. tmux 호환 모드(Ctrl+b)에서도 d가 같은 동작을 하므로, 손이 이미 Ctrl+b에 익숙하다면 그대로 써도 무방하다.

모드 키를 외우지 않아도 되는 이유

Zellij의 키바인딩은 모드 기반이다. Ctrl 조합으로 특정 모드에 들어간 뒤 단일 키로 동작을 지시하고, Enter나 Esc로 Normal 모드에 돌아온다. 외울 필요가 없는 이유는 현재 모드에서 쓸 수 있는 키가 하단 상태 바에 계속 표시되기 때문이다. 모드별 기본 키맵 전체와 커스터마이징 방법은 Zellij 키바인딩 문서에 정리돼 있다.

Pane 모드에 들어간 뒤에는 h/j/k/l 또는 방향키로 포커스를 옮긴다. Vim 키맵이 그대로 통하므로 손이 헤맬 일이 적다. Normal 모드 복귀는 Enter 또는 Esc인데, Locked 모드만은 예외로 Ctrl+g를 다시 눌러야 풀린다. 이 Locked 모드는 Zellij 안에서 Vim이나 Emacs를 띄웠을 때 단축키가 겹치는 문제를 해결하는 안전장치다.

Ctrl+b 호환 모드가 기본으로 들어 있다는 점은 tmux 사용자에게 꽤 크게 다가온다. 새 키맵을 통째로 익히지 않고도 첫날부터 평소 속도로 작업할 수 있고, 손에 익는 만큼 네이티브 모드로 넘어가면 된다.

config.kdl은 대체 어디에 두어야 하나

Zellij 설정 파일은 config.kdl 하나이며, 기본 위치는 $HOME/.config/zellij/config.kdl이다. Zellij는 정해진 순서로 설정 디렉터리를 탐색하므로, 파일을 엉뚱한 곳에 만들어 두고 설정이 안 먹는다고 헤매는 상황을 피하려면 이 순서를 알아 둘 필요가 있다.

탐색 순서는 --config-dir 플래그, ZELLIJ_CONFIG_DIR 환경 변수, $HOME/.config/zellij, OS 기본 경로, /etc/zellij 순이다. OS 기본 경로는 Linux가 ~/.config/zellij, macOS가 ~/Library/Application Support/org.Zellij-Contributors.Zellij로 갈린다. macOS에서 XDG 경로를 쓰고 싶다면 $HOME/.config/zellij에 두면 그쪽이 먼저 잡힌다.

# 기본 설정을 파일로 덤프해 출발점 만들기
mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

# 특정 설정 파일을 지정해 실행
zellij --config ~/.config/zellij/config-alt.kdl

# 설정을 무시하고 기본값으로 실행 (설정 문제 진단용)
zellij options --clean

# 기본 설정을 파일로 덤프해 출발점 만들기
mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

# 특정 설정 파일을 지정해 실행
zellij --config ~/.config/zellij/config-alt.kdl

# 설정을 무시하고 기본값으로 실행 (설정 문제 진단용)
zellij options --clean

zellij setup --dump-config는 현재 적용 중인 기본 설정 전체를 출력하므로, 이를 파일로 받아 두면 어떤 항목이 있는지 훑어보며 고칠 수 있다. ZELLIJ_CONFIG_FILE 환경 변수로 파일을 직접 지정하는 방법도 있다. 설정이 꼬였다 싶으면 --clean으로 한 번 띄워 본다. 문제가 사라지면 원인이 설정 파일에 있다는 뜻이고, 그대로면 다른 곳을 봐야 한다.

한 가지 편한 점은 Zellij가 실행 중에도 설정 파일 변경을 감시해 대부분의 필드를 자동 반영한다는 것이다. 테마나 키바인딩을 조정할 때 세션을 껐다 켜지 않아도 되므로 시행착오 비용이 낮다. 전체 옵션 설명은 Zellij 공식 문서에 정리돼 있다.

Yazi 설치에서 진짜 중요한 건 선택적 의존성이다

Yazi 본체 설치는 한 줄이지만, 실제 사용감을 결정하는 것은 함께 까는 선택적 의존성이다. PDF를 열었는데 미리보기가 비어 있거나 동영상 썸네일이 안 뜨는 대부분의 원인이 여기 있다. 처음부터 한 번에 깔아 두는 편이 나중에 원인을 추적하는 것보다 훨씬 싸게 먹힌다.

# macOS (Homebrew)
brew install yazi ffmpeg-full sevenzip jq poppler fd ripgrep fzf zoxide resvg imagemagick-full font-symbols-only-nerd-font
brew link ffmpeg-full imagemagick-full -f --overwrite

# Arch Linux
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick

# Cargo로 소스 빌드
cargo install --force yazi-build

# macOS (Homebrew)
brew install yazi ffmpeg-full sevenzip jq poppler fd ripgrep fzf zoxide resvg imagemagick-full font-symbols-only-nerd-font
brew link ffmpeg-full imagemagick-full -f --overwrite

# Arch Linux
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick

# Cargo로 소스 빌드
cargo install --force yazi-build

macOS 쪽 두 번째 줄인 brew link ... -f --overwrite를 빠뜨리면 기존 ffmpeg나 imagemagick과 심볼릭 링크가 충돌해 미리보기가 동작하지 않을 수 있다. 각 패키지의 역할은 명확히 나뉜다. ffmpeg는 비디오 썸네일, 7zip은 아카이브 내부 탐색, jq는 JSON 미리보기, poppler는 PDF 미리보기, imagemagick은 폰트와 HEIC 미리보기를 담당한다.

검색과 이동 계열도 별도 바이너리에 의존한다. fd는 파일명 검색, ripgrep은 파일 내용 검색, fzf는 빠른 탐색, zoxide는 이동 기록 기반 점프에 쓰인다. Yazi의 검색은 이미 검증된 CLI 도구를 감싼 형태다. 그래서 해당 바이너리가 없으면 그 키가 조용히 아무 일도 하지 않는다. 에러 메시지도 없어서 원인을 찾는 데 시간이 꽤 걸린다. 설치 상세는 Yazi 설치 문서에서 플랫폼별로 확인할 수 있고, 최신 버전은 v26.5.6(2026-05-05)이다.

z와 Z를 헷갈리면 하루를 날린다

Yazi에서 소문자 z는 fzf 플러그인, 대문자 Z는 zoxide 플러그인이다. 인터넷 글의 상당수가 이 둘을 반대로 적어 놓았으니 여기서 한 번 확정해 두고 간다. 나머지 키는 Vim 계열이라 이동은 h/j/k/l로 끝나고, 검색은 소문자 s가 fd 기반 파일명 검색, 대문자 S가 ripgrep 기반 내용 검색이다. 기본 키맵 전체는 Yazi 키맵 문서에서 확인할 수 있다.

a로 이름을 입력할 때 끝에 슬래시를 붙이면 파일이 아니라 디렉터리가 만들어진다. 표를 통째로 외울 필요는 없다. F1 하나만 기억해 두면 나머지는 그 자리에서 찾을 수 있다.

Yazi를 껐는데 디렉터리가 그대로인 이유

Yazi에서 한참 디렉터리를 옮겨 다니다 q로 나왔는데 셸이 원래 자리에 그대로 있는 현상은 버그가 아니다. 자식 프로세스는 부모 셸의 작업 디렉터리를 바꿀 수 없기 때문이며, 이를 우회하려면 Yazi 공식 문서의 셸 래퍼 함수를 등록해야 한다.

function y() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
    command yazi "$@" --cwd-file="$tmp"
    IFS= read -r -d '' cwd < "$tmp"
    [ "$cwd" != "$PWD" ] && [ -d "$cwd" ] && builtin cd -- "$cwd"
    command rm -f -- "$tmp"
}

function y() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
    command yazi "$@" --cwd-file="$tmp"
    IFS= read -r -d '' cwd < "$tmp"
    [ "$cwd" != "$PWD" ] && [ -d "$cwd" ] && builtin cd -- "$cwd"
    command rm -f -- "$tmp"
}

이 함수는 임시 파일을 하나 만들고 --cwd-file 옵션으로 Yazi에게 종료 시점의 디렉터리를 그 파일에 쓰게 한다. Yazi가 끝나면 파일 내용을 읽어 현재 디렉터리와 다르고 실제로 존재하는 경로일 때만 cd를 수행한 뒤 임시 파일을 지운다. command yazi와 builtin cd처럼 앞에 한정자를 붙인 이유는 별칭이나 다른 함수가 가로채는 것을 막기 위해서다.

함수를 ~/.zshrc나 ~/.bashrc에 넣고 셸을 다시 읽으면 이제 yazi 대신 y로 실행하게 된다. 여기서 종료 키가 두 갈래로 나뉜다. q로 나오면 마지막으로 보던 디렉터리로 셸이 따라 이동하고, 대문자 Q로 나오면 디렉터리를 바꾸지 않은 채 종료한다. 잠깐 다른 폴더를 훑어보기만 하고 원래 자리로 돌아오고 싶을 때 Q를 쓰면 된다.

yazi.toml, keymap.toml, theme.toml 세 파일로 끝내기

Yazi 설정은 ~/.config/yazi/ 아래 세 파일로 나뉜다. yazi.toml은 일반 동작, keymap.toml은 단축키, theme.toml은 색상을 담당한다. Windows는 %AppData%\yazi\config\이며, YAZI_CONFIG_HOME 환경 변수로 위치를 바꿔 여러 프로필을 쓸 수도 있다.

# 대체 설정 디렉터리로 Yazi 실행 (설정 실험용)
YAZI_CONFIG_HOME=~/.config/yazi-alt yazi

# 대체 설정 디렉터리로 Yazi 실행 (설정 실험용)
YAZI_CONFIG_HOME=~/.config/yazi-alt yazi

설정을 실험할 때 이 방식이 유용하다. 기존 설정을 건드리지 않고 별도 디렉터리에서 키맵이나 테마를 마음껏 바꿔 본 뒤, 만족스러운 부분만 원래 설정으로 옮기면 된다. 기본 프리셋 전체는 Yazi 프리셋 저장소에 공개돼 있는데, 이를 통째로 복사할 필요는 없고 덮어쓰고 싶은 항목만 골라 적으면 나머지는 기본값이 적용된다.

키맵은 왜 통째로 갈아엎으면 안 되나

키맵을 바꿀 때는 전체를 재정의하지 말고 prepend_keymap 또는 append_keymap으로 필요한 항목만 얹는 방식을 쓴다.

[mgr]
prepend_keymap = [
    { on = "<C-a>", run = "act1", desc = "Single action with `Ctrl + a`" },
]

[mgr]
prepend_keymap = [
    { on = "<C-a>", run = "act1", desc = "Single action with `Ctrl + a`" },
]

prepend_keymap은 기본 키맵보다 앞에 삽입되므로 같은 키가 있으면 이쪽이 이긴다. 반대로 append_keymap은 뒤에 붙어 기본값이 없을 때만 동작한다. 주의할 점은 TOML 문법 제약상 위와 같은 인라인 배열 스타일과 [[...]] 테이블 스타일을 한 키에 섞어 쓸 수 없다는 것이다. 하나를 정해 일관되게 유지해야 한다. 색상 테마는 flavors 저장소에서 가져다 쓰면 된다.

ya pkg 한 줄로 플러그인을 dotfiles에 묶기

플러그인은 ya라는 전용 CLI로 관리한다.

ya pkg add yazi-rs/plugins:git   # GitHub에서 clone 후 plugins 디렉터리로 설치
ya pkg add owner/my-plugin
ya pkg list                       # 설치된 플러그인 목록
ya pkg delete yazi-rs/plugins:git
ya pkg install                    # package.toml의 잠긴 버전으로 일괄 설치
ya pkg upgrade                    # 전체 업그레이드

ya pkg add yazi-rs/plugins:git   # GitHub에서 clone 후 plugins 디렉터리로 설치
ya pkg add owner/my-plugin
ya pkg list                       # 설치된 플러그인 목록
ya pkg delete yazi-rs/plugins:git
ya pkg install                    # package.toml의 잠긴 버전으로 일괄 설치
ya pkg upgrade                    # 전체 업그레이드

ya pkg add는 저장소를 자동으로 clone해 플러그인 디렉터리로 복사하고 package.toml에 버전을 기록한다. 이 파일을 dotfiles 저장소에 함께 커밋해 두면 새 장비에서 ya pkg install 한 번으로 동일한 플러그인 구성을 복원할 수 있다. Yazi 플러그인은 Lua로 작성되며 UI 요소, 동작, 커스텀 프리뷰어까지 손댈 수 있다. 버전별 변경 사항은 Yazi 릴리스 페이지에서 확인할 수 있다.

Zellij 레이아웃 KDL, 화면을 코드로 적는다

Zellij 레이아웃은 KDL 문법으로 작성하는 선언적 설정이다. 어떤 페인을 어느 방향으로 나누고 무슨 명령을 띄울지 파일에 적어 두면, 명령 한 줄로 매번 같은 화면이 재현된다. 가장 단순한 형태는 다음과 같다.

layout {
    pane
    pane split_direction="vertical" {
        pane
        pane command="htop"
    }
}

layout {
    pane
    pane split_direction="vertical" {
        pane
        pane command="htop"
    }
}

최상위 layout 블록 안의 pane이 화면 하나에 대응한다. 기본 분할 방향은 가로이고, split_direction="vertical"을 주면 그 블록 내부가 세로로 나뉜다. 중첩된 pane 블록은 그 영역을 다시 쪼개며, command 속성이 있으면 해당 페인에서 그 명령이 곧바로 실행된다.

size, cwd, focus로 화면의 나머지 절반을 채운다

여기에 붙일 수 있는 속성은 몇 가지가 더 있다. size는 pane size=5처럼 줄 수로도, pane size="80%"처럼 비율로도 지정한다. 다만 퍼센트가 아닌 고정 줄 수 지정은 공식 문서상 아직 unstable로 분류돼 있어 퍼센트 쪽이 안전하다. cwd는 최상위에 cwd "/home/aram/code/my-project"로 기준 경로를 잡고 개별 페인에서 pane cwd="src"처럼 상대 경로를 적는 방식이 편하다. focus=true를 준 페인이 세션 시작 시 포커스를 가져가고, 인자가 필요한 명령은 args로 넘긴다.

layout {
    tab name="main" split_direction="vertical" {
        pane command="htop" size="30%"
        pane split_direction="horizontal" {
            pane focus=true cwd="/tmp"
            pane command="git" {
                args "diff"
            }
        }
    }
}

layout {
    tab name="main" split_direction="vertical" {
        pane command="htop" size="30%"
        pane split_direction="horizontal" {
            pane focus=true cwd="/tmp"
            pane command="git" {
                args "diff"
            }
        }
    }
}

tab 블록으로 감싸면 이름이 붙은 탭이 만들어지고, 한 레이아웃에 여러 탭을 정의할 수도 있다. 마지막 pane처럼 args를 중괄호 안에 별도 줄로 적으면 git diff가 실행된 페인이 뜬다. size="30%"와 focus=true는 앞서 설명한 대로 각각 폭과 초기 포커스를 지정한다.

세션을 통째로 못 뜨게 만드는 KDL 한 줄

args를 pane command="git" { args "diff" }처럼 한 줄로 줄여 쓰면 안 된다. Zellij가 쓰는 KDL 파서는 노드 종결자로 줄바꿈이나 세미콜론만 허용해서, 이 형태는 “Nodes can only be terminated by ‘;’ or a valid line ending” 에러를 내며 세션 자체가 뜨지 않는다. 굳이 한 줄로 쓰려면 { args "diff"; }처럼 세미콜론을 넣어야 하지만, 여러 줄로 적는 쪽이 읽기에도 낫다.

버전도 오해하기 쉬운 부분이다. KDL 레이아웃 시스템 자체는 v0.32.0(2022-10-25)부터 있었으므로 위 예시는 오래된 버전에서도 그대로 동작한다. v0.44.0에서 추가된 것은 동명의 별개 기능인 Layout Manager 플러그인 UI로, 레이아웃을 새 탭에 열거나 현재 탭 구성을 그대로 레이아웃 파일로 녹화해 준다.

Zellij Yazi 터미널 환경의 완성형, 3페인 dev.kdl

이제 두 도구를 하나로 묶을 차례다. 왼쪽에 Yazi로 파일을 탐색하고, 오른쪽 위에서 실제 작업을 하고, 오른쪽 아래로 로그를 흘려보내는 3페인 구성이 가장 실용적이다. 아래 파일을 ~/.config/zellij/layouts/dev.kdl로 저장한다.

layout {
    // 세션 전체의 기준 디렉터리
    cwd "/Users/kwanghee/workspace/my-project"

    tab name="dev" split_direction="vertical" {
        // 왼쪽: Yazi 파일 탐색기 (전체 폭의 30%)
        pane command="yazi" size="30%"

        // 오른쪽: 위아래로 다시 분할
        pane split_direction="horizontal" {
            // 오른쪽 위: 작업용 셸, 시작 시 포커스
            pane focus=true cwd="src"

            // 오른쪽 아래: 애플리케이션 로그 tail (높이 30%)
            pane size="30%" command="tail" {
                args "-f" "/tmp/app.log"
            }
        }
    }
}

layout {
    // 세션 전체의 기준 디렉터리
    cwd "/Users/kwanghee/workspace/my-project"

    tab name="dev" split_direction="vertical" {
        // 왼쪽: Yazi 파일 탐색기 (전체 폭의 30%)
        pane command="yazi" size="30%"

        // 오른쪽: 위아래로 다시 분할
        pane split_direction="horizontal" {
            // 오른쪽 위: 작업용 셸, 시작 시 포커스
            pane focus=true cwd="src"

            // 오른쪽 아래: 애플리케이션 로그 tail (높이 30%)
            pane size="30%" command="tail" {
                args "-f" "/tmp/app.log"
            }
        }
    }
}

최상위 cwd가 기준 경로를 잡아 주므로 개별 페인에서는 cwd="src"처럼 상대 경로만 적으면 된다. 왼쪽 페인은 command="yazi"로 파일 매니저를 바로 띄우고 폭을 30%로 고정한다. 오른쪽은 다시 가로로 나뉘어 위쪽이 작업용 셸, 아래쪽이 로그 tail이 되며, focus=true가 붙은 작업용 셸에 커서가 놓인 채로 세션이 시작된다.

로그 대신 git 상태를 보고 싶다면 아래쪽 페인의 명령만 바꾸면 된다.

            // 로그 대신 lazygit을 띄우는 변형
            pane size="30%" command="lazygit"

            // 로그 대신 lazygit을 띄우는 변형
            pane size="30%" command="lazygit"

프로젝트 성격에 맞춰 변형을 두어 개 만들어 두고 골라 쓰면 된다. command로 지정한 프로그램이 시스템에 없으면 해당 페인에 에러가 표시되고 나머지 페인은 그대로 뜬다. 팀원 장비마다 도구 설치 상태가 달라도 레이아웃 전체가 깨지지는 않는다는 뜻인데, 이 동작은 공식 문서에 명시된 보장은 아니니 새 레이아웃을 팀에 배포하기 전에 한 번 확인해 두면 좋다.

dev.kdl을 명령 한 줄로 불러오는 법

# 이름만으로 레이아웃 실행 (config/layouts/ 아래에 있을 때)
zellij --layout dev

# 임의 경로의 레이아웃 파일 직접 지정
zellij --layout /path/to/layout_file.kdl

# 실행 중인 세션의 활성 탭 레이아웃을 교체
zellij action override-layout /path/to/new-layout.kdl

# 이름만으로 레이아웃 실행 (config/layouts/ 아래에 있을 때)
zellij --layout dev

# 임의 경로의 레이아웃 파일 직접 지정
zellij --layout /path/to/layout_file.kdl

# 실행 중인 세션의 활성 탭 레이아웃을 교체
zellij action override-layout /path/to/new-layout.kdl

레이아웃 파일을 config/layouts/ 디렉터리에 두면 확장자 없이 이름만으로 호출된다. dev.kdl을 넣어 두었다면 zellij --layout dev 한 줄이 곧 3페인 Zellij Yazi 터미널 환경 전체를 복원하는 명령이 된다. 이미 세션이 떠 있는 상태에서 구성을 바꾸고 싶다면 세션을 죽이지 않고 override-layout으로 갈아 끼울 수 있다. 다만 이 명령이 바꾸는 범위는 세션 전체가 아니라 활성 탭 하나이니, 탭을 여러 개 띄워 둔 상태라면 나머지 탭은 그대로 남는다. 레이아웃 파일에서 쓸 수 있는 노드와 속성의 전체 목록은 Zellij 레이아웃 문서에 정리돼 있다.

tmux를 버려야 하나: 숫자로 보는 비교

결론부터 말하면 성능이 목적이라면 tmux가 여전히 가볍고, 재현 가능한 작업 환경이 목적이라면 Zellij가 앞선다. 우열보다는 지향점이 다르다고 보는 쪽이 맞다. 측정된 수치로 보면 격차 자체는 현대 하드웨어에서 무시할 만한 수준이다.

위 수치는 공식 벤치마크가 아니라 100페인 분할 렌더링 비교 같은 서드파티 측정치이고, 로드한 플러그인 수와 페인 개수에 따라 편차가 크다. 실제로 Zellij 이슈 #3594에는 tmux 6MB 대 Zellij 80MB라는 훨씬 벌어진 보고도 올라와 있다. 절대값보다는 방향성만 참고하는 쪽이 맞다.

Zellij가 메모리를 더 쓰는 이유는 WASM 플러그인 런타임과 상태 바를 내장하기 때문이다. 대신 그 대가로 얻는 것이 발견 가능성과 플러그인 생태계다. 페인 확장 한계에서는 tmux가 명확히 유리하므로, 수십 개 페인을 동시에 띄우는 사용 패턴이라면 tmux를 유지하는 쪽을 권한다.

이주 문턱을 낮추는 건 앞서 언급한 Ctrl+b tmux 호환 모드다. 기존 근육 기억을 그대로 쓰면서 Zellij의 레이아웃 시스템만 먼저 가져올 수 있다. 한 번에 다 갈아엎지 않아도 된다는 뜻이다. 참고로 v0.44.2(2026-05-05)부터는 CSI 2031 시퀀스를 인식해 터미널의 다크·라이트 테마 전환을 자동으로 따라간다.

마치며

예전에는 새 프로젝트에 붙을 때마다 페인을 나누고 디렉터리를 옮기고 로그를 거는 데 3분쯤을 썼고, 그 3분이 아까워서 터미널을 그냥 켜 둔 채 며칠씩 방치하곤 했다. 지금은 zellij --layout dev 한 줄이면 끝나니 세션을 부담 없이 죽였다 살린다.

Yazi 쪽에서는 y() 래퍼 함수를 등록하기 전까지 며칠을 손해 봤다. 파일을 찾아 놓고도 셸은 엉뚱한 데 있어서 결국 경로를 복사해 cd를 치고 있었는데, 공식 문서에 이미 답이 있었다. 새 도구를 붙일 때 설치만 하고 문서의 셸 통합 항목을 건너뛰는 습관이 문제였다. 그리고 z와 Z는 여전히 가끔 헷갈린다. 소문자가 fzf, 대문자가 zoxide다. 지금까지 Zellij Yazi 터미널 환경 구축에 대해서 정리해 보았다.

FAQ