Part 3: Setup Package

3.1 Setup Reference

이 페이지는 claude-code-setup 패키지의 전체 구성 파일을 문서화합니다. 새 맥북 환경을 셋업하거나 Claude Code 최적 환경을 구성할 때 참고하세요. 각 탭에서 개별 파일의 전체 소스와 상세 설명을 확인할 수 있습니다.

패키지 폴더 구조

폴더 구조
claude-code-setup/
├── setup-new-mac.sh          # 메인 설치 스크립트 (8단계)
├── Brewfile                  # Homebrew 패키지 목록
├── zshrc                     # .zshrc 설정 파일
├── p10k.zsh                  # Powerlevel10k 테마 설정
├── .tmux.conf                # tmux 설정 파일
├── com.googlecode.iterm2.plist  # iTerm2 설정 백업
├── fonts/
│   └── *.ttf                 # MesloLGS NF 폰트 파일
├── claude/
│   ├── settings.json         # Claude Code 전역 설정
│   ├── notify.sh             # 스마트 알림 스크립트
│   └── statusline.sh         # 상태 표시줄 스크립트
└── karabiner/
    └── karabiner.json        # Karabiner-Elements 키 매핑

파일별 상세 레퍼런스

setup-new-mac.sh - 메인 설치 스크립트

새 맥북에서 실행하는 원클릭 셋업 스크립트입니다. 총 8단계로 구성되며, 각 단계에서 이미 설치된 항목은 자동으로 건너뜁니다 (멱등성 보장).

💡 사용법
  1. claude-code-setup 폴더를 새 맥으로 복사 (AirDrop, USB 등)
  2. cd ~/Desktop/claude-code-setup
  3. chmod +x setup-new-mac.sh
  4. ./setup-new-mac.sh
setup-new-mac.sh
#!/bin/bash
set -e

# ============================================
# 새 맥북 미니 환경 세팅 스크립트
# ============================================
# 사용법:
#   1. mac-migration 폴더를 새 맥으로 복사 (AirDrop, USB 등)
#   2. cd ~/Desktop/mac-migration (또는 복사한 경로)
#   3. chmod +x setup-new-mac.sh
#   4. ./setup-new-mac.sh

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
echo "========================================"
echo "  새 맥북 미니 환경 세팅 시작"
echo "========================================"

# ----- 1. Homebrew 설치 -----
echo ""
echo "[1/8] Homebrew 설치..."
if ! command -v brew &>/dev/null; then
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"
else
    echo "  -> Homebrew 이미 설치됨. 건너뜀."
fi

# ----- 2. Brewfile로 패키지 일괄 설치 -----
echo ""
echo "[2/8] Homebrew 패키지 설치 (Brewfile)..."
brew bundle --file="$SCRIPT_DIR/Brewfile"
echo "  -> 완료"

# ----- 3. Oh My Zsh 설치 -----
echo ""
echo "[3/8] Oh My Zsh 설치..."
if [ ! -d "$HOME/.oh-my-zsh" ]; then
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
else
    echo "  -> Oh My Zsh 이미 설치됨. 건너뜀."
fi

# ----- 4. Zsh 플러그인 & 테마 설치 -----
echo ""
echo "[4/8] Zsh 플러그인 & 테마 설치..."

if [ ! -d "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k" ]; then
    git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
        "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k"
    echo "  -> Powerlevel10k 설치 완료"
else
    echo "  -> Powerlevel10k 이미 설치됨"
fi

if [ ! -d "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions" ]; then
    git clone https://github.com/zsh-users/zsh-autosuggestions \
        "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions"
    echo "  -> zsh-autosuggestions 설치 완료"
else
    echo "  -> zsh-autosuggestions 이미 설치됨"
fi

if [ ! -d "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting" ]; then
    git clone https://github.com/zsh-users/zsh-syntax-highlighting \
        "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting"
    echo "  -> zsh-syntax-highlighting 설치 완료"
else
    echo "  -> zsh-syntax-highlighting 이미 설치됨"
fi

