[Claude SwiftBar] 메뉴바에서 Claude Code 상태 추적하기

 

안녕하세요! 재아군의 관찰인생입니다.

 

Claude Code를 오래 켜두고 작업하다 보면 한 가지 아쉬움이 생깁니다.

지금 어떤 모델을 쓰는지, 컨텍스트를 얼마나 썼는지, 5시간 제한이 얼마나 남았는지, 백그라운드 세션이 떠 있는지 계속 확인하고 싶어집니다.

 

터미널 안에서는 Claude Code의 status line으로 볼 수 있지만, 여러 프로젝트를 오가거나 터미널을 가려두면 시야에서 사라집니다.

이때 macOS 메뉴바 도구인 SwiftBar를 붙이면 Claude Code 상태를 메뉴바에 올려둘 수 있습니다.

 

먼저 중요한 점부터 분명히 하겠습니다.

이 글에서 다루는 Claude Code SwiftBar 플러그인은 Anthropic이나 SwiftBar가 공식 배포한 단일 제품명이 아닙니다.

공식 문서가 제공하는 Claude Code status line/CLI 데이터와 SwiftBar Plugin API를 조합해 직접 만드는 실전 패턴입니다.

 

결론부터 말하면, Claude Code의 status line이 세션 JSON을 파일로 남기고 SwiftBar가 그 파일을 주기적으로 읽으면 메뉴바에서 모델, 컨텍스트, 비용, rate limit, 백그라운드 세션 상태를 한눈에 볼 수 있습니다.

 

 

---

 

 

 

Claude Code SwiftBar 플러그인이란 무엇인가요?

 

Claude Code SwiftBar 플러그인은 Claude Code의 세션 상태를 macOS 메뉴바에 표시하는 사용자 제작 자동화 패턴입니다.

Claude Code가 status line 스크립트에 전달하는 JSON 데이터를 캐시 파일로 저장하고, SwiftBar 플러그인이 그 파일을 읽어 메뉴바와 드롭다운으로 보여줍니다.

 

공식 플러그인인가요?

 

현재 확인한 공식 문서 기준으로 Anthropic이나 SwiftBar가 “Claude Code SwiftBar 플러그인”이라는 완성품을 제공한다고 보기는 어렵습니다.

대신 Claude Code는 status line, CLI, hooks, plugins 같은 확장 지점을 제공하고, SwiftBar는 실행 가능한 스크립트의 stdout을 메뉴바로 바꾸는 Plugin API를 제공합니다.

 

왜 SwiftBar와 붙이면 좋은가요?

 

Claude Code 상태는 작업 중에는 중요하지만, 터미널 안에만 있으면 놓치기 쉽습니다.

SwiftBar에 올려두면 컨텍스트 사용률, 비용 추정치, rate limit, 현재 프로젝트 같은 운영 신호를 macOS 메뉴바에서 계속 볼 수 있습니다.

 

지금 바로 만들어도 되나요?

 

네, 개인 생산성 도구로는 바로 만들어볼 만합니다.

다만 토큰, 인증 정보, transcript 경로 같은 민감한 데이터를 메뉴바나 로그에 그대로 노출하지 않도록 필드를 선별해야 합니다.

 

 

---

 

이 글의 핵심 5가지

 

• Claude Code는 status line 스크립트에 모델, 작업 디렉터리, 비용, 컨텍스트, rate limit, 세션 ID 같은 JSON 데이터를 stdin으로 전달합니다.
• SwiftBar는 Plugin Folder 안의 실행 가능한 스크립트를 주기적으로 실행하고, stdout을 Header와 Body로 나눠 메뉴바와 드롭다운에 표시합니다.
• 두 도구를 연결하는 가장 안전한 방식은 Claude Code status line이 스냅샷 JSON을 캐시에 저장하고 SwiftBar가 그 캐시를 읽는 구조입니다.
• SwiftBar 플러그인에서는 claude auth status, claude --version, claude agents --json, claude daemon status 같은 CLI 명령도 보조 신호로 활용할 수 있습니다.
• 팀에서 공유하려면 비밀값을 출력하지 않는 필드 정책, refresh interval, 오류 처리, .swiftbarignore 같은 운영 규칙이 필요합니다.

 

