cmux.vim

cmux 위에서 동작하는 AI CLI(Claude Code / Gemini CLI)에 Vim에서 파일 참조를 보내주는 Vim 플러그인입니다.

English version: README.en.md

주요 기능

• 현재 파일 경로를 @mention 참조로 AI CLI에 전송
• 커서 라인 번호와 함께 전송
• 비주얼 모드로 선택한 라인 범위 전송
• 비주얼 선택 영역의 원시 텍스트 전송 (터미널 IME에서 한글/CJK 입력이 까다로울 때 유용)
• 스크래치 버퍼에서 프롬프트를 작성한 뒤 한 번에 전송
• Claude Code / Gemini CLI surface 자동 감지

설치

vim-plug

Plug 'gaebalai/cmux.vim'

수동 설치

git clone https://github.com/gaebalai/cmux.vim.git ~/.vim/pack/plugins/start/cmux.vim

업데이트

vim-plug

:PlugUpdate cmux.vim

수동 업데이트

git -C ~/.vim/pack/plugins/start/cmux.vim pull

사용법

cmux에서 두 개의 탭을 엽니다 — 하나는 Vim, 다른 하나는 AI CLI(Claude Code 또는 Gemini CLI).

키 매핑

키	모드	동작	예시
<Leader>c	Normal	파일 참조 전송	@src/main.ts
<Leader>c	Visual	파일 + 라인 범위 전송	@src/main.ts:L42-55
<Leader>cs	Visual	선택한 텍스트를 원시 입력으로 전송	(선택된 라인)
<Leader>cp	Normal	프롬프트 스크래치 버퍼 열기	(아래 참조)

기본 매핑은 <Plug> 매핑으로 자유롭게 변경할 수 있습니다 (아래 "키 매핑 커스터마이징" 참고). AI CLI surface는 처음 호출 시 자동으로 감지됩니다.

한국어 / CJK 입력 보조

터미널에서 동작하는 AI CLI에 한글(또는 다른 CJK 문자)을 직접 입력하면 IME 조합 문제로 깨지거나 어색하게 들어가는 경우가 많습니다. 이를 우회하기 위해, IME가 안정적으로 동작하는 Vim에서 텍스트를 작성한 뒤 cmux send로 그대로 전송하는 두 가지 흐름을 제공합니다.

• 비주얼 선택 전송 — Vim에서 라인을 선택하고 <Leader>cs(또는 :'<,'>CmuxSendSelection)를 누르면 됩니다. 멀티라인 선택은 shift+enter로 라인 사이를 분리해 보내므로, 프롬프트가 도중에 제출되는 일이 없습니다.
• 프롬프트 스크래치 버퍼 — <Leader>cp(또는 :CmuxPrompt)를 누르면 임시 버퍼가 열립니다. 거기서 자유롭게 한글 프롬프트를 작성한 뒤(#로 시작하는 줄은 자동으로 제외됩니다), :w 또는 :CmuxPromptSend로 전송합니다. :CmuxPromptCancel(또는 :q!)로 폐기할 수 있습니다.

명령어

명령어	설명
:CmuxSendFile	파일 경로 전송
:CmuxSendPos	파일 경로 + 라인 번호 전송
:'<,'>CmuxSendRange	파일 경로 + 라인 범위 전송
:'<,'>CmuxSendSelection	선택된 라인을 원시 텍스트로 전송
:CmuxPrompt	프롬프트 작성용 스크래치 버퍼 열기
:CmuxPromptSend	(프롬프트 버퍼 안에서) 버퍼 내용 전송
:CmuxPromptCancel	(프롬프트 버퍼 안에서) 버퍼 폐기
:CmuxDetect	AI CLI surface 재감지
:CmuxSetSurface	surface ID 수동 지정

설정

" 대상 surface 수동 지정 (자동 감지가 동작하므로 보통 필요 없음)
let g:cmux_surface = 'surface:2'

" 전송 후 대상 surface 패널로 자동 포커스 (기본값: 1)
let g:cmux_auto_focus = 0

" 전송 후 자동으로 Enter 입력 (기본값: 0)
let g:cmux_auto_enter = 1

키 매핑 커스터마이징

.vimrc에 <Plug> 매핑을 정의하면, 기본 <Leader>c 매핑은 자동으로 비활성화됩니다.

nmap <Leader>c  <Plug>(cmux-send-file)
nmap <Leader>p  <Plug>(cmux-send-pos)
vmap <Leader>c  <Plug>(cmux-send-range)
vmap <Leader>cs <Plug>(cmux-send-selection)
nmap <Leader>cp <Plug>(cmux-prompt)

사전 요구 사항

• cmux가 설치되어 있어야 합니다
• cmux 위에서 Vim과 AI CLI(Claude Code 또는 Gemini CLI)가 실행 중이어야 합니다

라이선스

MIT © 2026 gaebalai