[SwiftBar] macOS 메뉴바 자동화 입문부터 활용법까지

 

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

 

맥을 쓰다 보면 "이 정보를 메뉴바에 항상 띄워두면 편할 텐데"라는 생각, 한 번쯤 해보셨을 겁니다.

배포 상태, Git 브랜치, 디스크 용량, API 헬스체크 같은 것들 말이죠.

이걸 셸 스크립트 한 장으로 메뉴바에 올려주는 도구가 바로 SwiftBar입니다.

오늘은 SwiftBar를 설치부터 플러그인 작성, 운영, 디버깅까지 현업 개발자 관점에서 끝까지 따라갈 수 있게 정리해 보겠습니다.

 

 

 

이 글의 핵심 5가지

 

1. SwiftBar는 셸 스크립트의 표준 출력(stdout)을 그대로 macOS 메뉴바와 드롭다운으로 바꿔주는 메뉴바 커스터마이징 도구입니다.
2. 설치는 Homebrew cask 기준 brew install --cask swiftbar이며, 요구 사양은 macOS 11 이상입니다. (README는 brew install swiftbar, Catalina 10.15 이상으로 표기 — 본 글은 cask 기준을 우선합니다.)
3. 플러그인은 {name}.{time}.{ext} 형식의 실행 가능한 파일이며, 파일명 안의 time이 자동 갱신 주기를 결정합니다.
4. 출력 라인은 <제목> | 파라미터 문법을 따르고, color·sfimage·href·bash·refresh 같은 파라미터로 표현력과 액션을 더할 수 있습니다.
5. BitBar/xbar 플러그인 API를 그대로 채택했기 때문에 기존 BitBar/xbar 플러그인을 거의 그대로 실행할 수 있습니다.

 

 

 

목차

 

1. SwiftBar란 무엇인가?
2. 설치와 첫 설정
3. 플러그인 파일명과 실행 모델
4. 첫 번째 SwiftBar 플러그인 만들기
5. 실무 활용 패턴 5가지
6. 메뉴 표현력과 액션 파라미터
7. 운영 안정성과 디버깅
8. BitBar/xbar와 비교하고 언제 선택할까?
9. 팀에서 쓰는 SwiftBar 운영 전략
10. FAQ

 

 

 

 

용어정리

 

용어	의미
Plugin Folder	SwiftBar가 플러그인 파일을 읽어들이는 폴더. 첫 실행 시 지정합니다.
Plugin(플러그인)	메뉴바에 표시할 텍스트를 stdout으로 출력하는 실행 가능한 스크립트 파일
Header	첫 번째 --- 이전의 출력. 메뉴바에 표시되는 부분
Body	--- 이후의 출력. 클릭 시 펼쳐지는 드롭다운 메뉴 내용
refresh interval	플러그인을 자동으로 다시 실행하는 주기. 파일명에 들어갑니다.
stdout / stderr	표준 출력(메뉴 구성용) / 표준 에러(에러 표시용)
파라미터	출력 라인 뒤 | 다음에 붙이는 표현/동작 옵션 (color, href 등)
BitBar / xbar	SwiftBar가 호환하는 선행 메뉴바 도구. 플러그인 API가 동일합니다.

 

 

---

 

 

 

1. SwiftBar란 무엇인가?

 

SwiftBar는 공식 사이트(swiftbar.app)의 표현을 그대로 빌리면 다음과 같습니다.

 

"Powerful macOS menu bar customization tool." — swiftbar.app

 

즉, macOS 메뉴바를 커스터마이징하는 도구입니다.

Homebrew cask 페이지에서도 설명은 동일한 맥락으로 "Menu bar customization tool"이라고 적혀 있습니다.

 

 

 

 

 

어떤 문제를 해결하나요?

 

개발자에게 메뉴바는 "항상 시야에 있는 작은 대시보드"입니다.

SwiftBar의 핵심 사용 흐름은 README가 세 단계로 요약합니다.

 

shell script 작성 → SwiftBar에 추가 → 끝. — GitHub README

 