목차

 

1. Claude Code SwiftBar 플러그인은 무엇인가요?
2. Claude Code에서 어떤 데이터를 가져올 수 있나요?
3. SwiftBar는 이 데이터를 어떻게 메뉴바로 바꾸나요?
4. 가장 안전한 아키텍처는 무엇인가요?
5. Claude Code status line 브릿지 만들기
6. SwiftBar 플러그인 스크립트 만들기
7. 실무 활용 패턴 5가지
8. 운영 안정성과 보안 체크리스트
9. 다른 방식과 비교하면 언제 SwiftBar가 맞나요?
10. AEO 핵심 답변 모음
11. 자주 묻는 질문

 

용어정리

 

용어	쉬운 설명
Claude Code	Anthropic의 에이전틱 코딩 도구입니다. 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하며 개발 작업을 자동화합니다.
Status line	Claude Code 하단에 표시되는 사용자 정의 상태 표시줄입니다. 스크립트가 JSON을 읽고 문자열을 출력합니다.
SwiftBar	macOS 메뉴바 커스터마이징 도구입니다. 실행 가능한 스크립트 출력으로 메뉴바 항목을 만듭니다.
Plugin Folder	SwiftBar가 플러그인 스크립트를 읽는 폴더입니다. 파일명에 갱신 주기를 넣습니다.
Header	SwiftBar 출력에서 첫 번째 구분선 전까지입니다. 메뉴바에 직접 보입니다.
Body	SwiftBar 출력에서 구분선 이후입니다. 메뉴를 클릭했을 때 드롭다운으로 보입니다.
Rate limit	Claude Code 사용량 제한입니다. Claude Code status line JSON에는 5시간 및 7일 제한 사용률이 포함될 수 있습니다.

 

 

---

 

1. Claude Code SwiftBar 플러그인은 무엇인가요?

 

Claude Code SwiftBar 플러그인은 Claude Code 작업 상태를 macOS 메뉴바에서 계속 확인하기 위한 사용자 제작 메뉴바 플러그인입니다.

정확히는 하나의 공식 제품이 아니라, 두 도구의 확장 지점을 연결하는 작은 스크립트 묶음입니다.

 

Claude Code 공식 문서는 Claude Code를 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며 개발 도구와 통합되는 에이전틱 코딩 도구라고 설명합니다.

또한 터미널, IDE, 데스크톱 앱, 브라우저에서 사용할 수 있다고 안내합니다.

 

SwiftBar 공식 README는 SwiftBar 플러그인을 “원하는 언어로 작성한 실행 가능한 스크립트”라고 설명합니다.

스크립트는 정해진 형식으로 stdout을 출력하고, 오류는 stderr로 보내야 합니다.

 

두 설명을 합치면 구조가 명확해집니다.

 

Claude Code는 “상태를 스크립트에 전달할 수 있는 도구”이고, SwiftBar는 “스크립트 출력을 메뉴바로 바꾸는 도구”입니다.

 

즉, Claude Code의 상태 데이터를 SwiftBar가 읽을 수 있는 중간 파일로 남기면 메뉴바 플러그인이 됩니다.

복잡한 앱 개발 없이 Bash, jq, JSON 파일만으로도 충분히 시작할 수 있습니다.

 

관점	Claude Code	SwiftBar	연결 지점
기본 역할	코딩 에이전트 실행	macOS 메뉴바 표시	개발 상태를 메뉴바로 노출
확장 방식	status line, CLI, hooks, plugins	실행 가능한 스크립트	shell script
데이터 흐름	JSON을 stdin으로 전달	stdout을 메뉴로 표시	캐시 파일
좋은 사용처	모델, 컨텍스트, 비용, 세션 상태	상시 표시, 클릭 액션	개발자 대시보드

 