# ----- 5. 폰트 설치 -----
echo ""
echo "[5/8] 폰트 설치..."
mkdir -p ~/Library/Fonts
cp "$SCRIPT_DIR"/fonts/*.ttf ~/Library/Fonts/ 2>/dev/null && echo "  -> 폰트 복사 완료" || echo "  -> 복사할 폰트 없음"

# ----- 6. tmux 설치 확인 -----
echo ""
echo "[6/8] tmux 설치 확인..."
if command -v tmux &>/dev/null; then
    echo "  -> tmux 이미 설치됨: $(tmux -V)"
else
    brew install tmux
    echo "  -> tmux 설치 완료: $(tmux -V)"
fi

# ----- 7. Claude Code 설정 -----
echo ""
echo "[7/8] Claude Code 설정..."
mkdir -p "$HOME/.claude"
cp "$SCRIPT_DIR/claude/notify.sh" "$HOME/.claude/notify.sh"
chmod +x "$HOME/.claude/notify.sh"
echo "  -> notify.sh 복사 완료"

cp "$SCRIPT_DIR/claude/statusline.sh" "$HOME/.claude/statusline.sh"
chmod +x "$HOME/.claude/statusline.sh"
echo "  -> statusline.sh 복사 완료"

if [ -f "$HOME/.claude/settings.json" ]; then
    BACKUP_FILE="$HOME/.claude/settings.json.backup.$(date +%Y%m%d%H%M%S)"
    cp "$HOME/.claude/settings.json" "$BACKUP_FILE"
    echo "  -> 기존 settings.json 백업 완료: $BACKUP_FILE"
    jq -s '.[0] * .[1]' "$BACKUP_FILE" "$SCRIPT_DIR/claude/settings.json" > "$HOME/.claude/settings.json"
    echo "  -> settings.json 병합 완료 (기존 설정 보존)"
else
    cp "$SCRIPT_DIR/claude/settings.json" "$HOME/.claude/settings.json"
    echo "  -> settings.json 생성 완료"
fi

# ----- 8. 설정 파일 복원 -----
echo ""
echo "[8/8] 설정 파일 복원..."
if [ -f "$HOME/.zshrc" ]; then
    cp "$HOME/.zshrc" "$HOME/.zshrc.backup.$(date +%Y%m%d%H%M%S)"
    echo "  -> 기존 .zshrc 백업 완료"
fi
cp "$SCRIPT_DIR/zshrc" "$HOME/.zshrc"
echo "  -> .zshrc 복원 완료"

cp "$SCRIPT_DIR/p10k.zsh" "$HOME/.p10k.zsh"
echo "  -> .p10k.zsh 복원 완료"

if [ -f "$HOME/.tmux.conf" ]; then
    cp "$HOME/.tmux.conf" "$HOME/.tmux.conf.backup.$(date +%Y%m%d%H%M%S)"
    echo "  -> 기존 .tmux.conf 백업 완료"
fi
cp "$SCRIPT_DIR/.tmux.conf" "$HOME/.tmux.conf"
echo "  -> .tmux.conf 복원 완료"

cp "$SCRIPT_DIR/com.googlecode.iterm2.plist" "$HOME/Library/Preferences/com.googlecode.iterm2.plist"
echo "  -> iTerm2 설정 복원 완료"

if [ -d "$SCRIPT_DIR/karabiner" ]; then
    mkdir -p "$HOME/.config"
    cp -r "$SCRIPT_DIR/karabiner" "$HOME/.config/karabiner"
    echo "  -> Karabiner 설정 복원 완료"
fi

echo ""
echo "========================================"
echo "  설치 완료!"
echo "========================================"
echo ""
echo "다음 단계:"
echo "  1. iTerm2를 완전히 종료 후 다시 열어주세요."
echo "  2. 터미널을 새로 열거나 'source ~/.zshrc'를 실행하세요."
echo ""

8단계 상세 설명

[1/8]
이름: Homebrew 설치
설명: macOS 패키지 매니저 설치. Apple Silicon(/opt/homebrew) 경로를 ~/.zprofile에 등록합니다.
멱등성: 설치 여부 확인 후 건너뜀
[2/8]
이름: Brewfile 패키지 설치
설명: brew bundle 명령으로 Brewfile에 정의된 모든 CLI 도구, 앱, 폰트를 일괄 설치합니다.
멱등성: 이미 설치된 패키지는 자동 건너뜀
[3/8]
이름: Oh My Zsh 설치
설명: Zsh 프레임워크 설치. --unattended 플래그로 셸 변경 프롬프트 없이 자동 설치됩니다.
멱등성: ~/.oh-my-zsh 디렉토리 존재 확인
[4/8]
이름: Zsh 플러그인 & 테마
설명: Powerlevel10k 테마, zsh-autosuggestions, zsh-syntax-highlighting 플러그인을 git clone으로 설치합니다.
멱등성: 각 플러그인 디렉토리 존재 확인
[5/8]
이름: 폰트 설치
설명: MesloLGS NF 폰트 파일(*.ttf)을 ~/Library/Fonts/에 복사합니다. Powerlevel10k 테마에 필요합니다.
멱등성: 파일 복사 (덮어쓰기)
[6/8]
이름: tmux 설치 확인
설명: tmux가 설치되어 있는지 확인하고, 없으면 brew로 설치합니다. Agent Teams의 teammateMode에 필수입니다.
멱등성: 설치 여부 확인 후 건너뜀
[7/8]
이름: Claude Code 설정
설명: ~/.claude/ 디렉토리에 notify.sh, statusline.sh, settings.json을 복사합니다. 기존 settings.json이 있으면 jq로 병합합니다.
멱등성: 기존 설정 백업 후 병합
[8/8]
이름: 설정 파일 복원
설명: .zshrc, .p10k.zsh, .tmux.conf, iTerm2 plist, Karabiner 설정을 홈 디렉토리에 복원합니다. 기존 파일은 타임스탬프 백업됩니다.
멱등성: 기존 파일 백업 후 덮어쓰기
⚠️ 주의 사항
  • set -e로 인해 어떤 단계에서든 오류 발생 시 즉시 중단됩니다.
  • 7단계의 settings.json 병합에는 jq가 필요합니다 (2단계 Brewfile에서 설치됨).
  • 설치 완료 후 반드시 iTerm2를 재시작하고 source ~/.zshrc를 실행해야 합니다.

settings.json - Claude Code 전역 설정

~/.claude/settings.json에 위치하는 Claude Code 전역 설정 파일입니다. 모델 선택, 환경 변수, 권한 관리, 훅, 플러그인 등 Claude Code의 모든 동작을 제어합니다.

~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://43.201.162.58:4317",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000",
    "OTEL_LOGS_EXPORT_INTERVAL": "5000",
    "OTEL_SERVICE_NAME": "claude-code-{회사 영어 이름}"
  },
  "permissions": {
    "allow": ["Bash(*)", "WebSearch"],
    "deny": [
      "Bash(*rm -rf *)", "Bash(*killall *)", "Bash(*sudo *)",
      "Bash(*git push --force*)", "Bash(*npm publish*)",
      "Bash(*dd *)", "Bash(*mkfs *)", "Bash(*shutdown*)", "Bash(*reboot*)",
      "Bash(*poweroff*)", "Bash(*fdisk*)", "Bash(*diskutil erase*)",
      "Bash(*diskutil partitionDisk*)",
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "Read(~/.ssh/**)"
    ],
    "ask": [
      "Bash(*rm *)", "Bash(*curl *)", "Bash(*wget *)", "Bash(*git push *)",
      "Bash(*git reset --hard*)", "Bash(*git clean -f*)", "Bash(*pkill *)",
      "Bash(*chmod *)", "Bash(*chown *)", "Bash(*ssh *)", "Bash(*scp *)",
      "Bash(*launchctl *)", "Bash(*crontab *)"
    ]
  },
  "model": "sonnet",
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/notify.sh Asks"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/notify.sh Asks"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/notify.sh Stops"
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "enabledPlugins": {
    "ralph-loop@claude-plugins-official": true,
    "context7@claude-plugins-official": true,
    "github@claude-plugins-official": true,
    "superpowers@claude-plugins-official": true,
    "code-review@claude-plugins-official": true
  },
  "teammateMode": "tmux"
}

섹션별 상세 설명

model

기본 모델을 "sonnet"으로 설정합니다. 일반적인 개발 작업에는 Sonnet이 비용 대비 성능이 가장 좋습니다. 복잡한 아키텍처 결정이 필요할 때는 대화 중에 /model opus로 전환할 수 있습니다.

env (환경 변수)

두 가지 핵심 기능을 활성화합니다:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
값: "1"
설명: Agent Teams 기능 활성화. 여러 에이전트가 tmux 세션에서 협업 가능
CLAUDE_CODE_ENABLE_TELEMETRY
값: "1"
설명: OpenTelemetry 텔레메트리 수집 활성화
OTEL_*_EXPORTER
값: "otlp"
설명: 메트릭, 로그, 트레이스를 OTLP 포맷으로 내보내기
OTEL_EXPORTER_OTLP_PROTOCOL
값: "grpc"
설명: gRPC 프로토콜 사용 (HTTP보다 효율적)
OTEL_EXPORTER_OTLP_ENDPOINT
값: "http://...:4317"
설명: 텔레메트리 수집 서버 주소 (OTEL Collector)
OTEL_METRIC_EXPORT_INTERVAL
값: "10000"
설명: 메트릭 내보내기 간격 (10초)
OTEL_LOGS_EXPORT_INTERVAL
값: "5000"
설명: 로그 내보내기 간격 (5초)
OTEL_SERVICE_NAME
값: "claude-code-{이름}"
설명: 텔레메트리에 표시될 서비스 식별 이름
permissions (3계층 권한 관리)

Claude Code의 도구 사용 권한을 allow / ask / deny 3계층으로 관리합니다. 이 구조는 생산성과 안전성을 동시에 확보하기 위한 핵심 설정입니다.

allow (허용)
동작: 묻지 않고 즉시 실행
포함 항목: Bash(*) - 모든 Bash 명령, WebSearch - 웹 검색
deny (차단)
동작: 절대 실행 불가 (시도 시 오류)
포함 항목: 시스템 파괴 명령: rm -rf, killall, sudo, shutdown, reboot
위험한 Git: git push --force
패키지 배포: npm publish
디스크 조작: dd, mkfs, fdisk, diskutil erase/partitionDisk
민감 파일 읽기: .env, secrets/**, ~/.ssh/**
ask (확인)
동작: 실행 전 사용자에게 물어봄
포함 항목: 파일 삭제: rm
네트워크: curl, wget, ssh, scp
Git 위험 명령: git push, git reset --hard, git clean -f
프로세스: pkill
권한 변경: chmod, chown
시스템 서비스: launchctl, crontab
ℹ️ 권한 우선순위

deny > ask > allow 순으로 적용됩니다. 예를 들어 Bash(*)가 allow에 있어도, Bash(*rm -rf *)는 deny에 있으므로 차단됩니다. Bash(*rm *)는 ask에 있으므로 단순 rm은 확인을 거칩니다.

hooks (3가지 이벤트 훅)

Claude Code 라이프사이클 이벤트에 자동으로 트리거되는 훅을 설정합니다. 모든 훅은 notify.sh 스크립트를 호출하여 사용자에게 알림을 보냅니다.

Notification
트리거 시점: Claude가 알림을 보낼 때
동작: notify.sh Asks 실행 - 사용자에게 알림 전송
PreToolUse
트리거 시점: AskUserQuestion 도구 사용 직전
동작: notify.sh Asks 실행 - 사용자 입력이 필요할 때 알림
Stop
트리거 시점: Claude 작업 완료 시
동작: notify.sh Stops 실행 - 작업 종료 알림 전송
statusLine

Claude Code 하단에 표시되는 상태 표시줄을 설정합니다. statusline.sh 스크립트가 모델명, 작업 디렉토리, Git 브랜치, 컨텍스트 사용률, 비용, 실행 시간을 실시간으로 표시합니다.

enabledPlugins (5개 공식 플러그인)
ralph-loop
설명: Ralph Loop 패턴 지원 - 수렴할 때까지 반복 실행하는 에이전트 루프
context7
설명: Context7 통합 - 최신 라이브러리 문서를 자동으로 컨텍스트에 포함
github
설명: GitHub 통합 - PR 생성, 이슈 관리, 코드 리뷰 기능 강화
superpowers
설명: 고급 기능 확장 - 추가 도구와 향상된 에이전트 기능 제공
code-review
설명: 코드 리뷰 자동화 - PR 변경 사항 분석 및 리뷰 코멘트 생성
teammateMode

"tmux"로 설정하면 Agent Teams가 tmux 세션에서 각 에이전트를 별도 패널로 실행합니다. 각 에이전트의 작업 과정을 실시간으로 모니터링할 수 있어 디버깅과 협업에 유리합니다.

notify.sh - 스마트 알림 스크립트

Claude Code가 사용자의 입력을 기다리거나 작업을 완료했을 때 실행되는 알림 스크립트입니다. 핵심 기능은 사용자가 이미 해당 탭을 보고 있으면 알림을 건너뛰는 스마트 감지 로직입니다.

~/.claude/notify.sh
#!/bin/bash
LOG=~/.claude/notify.log
TYPE=$(echo "$1" | tr '[:lower:]' '[:upper:]')

front_app=$(osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true' 2>/dev/null)
control_client=$(tmux list-clients -F '#{client_name} #{client_control_mode}' 2>/dev/null | awk '$2 == "1" {print $1; exit}')
client_window=$(tmux display-message -c "$control_client" -p '#{window_index}' 2>/dev/null)
my_window=$(tmux display-message -t "$TMUX_PANE" -p '#{window_index}' 2>/dev/null)

{
  echo "--- $(date) ---"
  echo "type: $TYPE"
  echo "front_app: $front_app"
  echo "control_client: $control_client"
  echo "client_window: $client_window"
  echo "my_window: $my_window"
  echo "TMUX_PANE: $TMUX_PANE"
} >> "$LOG"

if [ "$front_app" = "iTerm2" ] && [ "$client_window" = "$my_window" ]; then
  echo "→ exit 0 (same tab)" >> "$LOG"
  exit 0
fi

pane_tty=$(tmux display-message -t "$TMUX_PANE" -p '#{pane_tty}')
echo "→ sending OSC9 notify ($TYPE) to $pane_tty" >> "$LOG"
printf '\ePtmux;\e\e]9;Claude %s\a\e\\' "$1" > "$pane_tty"

스마트 알림 로직 분석

이 스크립트는 불필요한 알림을 방지하기 위해 3단계 감지 로직을 사용합니다:

1. 타입 추출
코드: TYPE=$(echo "$1" | tr ...)
설명: 인자(Asks 또는 Stops)를 대문자로 변환하여 알림 유형 식별
2. 활성 앱 감지
코드: osascript -e 'tell application ...'
설명: macOS AppleScript로 현재 최전면 앱 이름을 가져옴 (예: iTerm2)
3. tmux 창 비교
코드: client_window vs my_window
설명: tmux의 control 클라이언트가 보고 있는 윈도우 인덱스와 현재 패널의 윈도우 인덱스를 비교
4. 조건 판단
코드: front_app = "iTerm2" && client_window = my_window
설명: 사용자가 iTerm2를 보고 있고, 동일한 tmux 윈도우를 보고 있으면 알림 건너뜀
5. 알림 전송
코드: printf '\ePtmux;...'
설명: OSC 9 이스케이프 시퀀스를 pane의 TTY로 전송. iTerm2가 이를 감지하여 시스템 알림 표시
💡 OSC 9 알림이란?

OSC (Operating System Command) 9는 터미널에서 시스템 알림을 트리거하는 이스케이프 시퀀스입니다. \e]9;메시지\a 형식이며, tmux 내부에서는 \ePtmux;\e...\e\\로 감싸서 전달합니다. iTerm2는 이 시퀀스를 감지하면 macOS 알림 센터에 알림을 표시합니다.

ℹ️ 로그 파일

모든 알림 이벤트는 ~/.claude/notify.log에 기록됩니다. 알림이 예상대로 동작하지 않을 때 이 로그를 확인하여 디버깅할 수 있습니다. front_app, client_window, my_window 값을 비교하면 알림이 전송되었는지 건너뛰었는지 확인할 수 있습니다.

statusline.sh - 상태 표시줄 스크립트

Claude Code 하단에 실시간으로 표시되는 상태 표시줄을 생성하는 스크립트입니다. stdin으로 JSON 데이터를 받아 모델명, 디렉토리, Git 브랜치, 컨텍스트 사용률, 비용, 실행 시간을 표시합니다.

~/.claude/statusline.sh
#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
BAR=$(printf "%${FILLED}s" | tr ' ' '█')$(printf "%${EMPTY}s" | tr ' ' '░')

MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))

BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | 🌿 $(git branch --show-current 2>/dev/null)"

echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
COST_FMT=$(printf '$%.2f' "$COST")
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"

표시 정보 및 동작 방식

Claude Code가 이 스크립트를 호출할 때 stdin으로 JSON 데이터를 전달합니다. 스크립트는 jq로 필요한 값을 추출하고 ANSI 색상 코드와 함께 출력합니다.

모델명
소스 경로: .model.display_name
설명: 현재 사용 중인 모델 (예: Claude Sonnet). 시안 색상으로 표시
작업 디렉토리
소스 경로: .workspace.current_dir
설명: 현재 작업 중인 디렉토리명 (마지막 경로만 표시)
Git 브랜치
소스 경로: git branch --show-current
설명: 현재 Git 브랜치명. Git 저장소가 아니면 숨김
컨텍스트 사용률
소스 경로: .context_window.used_percentage
설명: 프로그레스 바로 표시. 70% 이상 노란색, 90% 이상 빨간색
누적 비용
소스 경로: .cost.total_cost_usd
설명: 현재 세션의 총 API 비용 (USD). 노란색으로 표시
실행 시간
소스 경로: .cost.total_duration_ms
설명: 총 실행 시간을 분:초 형식으로 표시

컨텍스트 사용률 색상 코드

0% ~ 69%
색상: 초록색
의미: 여유 있음 - 정상 사용 범위
70% ~ 89%
색상: 노란색
의미: 주의 - 컨텍스트가 많이 채워짐. 불필요한 정보 정리 권장
90% ~ 100%
색상: 빨간색
의미: 위험 - 컨텍스트 초과 임박. /compact 명령으로 압축 필요
ℹ️ 출력 예시

상태 표시줄은 2줄로 구성됩니다:

[Claude 4 Sonnet] 📁 my-project | 🌿 feature/auth
████████░░ 78% | $0.42 | ⏱️ 3m 24s

.tmux.conf - tmux 설정

Claude Code와 Agent Teams 운영에 최적화된 tmux 설정 파일입니다. 256색 지원, 알림 통과, vi 모드, 마우스 지원 등을 포함합니다.

~/.tmux.conf
set -g default-terminal "screen-256color"
set-option -ga terminal-overrides ",xterm-256color:Tc"
set -g history-limit 50000
set -g visual-bell on
set -g bell-action any
set -g allow-passthrough on
set -g activity-action none
set -g silence-action none
set -g mouse on
setw -g mode-keys vi
bind -T copy-mode-vi M-Up send-keys -X scroll-up
bind -T copy-mode-vi M-Down send-keys -X scroll-down
bind -T copy-mode-vi M-PageUp send-keys -X halfpage-up
bind -T copy-mode-vi M-PageDown send-keys -X halfpage-down
bind -T copy-mode-vi PageDown send-keys -X page-down
bind -T copy-mode-vi PageUp send-keys -X page-up
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

설정 항목별 설명

default-terminal
값: screen-256color
설명: 기본 터미널 유형을 256색으로 설정. statusline.sh의 ANSI 색상 코드가 정상 표시됩니다.
Claude Code 관련: 상태 표시줄 색상
terminal-overrides
값: xterm-256color:Tc
설명: True Color(24비트) 지원 추가. 더 풍부한 색상 표현이 가능합니다.
Claude Code 관련: 코드 하이라이팅
history-limit
값: 50000
설명: 스크롤백 버퍼를 50,000줄로 설정. 긴 Claude Code 출력을 놓치지 않고 확인할 수 있습니다.
Claude Code 관련: 긴 출력 보존
visual-bell
값: on
설명: 비프음 대신 시각적 깜빡임으로 벨 이벤트를 표시합니다.
Claude Code 관련: 알림 시각화
bell-action
값: any
설명: 모든 윈도우의 벨 이벤트를 감지합니다. notify.sh의 OSC 9 알림과 연동됩니다.
Claude Code 관련: 알림 감지
allow-passthrough
값: on
설명: 이스케이프 시퀀스가 tmux를 통과하도록 허용합니다. notify.sh의 OSC 9 알림에 필수적인 설정입니다.
Claude Code 관련: 알림 전송 필수
activity-action
값: none
설명: 윈도우 활동 시 자동 동작을 비활성화. Claude 작업 중 불필요한 윈도우 전환을 방지합니다.
Claude Code 관련: 작업 방해 방지
silence-action
값: none
설명: 무활동 모니터링을 비활성화. Claude가 생각 중일 때 오탐 알림을 방지합니다.
Claude Code 관련: 오탐 방지
mouse
값: on
설명: 마우스로 패널 선택, 스크롤, 리사이즈가 가능합니다. Agent Teams 모니터링 시 편리합니다.
Claude Code 관련: 패널 전환 편의
mode-keys vi
값: vi
설명: 복사 모드에서 vi 키 바인딩 사용. hjkl로 이동, v로 선택합니다.
Claude Code 관련: 키보드 탐색
copy-mode-vi 바인딩
값: M-Up/Down 등
설명: Option+화살표, PageUp/Down으로 스크롤. Claude 출력을 빠르게 탐색할 수 있습니다.
Claude Code 관련: 출력 탐색
copy-pipe-and-cancel
값: pbcopy
설명: y 키로 선택 영역을 macOS 클립보드에 복사합니다. Claude 출력을 쉽게 복사할 수 있습니다.
Claude Code 관련: 출력 복사
⚠️ allow-passthrough 설정 중요

allow-passthrough on이 없으면 notify.sh의 OSC 9 알림이 tmux에서 차단됩니다. 이 설정은 Claude Code의 스마트 알림 시스템이 정상적으로 동작하기 위한 필수 설정입니다. 보안상 이유로 기본값은 off이므로 반드시 명시적으로 켜야 합니다.

Brewfile - Homebrew 패키지 목록

brew bundle 명령으로 일괄 설치되는 패키지 목록입니다. CLI 도구, 앱(Cask), 폰트를 포함합니다.

Brewfile
# ============================================
# Brewfile - Homebrew 패키지 목록
# ============================================
# 사용법: brew bundle --file=Brewfile

# ----- CLI 도구 -----
brew "git"                    # 버전 관리
brew "jq"                     # JSON 처리 (statusline.sh, settings.json 병합에 필수)
brew "gh"                     # GitHub CLI
brew "tmux"                   # 터미널 멀티플렉서 (Agent Teams에 필수)
brew "fzf"                    # 퍼지 파인더
brew "ripgrep"                # 빠른 텍스트 검색
brew "bat"                    # cat 대체 (구문 강조)
brew "eza"                    # ls 대체 (아이콘, Git 상태)
brew "fd"                     # find 대체 (더 빠르고 직관적)
brew "tldr"                   # 간단한 명령어 예시
brew "tree"                   # 디렉토리 트리 표시
brew "wget"                   # 파일 다운로드
brew "htop"                   # 시스템 모니터링

# ----- Node.js -----
brew "node"                   # Node.js (Claude Code 설치에 필요)
brew "pnpm"                   # 빠른 패키지 매니저

# ----- Cask 앱 -----
cask "iterm2"                 # 터미널 앱
cask "karabiner-elements"     # 키 매핑 도구
cask "visual-studio-code"     # 코드 에디터
cask "raycast"                # Spotlight 대체 런처

# ----- 폰트 -----
cask "font-meslo-lg-nerd-font"   # Powerlevel10k 권장 폰트
필수 CLI
패키지: git, jq, tmux, gh
Claude Code 관련성: Claude Code 동작, settings.json 병합, Agent Teams, GitHub 연동에 각각 필수
검색/탐색
패키지: ripgrep, fzf, fd
Claude Code 관련성: Claude Code의 Grep 도구가 내부적으로 ripgrep 사용. fzf/fd는 파일 탐색 효율 향상
뷰어
패키지: bat, eza, tree
Claude Code 관련성: 코드 미리보기, 디렉토리 탐색 시 구문 강조와 아이콘 표시
런타임
패키지: node, pnpm
Claude Code 관련성: Claude Code는 npm으로 설치 (npm i -g @anthropic-ai/claude-code)
패키지: iTerm2, Karabiner, VS Code, Raycast
Claude Code 관련성: iTerm2는 OSC 9 알림 지원, Karabiner는 키 매핑, VS Code는 Claude Code 확장 지원
폰트
패키지: font-meslo-lg-nerd-font
Claude Code 관련성: Powerlevel10k 테마의 아이콘/글리프 표시에 필요

karabiner.json - 키 매핑 설정

Karabiner-Elements의 키 매핑 설정입니다. 한영 전환, Caps Lock 활용 등 macOS 키보드 커스터마이징을 담당합니다.

karabiner/karabiner.json
{
  "profiles": [
    {
      "name": "Default",
      "selected": true,
      "simple_modifications": [
        {
          "from": { "key_code": "right_command" },
          "to": [{ "key_code": "f18" }]
        },
        {
          "from": { "key_code": "right_option" },
          "to": [{ "key_code": "f19" }]
        }
      ],
      "complex_modifications": {
        "rules": [
          {
            "description": "Caps Lock → Hyper Key (Cmd+Ctrl+Opt+Shift) when held, Escape when tapped",
            "manipulators": [
              {
                "from": {
                  "key_code": "caps_lock",
                  "modifiers": { "optional": ["any"] }
                },
                "to": [
                  {
                    "key_code": "left_shift",
                    "modifiers": ["left_command", "left_control", "left_option"]
                  }
                ],
                "to_if_alone": [{ "key_code": "escape" }],
                "type": "basic"
              }
            ]
          }
        ]
      }
    }
  ]
}
Simple Modification
원래 키: right_command
변경 후: F18
용도: 한영 전환 키로 사용. macOS 입력 소스 전환에 F18 지정
Simple Modification
원래 키: right_option
변경 후: F19
용도: 추가 단축키 트리거로 활용 가능
Complex Modification
원래 키: Caps Lock (길게)
변경 후: Hyper Key (Cmd+Ctrl+Opt+Shift)
용도: 모든 수정자 키 조합. 다른 앱과 충돌 없이 전용 단축키 생성 가능
Complex Modification
원래 키: Caps Lock (짧게)
변경 후: Escape
용도: vi 모드에서 ESC 대용. tmux 복사 모드 종료에도 사용
💡 Hyper Key 활용법

Caps Lock을 누른 채로 다른 키를 조합하면 Hyper Key(Cmd+Ctrl+Opt+Shift)로 동작합니다. 이 조합은 다른 앱에서 거의 사용하지 않으므로, Raycast나 VS Code에서 충돌 없는 전용 단축키를 만들 수 있습니다. 예: Hyper + T = iTerm2 전환, Hyper + C = Claude Code 열기 등.

설치되는 것들

터미널 환경

iTerm2
설명: macOS 전용 고급 터미널 앱. 분할 패널, 프로필, OSC 9 알림, tmux 통합 지원
설치 방법: Homebrew Cask (cask "iterm2")
Oh My Zsh
설명: Zsh 셸 프레임워크. 플러그인 시스템, 테마 관리, 편의 별칭(alias) 제공
설치 방법: 공식 설치 스크립트 (curl)
Powerlevel10k
설명: 고성능 Zsh 테마. Git 상태, 실행 시간, 에러 코드 등을 프롬프트에 표시
설치 방법: git clone (Oh My Zsh custom 테마)
tmux
설명: 터미널 멀티플렉서. 세션 유지, 패널 분할, Agent Teams 지원
설치 방법: Homebrew (brew "tmux")
MesloLGS NF
설명: Nerd Font 패치 폰트. Powerlevel10k 아이콘/글리프 표시에 필요
설치 방법: fonts/*.ttf 복사

Zsh 플러그인

zsh-autosuggestions
설명: 명령어 히스토리 기반 자동 완성 제안
효과: 이전에 입력한 명령어를 회색으로 미리 보여줌. 오른쪽 화살표로 수락
zsh-syntax-highlighting
설명: 명령어 실시간 구문 강조
효과: 올바른 명령어는 초록색, 잘못된 명령어는 빨간색으로 표시. 오타 즉시 발견

Homebrew 패키지 (CLI 도구)

git
역할: 버전 관리 시스템
대체 대상: -
jq
역할: JSON 처리 도구
대체 대상: -
gh
역할: GitHub CLI
대체 대상: 웹 브라우저에서 GitHub 접속
tmux
역할: 터미널 멀티플렉서
대체 대상: -
fzf
역할: 퍼지 파인더
대체 대상: -
ripgrep
역할: 빠른 텍스트 검색
대체 대상: grep
bat
역할: 구문 강조 파일 뷰어
대체 대상: cat
eza
역할: 모던 디렉토리 목록
대체 대상: ls
fd
역할: 빠른 파일 검색
대체 대상: find
tldr
역할: 명령어 간단 예시
대체 대상: man
tree
역할: 디렉토리 트리 표시
대체 대상: -
wget
역할: 파일 다운로드
대체 대상: curl
htop
역할: 시스템 모니터링
대체 대상: top
node
역할: JavaScript 런타임
대체 대상: -
pnpm
역할: 빠른 패키지 매니저
대체 대상: npm

iTerm2 설정 참고

iTerm2 설정은 com.googlecode.iterm2.plist 파일로 자동 복원됩니다. 직접 설정하고 싶은 경우 아래 항목을 참고하세요.

5-1. 폰트 설정

Preferences > Profiles > Text > Font에서 MesloLGS NF 폰트를 선택합니다. 크기는 13pt를 권장합니다. "Use ligatures" 옵션은 켜면 합자(ligature)가 적용됩니다.

5-2. 색상 테마

Preferences > Profiles > Colors에서 Solarized Dark 또는 원하는 테마를 선택합니다. "Minimum Contrast" 슬라이더를 조절하여 가독성을 높일 수 있습니다.

5-3. 키 매핑 (tmux 연동)

Preferences > Profiles > Keys에서 Option 키를 Esc+로 설정합니다. 이렇게 하면 tmux 복사 모드에서 Option+화살표로 스크롤할 수 있습니다.

Keys > General
항목: Left Option Key
값: Esc+
Keys > General
항목: Right Option Key
값: Esc+

5-4. tmux 통합 모드

Preferences > General > tmux에서 tmux 통합 모드를 설정합니다. tmux -CC 명령으로 연결하면 iTerm2가 tmux 세션을 네이티브 탭/창으로 표시합니다.

General > tmux
항목: When attaching, open unrecognized windows in
권장 값: Tabs in the attaching window
General > tmux
항목: Automatically bury the tmux client session
권장 값: 체크
General > tmux
항목: Use tmux profile rather than profile of the connecting session
권장 값: 체크

5-5. 알림 설정

notify.sh의 OSC 9 알림이 정상적으로 표시되려면 iTerm2 알림 설정을 확인해야 합니다.

Profiles > Terminal
항목: Notifications > Send Notifications
권장 값: 체크
Profiles > Terminal
항목: Filter Alerts
권장 값: 모두 활성화
macOS 시스템 설정
항목: 알림 > iTerm2
권장 값: 알림 허용, 배너 스타일

5-6. 스크롤백 버퍼

Preferences > Profiles > Terminal에서 스크롤백 라인 수를 설정합니다. Claude Code의 긴 출력을 보존하려면 충분히 큰 값을 설정하세요.

Profiles > Terminal
항목: Scrollback Lines
권장 값: 50000 이상 또는 Unlimited
Profiles > Terminal
항목: Save lines to scrollback when an app status bar is present
권장 값: 체크

5-7. 기타 권장 설정

Appearance
항목: Theme
권장 값: Minimal
이유: 상태 바 공간 절약
Appearance
항목: Tab bar location
권장 값: Top
이유: 패널과 구분 용이
Profiles > Window
항목: Columns / Rows
권장 값: 200 / 50
이유: 넓은 작업 영역 확보
Profiles > Session
항목: After a session ends
권장 값: No Action
이유: 세션 종료 후 탭 유지
Advanced
항목: Scroll wheel sends arrow keys when in alternate screen mode
권장 값: Yes
이유: less/vim 등에서 마우스 스크롤 지원

설치 후 할 일

ℹ️ 설치 후 체크리스트

스크립트 실행 후 아래 항목을 순서대로 확인하세요.

1

iTerm2 재시작

iTerm2를 완전히 종료(Cmd+Q) 후 다시 엽니다. plist 설정이 적용됩니다.

2

셸 설정 적용

source ~/.zshrc를 실행하거나 새 터미널 탭을 엽니다. Powerlevel10k 설정 마법사가 나타날 수 있습니다.

3

Claude Code 설치

npm i -g @anthropic-ai/claude-code로 Claude Code를 설치합니다. 이미 설치되어 있다면 건너뜁니다.

4

Claude Code 인증

claude 명령을 실행하고 Anthropic 계정으로 로그인합니다. API 키 또는 OAuth로 인증 가능합니다.

5

settings.json 확인

cat ~/.claude/settings.json | jq .로 설정이 올바르게 적용되었는지 확인합니다. 특히 OTEL_SERVICE_NAME을 실제 이름으로 변경하세요.

6

tmux 동작 확인

tmux new -s test로 세션을 만들고, tmux kill-session -t test로 정리합니다. Agent Teams 사용 시 tmux가 필수입니다.

7

알림 테스트

bash ~/.claude/notify.sh test를 실행하여 OSC 9 알림이 정상적으로 표시되는지 확인합니다.

8

CLAUDE.md 작성

프로젝트 루트에 CLAUDE.md 파일을 작성하여 프로젝트별 규칙과 컨텍스트를 정의합니다. 글로벌 설정은 ~/.claude/CLAUDE.md에 작성합니다.

문제 해결

Powerlevel10k 아이콘이 깨져 보임
원인: MesloLGS NF 폰트가 설치되지 않았거나 iTerm2에서 선택되지 않음
해결 방법: ls ~/Library/Fonts/MesloLGS*로 폰트 확인. iTerm2 > Preferences > Profiles > Text > Font에서 MesloLGS NF 선택
notify.sh 알림이 안 옴
원인: allow-passthrough가 꺼져 있거나 iTerm2 알림 비활성
해결 방법: .tmux.confset -g allow-passthrough on 확인. macOS 시스템 설정 > 알림 > iTerm2 허용 확인
settings.json 병합 실패
원인: jq가 설치되지 않음
해결 방법: brew install jq 실행 후 7단계 재시도. 또는 수동으로 JSON 편집
tmux 색상이 이상함
원인: 터미널이 256색을 지원하지 않음
해결 방법: iTerm2 사용 확인. echo $TERMxterm-256color인지 확인
Karabiner Caps Lock이 안 먹힘
원인: macOS 접근성 권한 미부여
해결 방법: 시스템 설정 > 개인정보 보호 및 보안 > 입력 모니터링에서 Karabiner 허용
brew bundle 실패
원인: Xcode Command Line Tools 미설치
해결 방법: xcode-select --install 실행 후 재시도
Oh My Zsh 설치 후 프롬프트 깨짐
원인: .zshrc가 Oh My Zsh 기본값으로 덮어씀
해결 방법: 스크립트의 8단계에서 복원된 .zshrc가 적용됨. source ~/.zshrc 실행
Agent Teams가 동작하지 않음
원인: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 미설정 또는 tmux 미설치
해결 방법: cat ~/.claude/settings.json | jq .env로 환경 변수 확인. which tmux로 tmux 설치 확인
statusline.sh에 정보가 안 나옴
원인: jq 미설치 또는 실행 권한 없음
해결 방법: chmod +x ~/.claude/statusline.sh 실행. which jq로 jq 설치 확인
iTerm2 plist 복원 후 설정이 안 바뀜
원인: iTerm2가 실행 중일 때 plist를 복사함
해결 방법: iTerm2를 완전히 종료(Cmd+Q) 후 다시 열기. 실행 중에는 메모리의 설정이 우선
💡 추가 도움이 필요하다면

위 해결 방법으로도 문제가 해결되지 않으면 ~/.claude/notify.log 파일을 확인하여 알림 관련 디버깅 정보를 참고하세요. 또한 claude --version으로 Claude Code 버전을 확인하고 최신 버전으로 업데이트해 보세요: npm update -g @anthropic-ai/claude-code