별도의 GUI 앱을 만들 필요 없이, 이미 익숙한 셸 스크립트의 stdout을 메뉴바로 끌어올린다는 점이 본질입니다.

스크립트가 출력한 텍스트가 그대로 메뉴바 항목이 되고, 클릭하면 드롭다운으로 펼쳐집니다.

 

 

 

 

Homebrew cask 정보 / 버전 / 요구사항

 

Homebrew cask 페이지(2026-06-19 확인 기준)의 정보를 정리하면 다음과 같습니다.

 

항목	값 (Homebrew cask 기준)
이름	SwiftBar
설명	Menu bar customization tool
설치 명령	brew install --cask swiftbar
현재 버전	2.0.1,536
요구 사양	macOS >= 11
라이선스	MIT (README 기준)

 

버전 표기는 출처에 따라 형태가 다릅니다.

 

구분	버전 표기	비고
Homebrew cask 기준	2.0.1,536	cask 페이지의 현재 버전 필드
GitHub README 기준	2.0.1 (2025-02-27)	GitHub 최신 릴리스

 

같은 2.0.1이지만 cask 쪽은 빌드 식별자(,536)가 함께 붙어 있습니다.
버전을 비교할 때는 "어느 출처 기준인지"를 명시하는 습관이 안전합니다.

 

설치 통계 (2026-06-19 확인 기준)

 

Homebrew cask 페이지는 설치 통계를 제공합니다.

 

기간	설치 수
최근 30일	3,733
최근 90일	8,897
최근 365일	16,497

 

규모가 폭발적으로 큰 도구는 아니지만, 1년에 1만 6천 건 이상 꾸준히 설치되는, 자리 잡은 메뉴바 유틸리티라고 볼 수 있습니다.

 

 

---

 

2. 설치와 첫 설정

 

Homebrew로 설치하기

 

본 글은 Homebrew cask 기준을 우선합니다.

 

# Homebrew cask 기준 설치 (이 글에서 권장)
brew install --cask swiftbar

 

참고로 README에는 다른 형태의 예시도 있습니다. 출처별로 구분해 두겠습니다.

 

구분	설치 명령	실행 환경
Homebrew cask 기준	brew install --cask swiftbar	macOS >= 11
README 기준	brew install swiftbar	macOS Catalina 10.15 이상

 

두 명령이 다르게 보여도 혼동하지 마세요. cask 페이지가 현재 --cask 플래그와 macOS 11 이상을 요구하므로, 새로 설치하는 분이라면 brew install --cask swiftbar를 쓰면 됩니다.

 

첫 실행과 Plugin Folder 지정

 

SwiftBar를 처음 실행하면 Plugin Folder를 지정하게 됩니다.

SwiftBar는 이 폴더 안의 파일을 플러그인으로 읽어들입니다.

 

# 플러그인 폴더 예시 (원하는 경로로 지정)
mkdir -p ~/SwiftBarPlugins

 

폴더를 지정한 뒤에는 SwiftBar 메뉴의 Get Plugins... 항목에서 공식 플러그인을 받아볼 수도 있습니다.

 

Plugin Folder 설계 시 알아둘 규칙

 

폴더를 어떻게 구성하느냐에 따라 SwiftBar의 탐색 동작이 달라집니다.

 

동작	SwiftBar의 처리 방식
숨김 폴더	무시됩니다 (탐색 대상 제외)
중첩(하위) 폴더	탐색합니다
symlink	탐색합니다
제외하고 싶은 파일	.swiftbarignore로 지정해 제외

 

중첩 폴더와 symlink를 탐색한다는 점은 실무에서 꽤 유용합니다.

예를 들어 팀 공용 플러그인 저장소를 클론해 두고, 그 안의 디렉터리를 Plugin Folder에 symlink로 걸어두면 됩니다.

 

권한, 업데이트, 삭제

 

플러그인은 결국 사용자 권한으로 실행되는 스크립트이므로, 신뢰할 수 있는 코드만 폴더에 넣어야 합니다(보안 주의점은 7장에서 다시 다룹니다).

업데이트와 삭제는 Homebrew를 그대로 활용합니다.

 