이 글에서는 “Claude Code 상태를 SwiftBar에 표시하는 플러그인”을 만드는 방법을 다룹니다.

완성품을 내려받는 글이 아니라, 공식 문서 기반으로 스스로 만들 수 있는 구현 가이드입니다.

 

 

---

 

2. Claude Code에서 어떤 데이터를 가져올 수 있나요?

 

Claude Code에서 가장 좋은 데이터 소스는 status line JSON입니다.

공식 status line 문서에 따르면 Claude Code는 status line 스크립트에 JSON 세션 데이터를 stdin으로 전달합니다.

스크립트는 이 JSON을 읽고 원하는 텍스트를 stdout으로 출력합니다.

 

공식 문서가 제공하는 대표 필드는 다음과 같습니다.

 

데이터	필드 예시	메뉴바에서의 활용
모델	model.display_name	현재 Opus, Sonnet 등 표시
작업 디렉터리	workspace.current_dir	어느 프로젝트에서 작업 중인지 표시
비용	cost.total_cost_usd	세션 비용 추정치 표시
변경량	cost.total_lines_added, cost.total_lines_removed	작업 규모 감지
컨텍스트 사용률	context_window.used_percentage	compact 시점 판단
남은 컨텍스트	context_window.remaining_percentage	여유 공간 표시
Rate limit	rate_limits.five_hour.used_percentage	5시간 제한 사용률 표시
세션	session_id, session_name	세션 구분
버전	version	Claude Code 버전 표시
PR	pr.number, pr.url, pr.review_state	현재 PR 상태 표시

 

여기서 중요한 제약도 있습니다.

공식 문서에 따르면 일부 필드는 없을 수 있습니다.

예를 들어 rate_limits는 Claude.ai 구독 사용자에게만 첫 API 응답 이후 나타날 수 있고, pr은 현재 브랜치에 열린 PR이 있을 때만 나타납니다.

 

따라서 플러그인은 “필드가 항상 있다”는 전제로 만들면 안 됩니다.

항상 fallback 값을 둬야 합니다.

 

# Claude Code status line JSON에서 안전하게 값을 읽는 패턴
MODEL=$(echo "$input" | jq -r '.model.display_name // "unknown"')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
LIMIT=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
PROJECT=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""')

 

Claude Code CLI도 보조 데이터 소스로 쓸 수 있습니다.

공식 CLI reference 기준으로 claude auth status는 인증 상태를 보여주며, --text 옵션으로 사람이 읽기 쉬운 출력도 가능합니다.

claude agents --json은 백그라운드 세션을 스크립트에서 다룰 수 있게 해주고, claude daemon status는 background-session supervisor 상태를 진단할 수 있습니다.

 

CLI 명령	쓸 수 있는 곳	메뉴바 활용
claude --version	거의 모든 환경	설치 여부와 버전 표시
claude auth status --text	로그인 확인	로그인 상태 경고
claude agents --json	백그라운드 세션 확인	실행 중 에이전트 수 표시
claude daemon status	supervisor 진단	백그라운드 세션 인프라 상태 표시
claude logs <id>	세션 로그 확인	드롭다운 액션으로 연결
claude attach <id>	세션 붙기	클릭 액션 후보

 

다만 CLI 명령을 SwiftBar가 너무 자주 실행하면 느려질 수 있습니다.

상태 line JSON은 빠르게 캐시하고, 무거운 CLI 명령은 30초에서 5분 단위로 천천히 확인하는 편이 좋습니다.

 

---

 

3. SwiftBar는 이 데이터를 어떻게 메뉴바로 바꾸나요?

 

SwiftBar는 단순한 규칙으로 움직입니다.

