• Published: 2026-03-20
• Categories: DIY
• Tags: vscode, tmux, terminal, macos, ubuntu

VS Code 안에서 작업하다 보면 굳이 별도 터미널 앱을 열지 않고도 tmux까지 같이 쓰고 싶어질 때가 있습니다. 문제는 VS Code와 tmux가 모두 키 입력을 적극적으로 쓰기 때문에, 아무 설정 없이 붙이면 Ctrl+B 계열 prefix나 Shift+Enter 같은 입력이 기대한 대로 동작하지 않는 경우가 많다는 점입니다.

이 글은 VS Code 통합 터미널에서 tmux를 처음 써보려는 사람을 기준으로, "어디서 충돌이 나고", "무엇만 먼저 설정하면 되는지", "tmux.conf는 어디까지 넣으면 되는지"를 정리한 초안입니다.

먼저 정리: VS Code와 tmux는 어디서 부딪히나

tmux는 기본적으로 Ctrl+B를 prefix로 사용합니다. 그런데 VS Code도 자체 단축키 체계를 가지고 있고, 통합 터미널은 일반 터미널 앱과는 다르게 입력을 한 번 더 가로챕니다. 그래서 초보자가 제일 먼저 겪는 문제는 보통 아래 둘입니다.

• tmux prefix를 눌렀다고 생각했는데 VS Code 단축키가 먼저 반응한다.
• Shift+Enter 같은 조합이 쉘이나 tmux까지 그대로 전달되지 않는다.

결론부터 말하면, VS Code 쪽에서 "어떤 키는 터미널이 포커스일 때 그대로 tmux에 넘긴다"는 규칙을 먼저 정해주고, tmux 쪽에서는 최소한의 동작만 켜는 방식이 가장 단순합니다.

1. keybindings.json에서 prefix 충돌을 먼저 정리한다

VS Code에서 가장 먼저 만질 파일은 keybindings.json입니다. 초보자 기준으로 중요한 건 "터미널이 아닐 때는 VS Code 단축키로 쓰고, 터미널 안에서는 tmux로 넘긴다"는 분기입니다.

아래 예시는 macOS 기준으로 Cmd+B를 tmux prefix(Ctrl+B)로 보내는 설정입니다.

[
  {
    "key": "cmd+b",
    "command": "-workbench.action.toggleSidebarVisibility"
  },
  {
    "key": "cmd+b",
    "command": "workbench.action.toggleSidebarVisibility",
    "when": "!terminalFocus"
  },
  {
    "key": "cmd+b",
    "command": "workbench.action.terminal.sendSequence",
    "when": "terminalFocus && !terminalFindFocus",
    "args": { "text": "\u0002" }
  },
  {
    "key": "shift+enter",
    "command": "workbench.action.terminal.sendSequence",
    "args": { "text": "\u001b[13;2u" },
    "when": "terminalFocus"
  }
]

핵심은 세 줄입니다.

• Cmd+B 기본 동작을 제거한다.
• 터미널 밖에서는 여전히 사이드바 토글로 쓴다.
• 터미널 안에서는 \u0002, 즉 Ctrl+B를 tmux로 보낸다.

이렇게 두면 "VS Code는 VS Code대로 쓰고, 터미널 안에서는 tmux prefix만 잘 쓰고 싶다"는 요구를 꽤 깔끔하게 만족시킬 수 있습니다.

Shift+Enter 설정은 선택 사항이지만, REPL이나 특정 TUI 앱에서 줄바꿈/실행을 구분해서 쓰고 싶을 때 꽤 유용합니다.

2. settings.json은 많이 건드릴 필요가 없다

실제로 tmux 사용에 직접적인 영향을 주는 건 keybindings.json 쪽입니다. settings.json은 필요한 것만 최소한으로 두는 편이 초보자에게 낫습니다.

현재 설정 중에서 tmux 사용과 함께 볼 만한 값은 아래 정도입니다.

{
  "terminal.integrated.fontFamily": "D2Coding",
  "terminal.integrated.enableMultiLinePasteWarning": "never",
  "terminal.integrated.shellIntegration.enabled": false
}

이 설정들의 의미는 대략 이렇습니다.

• terminal.integrated.fontFamily
  • 터미널 가독성을 위해 폰트를 맞춥니다.
• terminal.integrated.enableMultiLinePasteWarning
  • tmux 안에서 여러 줄을 붙여넣을 때 경고가 거슬리면 끌 수 있습니다.
• terminal.integrated.shellIntegration.enabled
  • 환경에 따라 VS Code shell integration이 프롬프트나 입력 처리와 부딪힌다고 느껴질 때 꺼볼 수 있습니다.

다만 이 세 가지는 "편의"에 가깝고, tmux prefix 충돌 해결의 본질은 아닙니다. 처음에는 keybindings.json부터 맞추고, 나머지는 필요할 때 추가하는 편이 낫습니다.

3. tmux.conf는 최소 설정부터 시작하는 편이 좋다

초보자가 처음부터 복잡한 .tmux.conf를 넣으면, 무엇 때문에 편해졌는지보다 무엇 때문에 꼬였는지부터 추적하게 됩니다. VS Code 안에서 쓸 목적이라면 아래 정도로 시작해도 충분합니다.

Ubuntu 예시

# Enable mouse support
set -g mouse on

# Use vi-mode in copy mode
setw -g mode-keys vi

# VS Code에서 보낸 Shift+Enter 신호를 현재 실행 중인 앱에 그대로 전달
bind-key -n S-Enter send-keys "\u001b[13;2u"

# 패널 상단에 번호와 이름을 보여준다
set -g pane-border-status top
set -g pane-border-format " [ #P: #T ] "