# 업데이트
brew upgrade --cask swiftbar

# 삭제
brew uninstall --cask swiftbar

 

 

---

 

3. 플러그인 파일명과 실행 모델

 

SwiftBar의 동작을 이해하는 핵심은 파일명과 실행 모델 두 가지입니다.

 

파일명 형식: {name}.{time}.{ext}

 

플러그인 파일명은 점(.)으로 구분된 세 부분으로 이뤄집니다.

 

구성 요소	의미	예시
name	플러그인 이름 (자유)	date
time	refresh interval(자동 갱신 주기)	1m
ext	확장자 (실행 환경)	sh

 

예를 들어 date.1m.sh는 "date라는 플러그인을 1분마다 갱신하는 셸 스크립트"라는 의미가 됩니다.

 

refresh interval 단위

 

time 부분에는 다음 단위를 쓸 수 있습니다.

 

단위	의미	예시
ms	밀리초	api.500ms.sh
s	초	cpu.10s.sh
m	분	date.1m.sh
h	시간	weather.1h.sh
d	일	quote.1d.sh

 

갱신 주기는 "필요한 만큼만"이 원칙입니다. 1초마다 외부 API를 때리는 플러그인을 여러 개 띄우면 배터리와 네트워크에 모두 부담이 됩니다(7장에서 조정 전략을 다룹니다).

 

stdout / stderr 와 출력 모델

 

플러그인은 실행 가능한 스크립트이며, stdout으로 메뉴바/드롭다운 텍스트를 출력합니다.

stderr는 에러용입니다. 이 둘을 섞지 않는 것이 디버깅의 출발점입니다.

 

출력은 Header와 Body로 나뉩니다.

 

• Header: 첫 번째 --- 이전의 출력. 메뉴바에 표시됩니다.
• Body: --- 이후의 출력. 클릭 시 펼쳐지는 드롭다운 메뉴 내용입니다.

 

출력 라인의 기본 형식은 다음과 같습니다.

 

<Item Title> | [param = ...]

 

즉, 제목을 먼저 쓰고 | 뒤에 표현/동작 파라미터를 붙입니다.

 

Standard 실행 모델과 플러그인 타입

 

SwiftBar 플러그인에는 여러 타입이 있습니다.

 

타입	동작 방식
Standard	실행 후 stdout을 내고 종료하는 기본 타입
Shortcuts	macOS 단축어와 연동되는 타입
Ephemeral	일시적으로 동작하는 타입
Streamable	별도 프로세스를 계속 실행하며 ~~~ 구분자로 메뉴바 항목을 갱신

 

가장 많이 쓰는 Standard 타입의 규칙은 명확합니다.

 

exit code 0 + non-empty stdout → 메뉴바가 구성됩니다.

exit code 1 → 메뉴바에 에러가 표시됩니다.

 

즉, "정상 종료하고, 빈 출력이 아니어야" 메뉴바가 제대로 그려집니다.

스트리밍이 필요한 실시간 모니터링에는 Streamable이 적합하며, 이때는 ~~~ 구분자로 항목을 갱신합니다.

 

---

 

4. 첫 번째 SwiftBar 플러그인 만들기

 

이제 가장 단순한 "현재 날짜/시간" 플러그인을 직접 만들어 보겠습니다.

macOS 기본 도구(date)만 사용합니다.

 

1단계: 파일 만들기

 

Plugin Folder 안에 date.1m.sh를 만듭니다. (1분마다 갱신)

 

#!/bin/bash
# date.1m.sh — 메뉴바에 현재 날짜/시간을 표시

# Header: 메뉴바에 표시되는 부분
date "+%Y-%m-%d %H:%M"

# 구분선 이후는 Body(드롭다운)
echo "---"
echo "오늘 날짜: $(date '+%Y년 %m월 %d일')"
echo "현재 시각: $(date '+%H시 %M분 %S초')"

 

2단계: 실행 권한 부여 (chmod)

 

플러그인은 "실행 가능한 스크립트"여야 합니다. 실행 권한이 없으면 동작하지 않습니다.

 