Plugin Folder 안에 실행 가능한 스크립트가 있으면 SwiftBar가 그 파일을 실행하고, stdout을 읽어 메뉴바를 구성합니다.

 

Homebrew cask 기준 설치 명령은 다음과 같습니다.

 

brew install --cask swiftbar

 

Homebrew Formulae 페이지 기준으로 SwiftBar의 현재 cask 정보는 2.0.1,536이고, 요구사항은 macOS 11 이상입니다.

설치 후 처음 실행하면 Plugin Folder를 지정합니다.

 

SwiftBar의 파일명은 보통 다음 형태를 씁니다.

 

{name}.{refresh interval}.{extension}

 

예를 들어 Claude Code 상태를 30초마다 갱신하려면 이런 이름을 쓸 수 있습니다.

 

claude-code.30s.sh

 

SwiftBar 출력은 첫 번째 구분선 전후로 나뉩니다.

첫 번째 --- 이전은 메뉴바에 보이는 Header입니다.

첫 번째 --- 이후는 메뉴를 클릭했을 때 보이는 Body입니다.

 

#!/bin/bash

echo "Claude 18% | sfimage=terminal color=green"
echo "---"
echo "Model: Sonnet"
echo "Project: blog-writer"
echo "Context: 18%"

 

SwiftBar의 각 줄은 “항목 제목 + 파라미터” 형식입니다.

파라미터에는 색상, SF Symbol, badge, tooltip, href, bash, refresh 같은 기능이 들어갑니다.

 

파라미터	역할	Claude Code 플러그인에서의 예
color	텍스트 색상	컨텍스트 80% 이상이면 빨간색
sfimage	SF Symbol 아이콘	터미널, 경고, 체크 아이콘
tooltip	마우스 오버 설명	전체 세션 ID 또는 프로젝트 경로
badge	오른쪽 badge	남은 제한 또는 세션 수
refresh	클릭 시 재실행	수동 새로고침 메뉴
href	URL 열기	PR URL 또는 문서 링크
bash	스크립트 실행	Claude attach 또는 로그 열기
terminal	터미널 실행 여부	background 실행 제어

 

SwiftBar는 플러그인 실행 시 SWIFTBAR_PLUGIN_CACHE_PATH, SWIFTBAR_PLUGIN_DATA_PATH, SWIFTBAR_PLUGINS_PATH 같은 환경 변수도 제공합니다.

캐시 파일을 어디에 둘지 정할 때 이 변수를 활용하면 플러그인별 데이터가 깔끔하게 분리됩니다.

 

---

 

4. 가장 안전한 아키텍처는 무엇인가요?

 

가장 추천하는 구조는 Claude Code status line 브릿지 + SwiftBar 리더입니다.

Claude Code가 직접 SwiftBar를 실행하게 만들거나, SwiftBar가 매번 Claude Code 세션을 강제로 건드리게 만들 필요가 없습니다.

 

흐름은 다음과 같습니다.

 

Claude Code session
  -> statusLine command receives JSON on stdin
  -> bridge script writes snapshot.json
  -> SwiftBar plugin reads snapshot.json every 30s
  -> macOS menu bar displays model, context, cost, limit

 

이 구조가 좋은 이유는 세 가지입니다.

 

첫째, Claude Code가 제공하는 공식 status line 데이터 흐름을 그대로 씁니다.

둘째, SwiftBar는 파일만 읽기 때문에 Claude Code 세션을 방해하지 않습니다.

셋째, SwiftBar refresh interval과 Claude Code status line 업데이트 주기를 분리할 수 있습니다.

 