macOS 예시

# 복사 모드에서 vi 키 사용
set-window-option -g mode-keys vi

# 마우스로 패널 선택, 스크롤, 리사이즈
set -g mouse on

# 패널 상단에 번호와 이름 표시
set -g pane-border-status top
set -g pane-border-format "#P: #T"

macOS 쪽 메모에는 아래 같은 설정도 함께 적혀 있었습니다.

#set -g default-terminal "xterm-256color"
#set -ga terminal-overrides ",xterm-256color:Tc"
#set -s extended-keys off
#set -s escape-time 0

이 값들은 환경에 따라 도움이 될 수 있지만, VS Code 통합 터미널에서 tmux를 처음 붙이는 단계에서는 일단 주석 상태로 두고 시작하는 편이 안전합니다. 색상 문제나 특수키 입력 문제가 실제로 생길 때 하나씩 켜보는 쪽이 디버깅하기 쉽습니다.

4. 왜 이 설정들이 필요한지 짧게 이해하고 넘어가면 편하다

초보자 입장에서는 각 줄이 길게 느껴질 수 있으니, 체감 효과만 짚어보면 이렇습니다.

• set -g mouse on
  • 패널 클릭, 스크롤, 크기 조절이 가능해져서 진입 장벽이 내려갑니다.
• mode-keys vi
  • copy mode에서 hjkl, /, Space 같은 vi 스타일 이동이 가능해집니다.
• pane-border-status top
  • 패널이 많아졌을 때 지금 어디가 어느 작업용 패널인지 구분하기 쉬워집니다.
• pane-border-format "#P: #T"
  • 패널 번호와 패널 제목을 같이 표시합니다.
• bind-key -n S-Enter ...
  • VS Code가 보낸 Shift+Enter 입력을 tmux 안쪽 프로그램까지 전달합니다.

결국 이 설정의 목적은 "tmux를 더 강하게 제어한다"가 아니라, VS Code 안에서 tmux가 덜 답답하게 느껴지도록 만드는 데 있습니다.

5. 패널 이름을 붙이면 여러 작업을 동시에 보기 쉬워진다

패널 테두리에 #T를 표시하려면 패널 제목을 바꿔주는 습관이 있으면 좋습니다. 예를 들어 한쪽 패널은 server, 다른 쪽은 editor, 또 다른 패널은 git처럼 이름을 붙여두면 현재 작업 맥락이 눈에 바로 들어옵니다.

아래 이미지는 패널 상단에 이름이 붙은 상태를 보여줍니다.

패널 상단에 번호와 이름을 같이 보여주면 여러 작업을 동시에 볼 때 훨씬 덜 헷갈립니다.

패널 이름은 tmux 안에서 다음처럼 줄 수 있습니다.

tmux select-pane -T server

또는 tmux command prompt를 열어서 직접 넣어도 됩니다.

Ctrl+B :
select-pane -T editor

이 글의 설정에서 pane-border-format이 #P: #T를 출력하도록 되어 있으므로, 제목을 붙여두면 바로 반영됩니다.

6. 처음 설정할 때는 이 순서로 확인하면 덜 헷갈린다

처음부터 모든 걸 한꺼번에 맞추려 하지 말고, 아래 순서로 확인하는 편이 안전합니다.

1. VS Code 통합 터미널에서 tmux를 실행한다.
2. Cmd+B를 눌렀을 때 사이드바가 아니라 tmux prefix로 동작하는지 본다.
3. set -g mouse on 상태에서 패널 클릭과 스크롤이 되는지 확인한다.
4. pane-border-status top 설정으로 패널 상단 라벨이 보이는지 확인한다.
5. tmux select-pane -T test로 패널 제목이 바뀌는지 확인한다.
6. 필요한 경우에만 Shift+Enter 전달 설정을 추가한다.

이 순서대로 보면 "VS Code 문제인지", "tmux 설정 문제인지", "내가 추가한 확장 기능이나 쉘 설정 문제인지"를 조금 더 쉽게 분리할 수 있습니다.

7. 초보자가 자주 헷갈리는 부분

Ctrl+B를 그대로 쓰면 안 되나

쓸 수는 있습니다. 다만 VS Code에서 다른 단축키와 겹치거나, 운영체제/키보드 습관상 손이 불편하면 macOS에서는 Cmd+B를 tmux prefix 대용으로 보내는 방식이 더 편할 수 있습니다.

settings.json 전체를 그대로 복사해야 하나

그럴 필요는 없습니다. tmux와 직접 관련 있는 건 극히 일부입니다. 특히 초보자라면 keybinding 충돌 해결과 .tmux.conf 최소 설정만 먼저 적용하는 편이 낫습니다.

macOS와 Ubuntu 설정을 둘 다 넣어야 하나

아닙니다. 기본 골격은 비슷하지만, 실제로는 본인이 주로 쓰는 환경에 맞춰 하나부터 시작하는 편이 낫습니다.

마무리

VS Code 안에서 tmux를 쓰는 핵심은 "tmux를 엄청 복잡하게 꾸미는 것"이 아니라, VS Code가 가로채는 키 입력만 필요한 만큼 정리하는 데 있습니다. 초보자라면 mouse on, mode-keys vi, 패널 이름 표시, 그리고 Cmd+B -> Ctrl+B 전달 정도만 먼저 적용해도 체감이 꽤 큽니다.

나중에 익숙해지면 그때부터 pane title 자동화, 세션 복구, prefix 변경 같은 설정을 얹어도 늦지 않습니다. 처음에는 "잘 되는 최소 설정"으로 시작하는 편이 훨씬 오래 갑니다.