chmod +x ~/SwiftBarPlugins/date.1m.sh

 

3단계: 터미널에서 먼저 테스트

 

SwiftBar에 올리기 전에, 스크립트가 의도대로 출력하는지 직접 확인합니다.

 

# 직접 실행해서 stdout 확인
~/SwiftBarPlugins/date.1m.sh

# 종료 코드 확인 (0이어야 정상)
echo "exit code: $?"

 

여기서 첫 줄(Header)이 메뉴바에 올라갈 텍스트, --- 아래가 드롭다운에 들어갈 텍스트입니다.

exit code가 0이고 출력이 비어 있지 않다면 준비 완료입니다.

 

4단계: SwiftBar에 반영

 

SwiftBar는 Plugin Folder를 감시하므로 파일을 저장하면 잡아냅니다.

즉시 반영되지 않으면 SwiftBar 메뉴에서 새로고침을 하거나, URL scheme으로 강제 새로고침할 수 있습니다.

 

# 모든 플러그인 새로고침
open "swiftbar://refreshallplugins"

 

첫 플러그인이 안 보인다면 대부분 (1) 실행 권한 누락(chmod +x), (2) Header가 빈 출력, (3) 파일이 Plugin Folder 밖에 있음 — 이 세 가지 중 하나입니다.

 

---

 

5. 실무 활용 패턴 5가지

 

개발자가 메뉴바에 올려두면 좋은 패턴 다섯 가지를 살펴보겠습니다.

모두 macOS 기본 도구와 표준 CLI 위주로 구성했습니다.

 

패턴 1: 개발 서버 상태

 

로컬 개발 서버(예: 3000 포트)가 떠 있는지 확인합니다.

 

#!/bin/bash
# devserver.10s.sh — 로컬 3000 포트 상태

if lsof -i :3000 >/dev/null 2>&1; then
  echo "DEV ●"
else
  echo "DEV ○"
fi
echo "---"
echo "localhost:3000 | href=http://localhost:3000"

 

패턴 2: Git 브랜치

 

현재 작업 중인 저장소의 브랜치를 메뉴바에 띄웁니다.

 

#!/bin/bash
# gitbranch.30s.sh — 특정 저장소의 현재 브랜치

REPO="$HOME/work/my-project"
BRANCH=$(git -C "$REPO" rev-parse --abbrev-ref HEAD 2>/dev/null)

if [ -n "$BRANCH" ]; then
  echo "⎇ $BRANCH"
else
  echo "⎇ -"
fi
echo "---"
echo "저장소 열기 | bash=/usr/bin/open param1=$REPO terminal=false"

 

패턴 3: 디스크 용량

 

루트 볼륨의 사용률을 표시합니다.

 

#!/bin/bash
# disk.5m.sh — 디스크 사용률

USAGE=$(df -h / | awk 'NR==2 {print $5}')
echo "💾 $USAGE"
echo "---"
df -h / | awk 'NR==2 {print "사용: "$3" / 전체: "$2}'

 

패턴 4: API 상태

 

외부/내부 API의 헬스체크 결과를 표시합니다.

이때 갱신 주기를 너무 짧게 잡지 않는 것이 중요합니다.

 

활용	권장 갱신 주기	파일명 예시
개발 서버 상태	10초	devserver.10s.sh
Git 브랜치	30초	gitbranch.30s.sh
디스크 용량	5분	disk.5m.sh
API 헬스체크	1분	apihealth.1m.sh
배포 링크(정적)	1일	deploy.1d.sh

 

패턴 5: 배포 링크 모음

 

자주 여는 배포/대시보드 링크를 드롭다운에 모아둡니다.

정적인 정보이므로 갱신 주기를 길게(예: 1일) 잡습니다.

 

#!/bin/bash
# deploy.1d.sh — 자주 쓰는 링크 모음
echo "🚀 Deploy"
echo "---"
echo "Production | href=https://example.com"
echo "Staging | href=https://staging.example.com"
echo "CI 대시보드 | href=https://ci.example.com"

 