구조	장점	단점	추천도
SwiftBar가 claude 명령만 직접 실행	구현이 단순함	세션 내부 컨텍스트 데이터 접근이 약함	보조용
status line이 JSON을 캐시하고 SwiftBar가 읽음	세션 데이터가 풍부하고 안정적	파일 브릿지 설정 필요	가장 추천
Claude Code hook이 SwiftBar 캐시를 갱신	이벤트별 세밀한 제어 가능	hooks 설정이 복잡함	팀 운영용
별도 daemon이 Claude 상태를 수집	확장성 좋음	과한 구조가 되기 쉬움	대규모 팀용

 

이 글에서는 두 번째 방식을 기준으로 설명합니다.

개인용으로도 충분히 단순하고, 팀에서 확장하기에도 가장 균형이 좋습니다.

 

---

 

5. Claude Code status line 브릿지 만들기

 

먼저 Claude Code가 전달하는 status line JSON을 파일로 저장하는 브릿지 스크립트를 만듭니다.

공식 문서는 ~/.claude/settings.json에 statusLine 필드를 추가하고, type을 command로 지정하는 방식을 안내합니다.

 

아래 스크립트는 Claude Code에서 받은 JSON을 ~/.cache/claude-swiftbar/status.json에 저장한 뒤, Claude Code 터미널 안에도 짧은 status line을 출력합니다.

 

#!/bin/bash
# ~/.claude/statusline-swiftbar-bridge.sh

set -u

input=$(cat)
cache_dir="$HOME/.cache/claude-swiftbar"
snapshot="$cache_dir/status.json"

mkdir -p "$cache_dir"
printf '%s' "$input" > "$snapshot"

model=$(echo "$input" | jq -r '.model.display_name // "Claude"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""')
project=$(basename "$dir")
context=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')

echo "[$model] ${project:-project} | ${context}% context | ${cost}"

 

실행 권한을 줍니다.

 

chmod +x ~/.claude/statusline-swiftbar-bridge.sh

 

이제 ~/.claude/settings.json에 statusLine 설정을 추가합니다.

 

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline-swiftbar-bridge.sh",
    "refreshInterval": 5
  }
}

 

refreshInterval은 이벤트 기반 업데이트 외에 N초마다 명령을 다시 실행하도록 하는 옵션입니다.

공식 문서 기준 최소값은 1초입니다.

하지만 너무 짧게 잡으면 불필요한 파일 쓰기가 많아지므로, 개인용은 5초에서 10초 정도가 무난합니다.

 

핵심은 status line 스크립트가 Claude Code 안에서 보이는 문자열만 출력하는 것이 아니라, SwiftBar가 읽을 수 있는 JSON 스냅샷도 남긴다는 점입니다.

 

브릿지 파일에는 민감한 데이터를 그대로 저장할 수 있습니다.

특히 transcript path, session id, repo owner, PR URL 같은 정보는 팀 환경에서 민감할 수 있습니다.

필요하면 저장 전에 필드를 줄인 sanitized JSON만 남기는 방식이 더 안전합니다.

 

#!/bin/bash
# 민감 필드를 줄인 버전

input=$(cat)
cache_dir="$HOME/.cache/claude-swiftbar"
mkdir -p "$cache_dir"

echo "$input" | jq '{
  model: .model.display_name,
  project: (.workspace.current_dir // .cwd),
  version: .version,
  cost: .cost,
  context_window: .context_window,
  rate_limits: .rate_limits,
  pr: .pr,
  updated_at: now
}' > "$cache_dir/status.json"

model=$(echo "$input" | jq -r '.model.display_name // "Claude"')
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$model] ${pct}% context"

 

개인 장비라면 원본 저장도 편하지만, 블로그 독자에게 권장할 기본값은 sanitized JSON입니다.

나중에 SwiftBar 스크립트를 공유하거나 GitHub에 올릴 때 실수 위험이 줄어듭니다.

 

---

 

6. SwiftBar 플러그인 스크립트 만들기

 

이제 SwiftBar Plugin Folder에 스크립트를 만듭니다.

폴더는 SwiftBar 첫 실행 시 지정한 위치를 쓰면 됩니다.

