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단계로 구성되며, 각 단계에서 이미 설치된 항목은 자동으로 건너뜁니다 (멱등성 보장).
claude-code-setup폴더를 새 맥으로 복사 (AirDrop, USB 등)cd ~/Desktop/claude-code-setupchmod +x 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 설정을 홈 디렉토리에 복원합니다. 기존 파일은 타임스탬프 백업됩니다. | 기존 파일 백업 후 덮어쓰기 |
[1/8] /opt/homebrew) 경로를 ~/.zprofile에 등록합니다. [2/8] brew bundle 명령으로 Brewfile에 정의된 모든 CLI 도구, 앱, 폰트를 일괄 설치합니다. [3/8] --unattended 플래그로 셸 변경 프롬프트 없이 자동 설치됩니다. ~/.oh-my-zsh 디렉토리 존재 확인 [4/8] [5/8] ~/Library/Fonts/에 복사합니다. Powerlevel10k 테마에 필요합니다. [6/8] [7/8] ~/.claude/ 디렉토리에 notify.sh, statusline.sh, settings.json을 복사합니다. 기존 settings.json이 있으면 jq로 병합합니다. [8/8] set -e로 인해 어떤 단계에서든 오류 발생 시 즉시 중단됩니다.- 7단계의 settings.json 병합에는
jq가 필요합니다 (2단계 Brewfile에서 설치됨). - 설치 완료 후 반드시 iTerm2를 재시작하고
source ~/.zshrc를 실행해야 합니다.
settings.json - Claude Code 전역 설정
~/.claude/settings.json에 위치하는 Claude Code 전역 설정 파일입니다.
모델 선택, 환경 변수, 권한 관리, 훅, 플러그인 등 Claude Code의 모든 동작을 제어합니다.
{
"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-{이름}" | 텔레메트리에 표시될 서비스 식별 이름 |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS "1" CLAUDE_CODE_ENABLE_TELEMETRY "1" OTEL_*_EXPORTER "otlp" OTEL_EXPORTER_OTLP_PROTOCOL "grpc" OTEL_EXPORTER_OTLP_ENDPOINT "http://...:4317" OTEL_METRIC_EXPORT_INTERVAL "10000" OTEL_LOGS_EXPORT_INTERVAL "5000" 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, scpGit 위험 명령: git push, git reset --hard, git clean -f프로세스: pkill권한 변경: chmod, chown시스템 서비스: launchctl, crontab |
Bash(*) - 모든 Bash 명령, WebSearch - 웹 검색 rm -rf, killall, sudo, shutdown, reboot 등위험한 Git:
git push --force패키지 배포:
npm publish디스크 조작:
dd, mkfs, fdisk, diskutil erase/partitionDisk민감 파일 읽기:
.env, secrets/**, ~/.ssh/** rm네트워크:
curl, wget, ssh, scpGit 위험 명령:
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 실행 - 작업 종료 알림 전송 |
Notification notify.sh Asks 실행 - 사용자에게 알림 전송 PreToolUse AskUserQuestion 도구 사용 직전 notify.sh Asks 실행 - 사용자 입력이 필요할 때 알림 Stop notify.sh Stops 실행 - 작업 종료 알림 전송 statusLine
Claude Code 하단에 표시되는 상태 표시줄을 설정합니다. statusline.sh 스크립트가
모델명, 작업 디렉토리, Git 브랜치, 컨텍스트 사용률, 비용, 실행 시간을 실시간으로 표시합니다.
enabledPlugins (5개 공식 플러그인)
| 플러그인 | 설명 |
|---|---|
ralph-loop | Ralph Loop 패턴 지원 - 수렴할 때까지 반복 실행하는 에이전트 루프 |
context7 | Context7 통합 - 최신 라이브러리 문서를 자동으로 컨텍스트에 포함 |
github | GitHub 통합 - PR 생성, 이슈 관리, 코드 리뷰 기능 강화 |
superpowers | 고급 기능 확장 - 추가 도구와 향상된 에이전트 기능 제공 |
code-review | 코드 리뷰 자동화 - PR 변경 사항 분석 및 리뷰 코멘트 생성 |
ralph-loop context7 github superpowers code-review teammateMode
"tmux"로 설정하면 Agent Teams가 tmux 세션에서 각 에이전트를 별도 패널로 실행합니다.
각 에이전트의 작업 과정을 실시간으로 모니터링할 수 있어 디버깅과 협업에 유리합니다.
notify.sh - 스마트 알림 스크립트
Claude Code가 사용자의 입력을 기다리거나 작업을 완료했을 때 실행되는 알림 스크립트입니다. 핵심 기능은 사용자가 이미 해당 탭을 보고 있으면 알림을 건너뛰는 스마트 감지 로직입니다.
#!/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가 이를 감지하여 시스템 알림 표시 |
TYPE=$(echo "$1" | tr ...) Asks 또는 Stops)를 대문자로 변환하여 알림 유형 식별 osascript -e 'tell application ...' iTerm2) client_window vs my_window front_app = "iTerm2" && client_window = my_window printf '\ePtmux;...' 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 브랜치, 컨텍스트 사용률, 비용, 실행 시간을 표시합니다.
#!/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 | 총 실행 시간을 분:초 형식으로 표시 |
.model.display_name .workspace.current_dir git branch --show-current .context_window.used_percentage .cost.total_cost_usd .cost.total_duration_ms 컨텍스트 사용률 색상 코드
| 사용률 | 색상 | 의미 |
|---|---|---|
| 0% ~ 69% | 초록색 | 여유 있음 - 정상 사용 범위 |
| 70% ~ 89% | 노란색 | 주의 - 컨텍스트가 많이 채워짐. 불필요한 정보 정리 권장 |
| 90% ~ 100% | 빨간색 | 위험 - 컨텍스트 초과 임박. /compact 명령으로 압축 필요 |
/compact 명령으로 압축 필요 상태 표시줄은 2줄로 구성됩니다:
[Claude 4 Sonnet] 📁 my-project | 🌿 feature/auth
████████░░ 78% | $0.42 | ⏱️ 3m 24s
.tmux.conf - tmux 설정
Claude Code와 Agent Teams 운영에 최적화된 tmux 설정 파일입니다. 256색 지원, 알림 통과, vi 모드, 마우스 지원 등을 포함합니다.
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" 설정 항목별 설명
| 설정 | 값 | 설명 | Claude Code 관련 |
|---|---|---|---|
default-terminal | screen-256color | 기본 터미널 유형을 256색으로 설정. statusline.sh의 ANSI 색상 코드가 정상 표시됩니다. | 상태 표시줄 색상 |
terminal-overrides | xterm-256color:Tc | True Color(24비트) 지원 추가. 더 풍부한 색상 표현이 가능합니다. | 코드 하이라이팅 |
history-limit | 50000 | 스크롤백 버퍼를 50,000줄로 설정. 긴 Claude Code 출력을 놓치지 않고 확인할 수 있습니다. | 긴 출력 보존 |
visual-bell | on | 비프음 대신 시각적 깜빡임으로 벨 이벤트를 표시합니다. | 알림 시각화 |
bell-action | any | 모든 윈도우의 벨 이벤트를 감지합니다. notify.sh의 OSC 9 알림과 연동됩니다. | 알림 감지 |
allow-passthrough | on | 이스케이프 시퀀스가 tmux를 통과하도록 허용합니다. notify.sh의 OSC 9 알림에 필수적인 설정입니다. | 알림 전송 필수 |
activity-action | none | 윈도우 활동 시 자동 동작을 비활성화. Claude 작업 중 불필요한 윈도우 전환을 방지합니다. | 작업 방해 방지 |
silence-action | none | 무활동 모니터링을 비활성화. Claude가 생각 중일 때 오탐 알림을 방지합니다. | 오탐 방지 |
mouse | on | 마우스로 패널 선택, 스크롤, 리사이즈가 가능합니다. Agent Teams 모니터링 시 편리합니다. | 패널 전환 편의 |
mode-keys vi | vi | 복사 모드에서 vi 키 바인딩 사용. hjkl로 이동, v로 선택합니다. | 키보드 탐색 |
copy-mode-vi 바인딩 | M-Up/Down 등 | Option+화살표, PageUp/Down으로 스크롤. Claude 출력을 빠르게 탐색할 수 있습니다. | 출력 탐색 |
copy-pipe-and-cancel | pbcopy | y 키로 선택 영역을 macOS 클립보드에 복사합니다. Claude 출력을 쉽게 복사할 수 있습니다. | 출력 복사 |
default-terminal screen-256color terminal-overrides xterm-256color:Tc history-limit 50000 visual-bell on bell-action any allow-passthrough on activity-action none silence-action none mouse on mode-keys vi vi hjkl로 이동, v로 선택합니다. copy-mode-vi 바인딩 copy-pipe-and-cancel pbcopy y 키로 선택 영역을 macOS 클립보드에 복사합니다. Claude 출력을 쉽게 복사할 수 있습니다. allow-passthrough on이 없으면 notify.sh의 OSC 9 알림이 tmux에서 차단됩니다.
이 설정은 Claude Code의 스마트 알림 시스템이 정상적으로 동작하기 위한 필수 설정입니다.
보안상 이유로 기본값은 off이므로 반드시 명시적으로 켜야 합니다.
Brewfile - Homebrew 패키지 목록
brew bundle 명령으로 일괄 설치되는 패키지 목록입니다.
CLI 도구, 앱(Cask), 폰트를 포함합니다.
# ============================================
# 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 권장 폰트 | 분류 | 패키지 | Claude Code 관련성 |
|---|---|---|
| 필수 CLI | git, jq, tmux, gh | Claude Code 동작, settings.json 병합, Agent Teams, GitHub 연동에 각각 필수 |
| 검색/탐색 | ripgrep, fzf, fd | Claude Code의 Grep 도구가 내부적으로 ripgrep 사용. fzf/fd는 파일 탐색 효율 향상 |
| 뷰어 | bat, eza, tree | 코드 미리보기, 디렉토리 탐색 시 구문 강조와 아이콘 표시 |
| 런타임 | node, pnpm | Claude Code는 npm으로 설치 (npm i -g @anthropic-ai/claude-code) |
| 앱 | iTerm2, Karabiner, VS Code, Raycast | iTerm2는 OSC 9 알림 지원, Karabiner는 키 매핑, VS Code는 Claude Code 확장 지원 |
| 폰트 | font-meslo-lg-nerd-font | Powerlevel10k 테마의 아이콘/글리프 표시에 필요 |
git, jq, tmux, gh ripgrep, fzf, fd bat, eza, tree node, pnpm npm i -g @anthropic-ai/claude-code) font-meslo-lg-nerd-font karabiner.json - 키 매핑 설정
Karabiner-Elements의 키 매핑 설정입니다. 한영 전환, Caps Lock 활용 등 macOS 키보드 커스터마이징을 담당합니다.
{
"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 복사 모드 종료에도 사용 |
right_command F18 right_option F19 Caps Lock (길게) Caps Lock (짧게) Escape 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 복사 |
cask "iterm2") curl) brew "tmux") 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 |
git jq gh tmux fzf ripgrep grep bat cat eza ls fd find tldr man tree wget curl htop top node 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+ |
Esc+ 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 | 체크 |
50000 이상 또는 Unlimited 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 등에서 마우스 스크롤 지원 |
설치 후 할 일
스크립트 실행 후 아래 항목을 순서대로 확인하세요.
iTerm2 재시작
iTerm2를 완전히 종료(Cmd+Q) 후 다시 엽니다. plist 설정이 적용됩니다.
셸 설정 적용
source ~/.zshrc를 실행하거나 새 터미널 탭을 엽니다. Powerlevel10k 설정 마법사가 나타날 수 있습니다.
Claude Code 설치
npm i -g @anthropic-ai/claude-code로 Claude Code를 설치합니다. 이미 설치되어 있다면 건너뜁니다.
Claude Code 인증
claude 명령을 실행하고 Anthropic 계정으로 로그인합니다. API 키 또는 OAuth로 인증 가능합니다.
settings.json 확인
cat ~/.claude/settings.json | jq .로 설정이 올바르게 적용되었는지 확인합니다. 특히 OTEL_SERVICE_NAME을 실제 이름으로 변경하세요.
tmux 동작 확인
tmux new -s test로 세션을 만들고, tmux kill-session -t test로 정리합니다. Agent Teams 사용 시 tmux가 필수입니다.
알림 테스트
bash ~/.claude/notify.sh test를 실행하여 OSC 9 알림이 정상적으로 표시되는지 확인합니다.
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.conf에 set -g allow-passthrough on 확인. macOS 시스템 설정 > 알림 > iTerm2 허용 확인 |
| settings.json 병합 실패 | jq가 설치되지 않음 | brew install jq 실행 후 7단계 재시도. 또는 수동으로 JSON 편집 |
| tmux 색상이 이상함 | 터미널이 256색을 지원하지 않음 | iTerm2 사용 확인. echo $TERM이 xterm-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) 후 다시 열기. 실행 중에는 메모리의 설정이 우선 |
ls ~/Library/Fonts/MesloLGS*로 폰트 확인. iTerm2 > Preferences > Profiles > Text > Font에서 MesloLGS NF 선택 allow-passthrough가 꺼져 있거나 iTerm2 알림 비활성 .tmux.conf에 set -g allow-passthrough on 확인. macOS 시스템 설정 > 알림 > iTerm2 허용 확인 jq가 설치되지 않음 brew install jq 실행 후 7단계 재시도. 또는 수동으로 JSON 편집 echo $TERM이 xterm-256color인지 확인 brew bundle 실패 xcode-select --install 실행 후 재시도 source ~/.zshrc 실행 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 미설정 또는 tmux 미설치 cat ~/.claude/settings.json | jq .env로 환경 변수 확인. which tmux로 tmux 설치 확인 jq 미설치 또는 실행 권한 없음 chmod +x ~/.claude/statusline.sh 실행. which jq로 jq 설치 확인 위 해결 방법으로도 문제가 해결되지 않으면 ~/.claude/notify.log 파일을 확인하여
알림 관련 디버깅 정보를 참고하세요. 또한 claude --version으로 Claude Code 버전을 확인하고
최신 버전으로 업데이트해 보세요: npm update -g @anthropic-ai/claude-code