다섯 패턴 모두 핵심은 같습니다. "셸로 상태를 한 줄 만들어 Header에 올리고, 자세한 내용과 액션을 Body에 붙인다." 이 패턴만 익히면 어떤 정보든 메뉴바로 끌어올 수 있습니다.

 

---

 

6. 메뉴 표현력과 액션 파라미터

 

출력 라인 뒤에 |로 파라미터를 붙이면 색, 아이콘, 링크, 명령 실행 같은 표현력을 더할 수 있습니다.

README가 제시하는 주요 파라미터는 다음과 같습니다.

 

파라미터	역할
color	텍스트 색상 지정
font	글꼴 지정
size	글자 크기 지정
md	마크다운 처리 여부
sfimage	SF Symbols 아이콘 표시
checked	체크 표시
tooltip	마우스오버 툴팁
badge	배지 표시
refresh	클릭 시 플러그인 새로고침
href	클릭 시 URL 열기
bash	클릭 시 명령 실행
terminal	명령을 터미널에서 실행할지 여부
params	bash 실행 시 인자 전달
shortcut	단축키 지정

 

예시로 보는 파라미터 조합

 

#!/bin/bash
# params-demo.1m.sh — 파라미터 활용 예시
echo "Status"
echo "---"

# 색상 + SF Symbol 아이콘
echo "정상 동작 중 | color=green sfimage=checkmark.circle"

# 툴팁 + 배지
echo "대기 작업 | tooltip=처리 대기열 badge=3"

# 클릭 시 URL 열기
echo "문서 열기 | href=https://swiftbar.app/"

# 클릭 시 명령 실행 (터미널 없이)
echo "플러그인 새로고침 | refresh=true"

# 클릭 시 bash 실행 + 인자 전달
echo "빌드 실행 | bash=/usr/bin/make param1=build terminal=true"

 

• color와 sfimage로 상태를 직관적으로 표현합니다.
• tooltip/badge로 보조 정보를 얹습니다.
• href는 링크, bash는 명령 실행, refresh는 새로고침이라는 점이 핵심 구분입니다.
• bash로 명령을 실행할 때 인자는 params(param1, param2...)로 넘깁니다.

 

표현력 파라미터(color, sfimage, badge)와 액션 파라미터(href, bash, refresh)를 머릿속에서 분리해 두면 메뉴 설계가 훨씬 쉬워집니다.

 

메타데이터는 xbar 형식 권장

 

플러그인에 메타데이터를 넣을 때는 xbar 형식이 권장됩니다.

 

메타데이터 키	의미
xbar.title	플러그인 제목
xbar.version	버전
xbar.author	작성자
xbar.desc	설명
xbar.dependencies	의존성

 

---

 

7. 운영 안정성과 디버깅

 

플러그인이 늘어나면 "안정적으로 굴리고, 문제를 빨리 찾는" 운영 관점이 필요합니다.

 

제외 규칙: .swiftbarignore

 

작업 중인 파일이나 공용 스크립트 등 플러그인으로 읽히면 안 되는 파일은 .swiftbarignore로 제외합니다.

 

# Plugin Folder에 .swiftbarignore 생성
cat > ~/SwiftBarPlugins/.swiftbarignore <<'EOF'
# 라이브러리/공용 스크립트는 플러그인으로 읽지 않기
lib/
*.draft.sh
EOF

 

숨김 폴더는 어차피 무시되지만, 보이는 폴더 안의 특정 파일을 제외하려면 .swiftbarignore가 정석입니다.

 

SwiftBar가 제공하는 환경 변수

 

플러그인 안에서는 SwiftBar가 주입하는 환경 변수를 활용할 수 있습니다.

 

환경 변수	용도
SWIFTBAR	SwiftBar에서 실행 중인지 식별
SWIFTBAR_VERSION	SwiftBar 버전
SWIFTBAR_BUILD	빌드 번호
SWIFTBAR_PLUGINS_PATH	플러그인 폴더 경로
SWIFTBAR_PLUGIN_PATH	현재 플러그인 파일 경로
SWIFTBAR_PLUGIN_CACHE_PATH	플러그인 캐시 경로
SWIFTBAR_PLUGIN_DATA_PATH	플러그인 데이터 경로
SWIFTBAR_PLUGIN_REFRESH_REASON	새로고침이 발생한 이유
OS_APPEARANCE	다크/라이트 모드 등 외관 정보

 