예시는 ~/SwiftBarPlugins를 기준으로 하겠습니다.

 

mkdir -p ~/SwiftBarPlugins
touch ~/SwiftBarPlugins/claude-code.30s.sh
chmod +x ~/SwiftBarPlugins/claude-code.30s.sh

 

가장 작은 버전은 캐시 파일을 읽고 메뉴바에 컨텍스트 사용률을 표시하는 스크립트입니다.

 

#!/bin/bash
# ~/SwiftBarPlugins/claude-code.30s.sh

snapshot="$HOME/.cache/claude-swiftbar/status.json"

if ! command -v jq >/dev/null 2>&1; then
  echo "Claude: jq 없음 | color=red sfimage=exclamationmark.triangle"
  echo "---"
  echo "jq를 설치하세요 | href=https://jqlang.github.io/jq/"
  exit 0
fi

if [ ! -f "$snapshot" ]; then
  echo "Claude: 대기 | color=gray sfimage=terminal"
  echo "---"
  echo "Claude Code 세션을 열고 status line 브릿지를 먼저 실행하세요."
  echo "설정 파일: ~/.claude/settings.json"
  exit 0
fi

model=$(jq -r '.model // "Claude"' "$snapshot")
project=$(jq -r '.project // ""' "$snapshot")
pct=$(jq -r '.context_window.used_percentage // 0' "$snapshot" | cut -d. -f1)
remain=$(jq -r '.context_window.remaining_percentage // 0' "$snapshot" | cut -d. -f1)
cost=$(jq -r '.cost.total_cost_usd // 0' "$snapshot")
limit=$(jq -r '.rate_limits.five_hour.used_percentage // empty' "$snapshot")

color="green"
if [ "$pct" -ge 80 ]; then
  color="red"
elif [ "$pct" -ge 60 ]; then
  color="orange"
fi

echo "Claude ${pct}% | color=$color sfimage=terminal badge=${model}"
echo "---"
echo "Project: ${project:-unknown}"
echo "Model: $model"
echo "Context used: ${pct}%"
echo "Context remaining: ${remain}%"
echo "Estimated cost: ${cost}"

if [ -n "$limit" ]; then
  echo "5h rate limit used: ${limit}%"
fi

echo "---"
echo "Refresh | refresh=true"
echo "Open Claude Docs | href=https://code.claude.com/docs/en/statusline"

 

이 정도만으로도 메뉴바에서 현재 세션 상태를 볼 수 있습니다.

컨텍스트가 60%를 넘으면 주황색, 80%를 넘으면 빨간색으로 바뀌므로 /compact 시점을 판단하기 쉽습니다.

 

다음 단계는 Claude Code CLI를 보조 신호로 붙이는 것입니다.

예를 들어 설치 여부, 로그인 상태, background agent 수를 드롭다운에 추가할 수 있습니다.

 

# Claude Code CLI 보조 상태
if command -v claude >/dev/null 2>&1; then
  version=$(claude --version 2>/dev/null | head -n 1)
  echo "CLI: ${version:-installed}"

  auth=$(claude auth status --text 2>/dev/null | head -n 1)
  echo "Auth: ${auth:-unknown}"

  agents_json=$(claude agents --json 2>/dev/null)
  if [ -n "$agents_json" ]; then
    count=$(echo "$agents_json" | jq 'length' 2>/dev/null)
    echo "Background agents: ${count:-0}"
  fi
else
  echo "Claude CLI not found | color=red"
fi

 

CLI 명령은 status line JSON 읽기보다 느릴 수 있습니다.

그래서 전체 플러그인을 10초마다 실행하기보다 30초나 1분마다 실행하는 것이 좋습니다.

더 정교하게 만들려면 SwiftBar의 캐시 경로에 CLI 결과를 따로 저장하고, 일정 시간이 지났을 때만 갱신하는 방식도 가능합니다.

 

---