예를 들어 SWIFTBAR_PLUGIN_DATA_PATH에 상태 파일을 저장하면 플러그인이 갱신될 때마다 직전 상태를 비교할 수 있고, OS_APPEARANCE로 다크/라이트에 맞춰 색을 바꿀 수 있습니다.

 

디버깅: 어디서 무엇을 보나

 

플러그인이 실패하면 단서는 다음 위치에 남습니다.

 

증상/단서	확인 위치
메뉴바에 경고 표시	SwiftBar 메뉴바 항목
드롭다운에 Error 표시	플러그인 드롭다운의 Error 항목
상세 로그/오류	macOS Console.app

 

디버깅의 순서는 항상 같습니다. ① 터미널에서 스크립트를 직접 실행해 stdout과 exit code 확인 → ② 메뉴바/드롭다운의 Error 확인 → ③ 그래도 모르겠으면 Console.app.

 

exit code와 stderr를 활용한 자가 진단

 

#!/bin/bash
# health.1m.sh — 실패를 명확히 드러내는 패턴
set -euo pipefail

if ! RESULT=$(curl -fsS https://example.com/health 2>/dev/null); then
  # stderr로 에러를 남기고, exit 1로 메뉴바에 에러 표시
  echo "헬스체크 실패" >&2
  echo "API ⚠️"
  echo "---"
  echo "엔드포인트 응답 없음"
  exit 1
fi

echo "API ●"
echo "---"
echo "$RESULT"

 

• 정상이 아닐 때 exit 1을 명시하면 메뉴바에 에러가 드러나 "조용한 실패"를 막을 수 있습니다.
• 진짜 에러 메시지는 stderr로 보내고, 메뉴 표시는 stdout으로 분리합니다.

 

refresh interval 조정과 보안 주의점

 

• 자주 바뀌지 않는 정보는 갱신 주기를 길게 잡아 시스템 부하를 줄입니다.
• 외부 네트워크를 호출하는 플러그인은 주기를 보수적으로 설정합니다.
• 플러그인은 사용자 권한으로 실행되는 임의의 스크립트입니다. 출처가 불분명한 플러그인을 Plugin Folder에 넣지 마세요.
• 비밀값(토큰, 키)을 스크립트에 하드코딩하지 말고, 별도 설정/키체인 등에서 읽어오도록 설계하세요(9장 참고).

 

---

 

8. BitBar/xbar와 비교하고 언제 선택할까?

 

SwiftBar는 BitBar/xbar 플러그인 API를 채택했기 때문에, 기존 BitBar/xbar 플러그인을 실행할 수 있습니다.

즉, 생태계 호환성이 강점입니다. 다른 메뉴바/자동화 도구들과 함께 비교해 보겠습니다.

 

도구	핵심 성격	SwiftBar와의 관계
SwiftBar	셸 stdout → 메뉴바. BitBar/xbar API 채택, MIT 라이선스	본 글의 주제
xbar	SwiftBar가 호환하는 선행 도구. 동일한 플러그인 API	기존 플러그인을 SwiftBar에서 실행 가능
BitBar	xbar의 전신 격. 동일 계열 플러그인 API	SwiftBar가 해당 API 채택
Hammerspoon	Lua 기반 macOS 자동화 프레임워크	메뉴바 외 광범위한 자동화 지향(성격 다름)
Raycast Script Commands	런처 중심의 스크립트 실행	메뉴바 상시 표시보다 런처 트리거 중심
macOS Shortcuts	애플 기본 단축어 자동화	SwiftBar는 Shortcuts 연동 타입을 별도로 지원

 

위 표에서 Hammerspoon·Raycast·Shortcuts의 세부 사양은 본 글의 공식 출처 범위 밖이므로, "성격이 이렇게 다르다" 수준의 일반적 구분만 적었습니다. 정확한 기능은 각 도구의 공식 문서를 확인하시길 권합니다.

 

언제 SwiftBar를 선택하면 좋은가

 

• 이미 셸 스크립트로 상태를 뽑고 있다 → stdout만 메뉴바로 올리면 되므로 SwiftBar가 가장 자연스럽습니다.
• 기존 BitBar/xbar 플러그인 자산이 있다 → API 호환이므로 거의 그대로 실행 가능합니다.
• 메뉴바에 상시 노출되는 가벼운 대시보드가 필요하다 → SwiftBar의 본령입니다.
• 반대로 복잡한 시스템 자동화(키 후킹, 창 관리 등)가 목적이라면 Hammerspoon 같은 프레임워크가, 런처 기반 즉시 실행이 목적이라면 Raycast 쪽이 더 맞을 수 있습니다.

 

---

 

9. 팀에서 쓰는 SwiftBar 운영 전략

 

혼자 쓰던 플러그인을 팀으로 확장할 때의 운영 포인트를 정리합니다.

 

플러그인 저장소 구조

 

SwiftBar가 중첩 폴더와 symlink를 탐색한다는 특성을 활용합니다.

공용 Git 저장소를 하나 두고, 각 개발자가 그 안의 폴더를 Plugin Folder에 symlink로 연결하면 됩니다.

 

swiftbar-team/
├── plugins/
│   ├── devserver.10s.sh
│   ├── gitbranch.30s.sh
│   └── deploy.1d.sh
├── lib/                 # 공용 함수 (.swiftbarignore로 제외)
│   └── common.sh
├── .swiftbarignore      # lib/ 제외
└── README.md            # 온보딩 문서

 

lib/ 같은 공용 코드 디렉터리는 .swiftbarignore로 제외해, 플러그인으로 잘못 읽히지 않게 합니다.

 

코드 리뷰와 공통 템플릿

 

• 플러그인도 사용자 권한으로 실행되는 코드이므로 PR 기반 코드 리뷰를 거치게 합니다.
• 공통 템플릿(메타데이터, 에러 처리 패턴, exit code 규칙)을 정해 두면 품질이 균일해집니다.

 

#!/bin/bash
# 팀 공통 템플릿 예시
# <xbar.title>팀 표준 플러그인</xbar.title>
# <xbar.author>your-team</xbar.author>
# <xbar.desc>설명을 적습니다</xbar.desc>
set -euo pipefail

# 실패 시 명확히 에러를 드러내는 공통 패턴
fail() { echo "$1" >&2; echo "⚠️"; echo "---"; echo "$1"; exit 1; }

# ... 본문 ...

 

비밀값 관리

 

• 토큰/키는 스크립트에 하드코딩 금지가 원칙입니다.
• 환경 변수, 별도 설정 파일, macOS 키체인 등에서 런타임에 읽어오도록 합니다.
• 공용 저장소에 비밀값이 커밋되지 않도록 .gitignore와 리뷰로 이중 방어합니다.

 

온보딩 문서

 

새 팀원이 따라 할 수 있도록 최소한 다음을 README에 남깁니다.

 

온보딩 항목	내용
설치	brew install --cask swiftbar (cask 기준)
Plugin Folder 연결	저장소 plugins/를 Plugin Folder에 symlink
실행 권한	새 스크립트는 chmod +x 필수
비밀값 설정	키체인/환경 변수 설정 방법 안내
새로고침	open "swiftbar://refreshallplugins"

 

팀 운영의 핵심은 "플러그인을 일반 코드처럼 다루는 것"입니다. 저장소·리뷰·비밀값 관리·온보딩 문서 — 일반 코드베이스에 적용하는 규율을 그대로 가져오면 됩니다.

 

---

 

10. FAQ

 

Q1. 설치 명령이 brew install swiftbar와 brew install --cask swiftbar 두 가지로 보입니다. 뭐가 맞나요?

README 기준 예시는 brew install swiftbar이지만, Homebrew cask 페이지는 현재 brew install --cask swiftbar를 안내합니다. 본 글은 cask 기준을 우선하므로 새로 설치한다면 brew install --cask swiftbar를 쓰세요.

 

Q2. macOS 버전 요구사항이 출처마다 다른데요?

Homebrew cask 기준은 macOS 11 이상, README 기준은 Catalina(10.15) 이상으로 표기되어 있습니다. 설치 기준(cask)을 따른다면 macOS 11 이상이 기준입니다.

 

Q3. 플러그인이 메뉴바에 안 보여요.

대개 세 가지입니다. ① 실행 권한 누락 → chmod +x, ② Header(첫 --- 이전)가 빈 출력, ③ 파일이 Plugin Folder 밖이거나 .swiftbarignore/숨김 폴더로 제외됨. 터미널에서 직접 실행해 stdout과 exit code(0이어야 함)를 먼저 확인하세요.

 

Q4. 갱신 주기는 어떻게 정하나요?

파일명의 time 부분으로 정합니다. ms/s/m/h/d 단위를 쓸 수 있고(date.1m.sh), 자주 바뀌지 않는 정보는 길게, 외부 호출이 있는 건 보수적으로 잡는 것이 좋습니다.

 

Q5. 기존 BitBar/xbar 플러그인을 쓸 수 있나요?

네. SwiftBar는 BitBar/xbar 플러그인 API를 채택했기 때문에 기존 BitBar/xbar 플러그인을 실행할 수 있습니다.

 

Q6. 실시간으로 계속 갱신되는 항목을 만들고 싶어요.

Standard 타입은 실행 후 종료하지만, Streamable 타입은 별도 프로세스를 계속 실행하면서 ~~~ 구분자로 메뉴바 항목을 갱신합니다. 실시간 모니터링에는 Streamable을 고려하세요.

 

Q7. 플러그인이 실패하면 로그는 어디서 보나요?

플러그인이 실패하면 메뉴바에 경고가 보이고, 드롭다운의 Error 항목 또는 macOS Console.app에서 상세 내용을 확인할 수 있습니다. 에러 메시지는 stderr로 보내고 메뉴 출력은 stdout으로 분리하면 추적이 쉬워집니다.

 

---

 

마무리

 

SwiftBar는 "셸 스크립트의 stdout을 메뉴바로 끌어올린다"는 단순하지만 강력한 아이디어로 동작합니다.

파일명 규칙({name}.{time}.{ext})과 출력 모델(Header/Body, stdout/stderr, exit code)만 이해하면, 나머지는 평소에 쓰던 셸 실력 그대로입니다.

 

바로 할 일 3단계

 

1. 오늘: brew install --cask swiftbar로 설치하고, Plugin Folder를 지정한 뒤 4장의 date.1m.sh를 만들어 메뉴바에 띄워보세요.
2. 이번 주: 5장 패턴 중 본인 업무에 맞는 1~2개(개발 서버 상태, Git 브랜치, API 헬스체크)를 실제 환경에 맞춰 작성해 운영해 보세요.
3. 꾸준히: 팀 공용 저장소 + 코드 리뷰 + 비밀값 관리 + 온보딩 문서로 플러그인을 "일반 코드처럼" 운영해 보세요.

 

핵심 요약 4줄

 

• SwiftBar는 셸 stdout을 메뉴바/드롭다운으로 바꿔주는 macOS 메뉴바 커스터마이징 도구입니다.
• 설치는 cask 기준 brew install --cask swiftbar(macOS 11+), 파일명의 time이 자동 갱신 주기를 정합니다.
• 출력은 <제목> | 파라미터 문법이며, color·sfimage·href·bash·refresh 등으로 표현력과 액션을 더합니다.
• BitBar/xbar API 호환 + MIT 라이선스로, 기존 플러그인 자산을 그대로 활용할 수 있습니다.

 

이 글이 도움이 되셨다면 댓글로 여러분만의 SwiftBar 플러그인 아이디어를 공유해 주세요.

주변에 맥으로 개발하는 동료가 있다면 이 글을 함께 나눠주시면 큰 힘이 됩니다. 🙌