Claude Code용 상태표시줄 CLI 도구. 컴퓨터·AI 프로그램이 처음이신 분도 처음부터 끝까지 따라 하실 수 있도록, 이 문서 하나에 설치부터 문제 해결·법률 정보까지 전부 정리했습니다. (계정 자동전환 기능은 이용약관 검토 결과 현재 배포판에 포함되어 있지 않습니다 — 아래 "② 계정 자동전환" 참고.)
지금 상태(중요): 이 프로젝트는 상태표시줄(Display) 기능만 배포합니다(현재 정식 출시 버전: v0.4.0). 아래 "① 상태표시줄"은 지금 실제로 잘 동작합니다. "② 계정 자동전환"은 현재 배포판에 전혀 포함되어 있지 않습니다 — Anthropic의 공식 이용약관을 직접 확인한 결과 이 기능이 이용약관과 충돌한다는 판단은 지금도 유효하며, 관련 코드는 실제 배포되는 실행 파일에 포함되지 않습니다(2026-07-15 확인, 자세한 내용은 아래 "② 계정 자동전환" 참고).
이 문서는 개발이 완료된 최신 기준으로 작성되었습니다. 실제로 내려받으시는 배포판(GitHub Release)은 정식 출시 시점 기준이라, 이 문서의 최신 설명과 다운로드하신 배포판 사이에 시간차가 있을 수 있습니다 — 배포판에 실제로 포함된 내용은 아래 "업데이트 내용 요약"과 Releases 페이지에서 확인하세요.
Claude Code 화면 아래에 지금 작업 중인 프로젝트 위치·사용 모델·컨텍스트 사용량·비용·사용률을 색과 막대 그래프로 보여줍니다. 여러분의 Claude 계정 정보나 비밀번호를 전혀 다루지 않습니다.
예시:
Sonnet 5 📁 my-project 🌿 main 컨텍스트 ██░░░ 45% 💰 $1.50 5시간 ████░ 78%·1:41 7일 ███░░ 71%·일06:00
(사용률과 무관하게 재설정 시간이 항상 함께 표시됩니다. 터미널 창 폭이 120칸 이상으로 넓으면 막대 그래프가 5칸에서 10칸으로 자동으로 더 촘촘하게 표시됩니다 — 설정할 필요 없이 자동으로 적용됩니다. Git 브랜치/변경사항 항목은 지금 작업 중인 폴더가 git 저장소일 때만 자동으로 나타나며, git 저장소가 아니면 자동으로 숨겨집니다. 반대로 화면 폭이 좁아 모든 항목이 한 줄에 다 들어가지 않으면, 상대적으로 덜 중요한 항목[Git → 사용률 → 비용 → 컨텍스트 순으로 뒤에서부터]이 자동으로 숨겨져 화면이 줄바꿈으로 깨지는 일을 막아줍니다 — 이 역시 설정 없이 자동으로 적용됩니다.)
- 정식 이름이 아직 정해지지 않아 지금은 "ClaudeTower"라는 가제(임시 이름)를 쓰고 있습니다.
- 이 프로젝트의 GitHub 저장소는 **공개(public)**입니다. 다운로드 페이지를 보는 데 GitHub 로그인이 필요하지 않습니다.
- 무료이며, 개인 사용 목적입니다. 상업적으로 판매하거나 회사에 유료로 납품하는 용도로는 만들어지지 않았습니다(자세한 내용은 아래 "법률·저작권·라이선스" 참고).
- 이 프로그램은 Anthropic(Claude를 만든 회사)의 공식 제품이 아닙니다. 개인이 만든 보조 도구이며, Anthropic과 제휴·후원 관계가 전혀 없습니다.
일반 사용자(프로그램을 그냥 쓰기만 하실 분)
| 준비물 | 왜 필요한가요? | 이미 있는지 확인하는 법 |
|---|---|---|
| Windows, macOS(Apple Silicon), 또는 Linux(x64) 컴퓨터 | 이 프로그램은 이 세 가지 운영체제에서만 지금 작동합니다 | 잘 모르시면 Windows는 "시작 메뉴 → 설정 → 시스템 → 정보"에서 확인 가능 |
| Claude Code 최신 버전 | 이 프로그램은 Claude Code의 "상태표시줄" 기능에 끼워 넣는 방식이라, Claude Code가 먼저 설치되어 있어야 합니다 | Claude Code가 이미 실행되고 있다면 준비 완료 |
| 웹 브라우저(크롬, 엣지 등) | 프로그램 파일을 받는 페이지에 접속하기 위해 필요합니다(GitHub 로그인은 필요 없습니다) | 평소 쓰시는 브라우저면 충분합니다 |
중요: 일반 사용자는 Node.js를 설치하실 필요가 전혀 없습니다. 프로그램 파일 하나만 받으면 바로 실행됩니다.
선택사항 — Git: 컴퓨터에 Git이 설치돼 있고 지금 작업 중인 폴더가 git 저장소라면, 상태표시줄에 현재 브랜치명과 변경사항 개수가 자동으로 추가 표시됩니다. Git이 없거나 git 저장소가 아니어도 전혀 문제없습니다 — 이 항목만 자동으로 숨겨지고 나머지 기능은 평소와 똑같이 작동합니다.
개발자(소스 코드를 직접 고치거나 빌드·테스트하실 분)
| 준비물 | 버전 |
|---|---|
| Node.js | 22 이상 |
| Git | 저장소를 내려받기 위해 필요 |
| npm(Node.js 설치 시 자동으로 함께 설치됨) | — |
Node.js를 설치할 필요가 없습니다. 아래 순서만 따라 하시면 됩니다.
- Releases 페이지에서 내 컴퓨터에 맞는 파일을 내려받습니다.
- Windows →
claudetower-win-x64.exe - macOS(Apple Silicon) →
claudetower-macos-arm64 - Linux(x64) →
claudetower-linux-x64
- Windows →
- 받은 파일을 아무 폴더에나 둡니다. 이름을 바꾸거나 나중에 다른 폴더로 옮겨도 괜찮습니다(아래 "설치 파일을 지우거나 옮겨도 되나요?" 참고).
- 그 폴더에서 터미널을 엽니다.
- Windows: 파일 탐색기 주소창을 클릭해 전부 지우고
cmd입력 후 Enter — 검은 배경 창이 뜨면 터미널입니다. - macOS: Finder에서 폴더 안 빈 공간을 마우스 오른쪽 버튼(또는 두 손가락)으로 클릭 → "폴더에서 새로운 터미널 열기".
- Windows: 파일 탐색기 주소창을 클릭해 전부 지우고
- 아래 명령을 실행합니다.
(macOS/Linux는 파일명 앞에
claudetower-win-x64.exe setup./를 붙입니다:./claudetower-macos-arm64 setup)- Windows에서 **"Windows가 PC를 보호했습니다"**라는 파란색 경고창이 뜰 수 있습니다. 아직 정식 인증서를 받지 않은 초기 버전이라 그런 것으로, 위험한 것이 아닙니다 —
추가 정보클릭 →실행을 누르면 계속 진행됩니다. - 화면에 뜨는 질문(모델/위치/컨텍스트/비용/사용률 각각 표시할지)에 Y 또는 N으로 답하면 끝입니다. 이때 실행 파일이 컴퓨터 안의 고정된 안전한 위치(
~/.claudetower/bin/)로 자동 복사됩니다. (Windows에서는 이어서 "터미널에서 claudetower라고 짧게 써도 되게 만들까요?"라는 질문이 한 번 더 뜹니다 — 어느 쪽으로 답해도 상태표시줄 자체는 동일하게 작동합니다.)
- Windows에서 **"Windows가 PC를 보호했습니다"**라는 파란색 경고창이 뜰 수 있습니다. 아직 정식 인증서를 받지 않은 초기 버전이라 그런 것으로, 위험한 것이 아닙니다 —
- Claude Code에서 다음 대화부터 상태표시줄이 바로 보입니다(재시작 불필요).
| 방법 | 상태 | 비고 |
|---|---|---|
| GitHub Release에서 직접 다운로드 (위 5단계) | ✅ 지금 가능 | Node.js 불필요 |
curl/PowerShell 원라이너 (install.sh/install.ps1) |
✅ 지금 가능(2026-07-04부터, main 브랜치 개설로 해결) |
Node.js 불필요, 아래 명령 참고. 터미널이 낯설면 위 5단계 직접 다운로드 방법을 권장합니다 |
| 소스에서 직접 빌드 | ✅ 지금 가능 | 개발자용, Node.js 22+ 필요 — 아래 "개발자용" 참고 |
npm install -g |
⏸️ 의도적으로 보류 | "ClaudeTower/claudetower"의 상표 저촉 여부 법률 검토는 2026-07-15에 끝났고, 낮은 우선순위 잔존 리스크를 감수하고 이 이름을 유지하기로 결정했습니다(.PRD/01_PRD.md §7). 다만 완전히 영구 확정된 상태는 아니라서, 사실상 영구 점유되는 자원인 npm 패키지 이름은 이름이 완전히 확정되기 전까지 발행하지 않습니다 |
macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/sodam-ai/ClaudeTower/main/install.sh | shWindows(PowerShell):
irm https://raw.githubusercontent.com/sodam-ai/ClaudeTower/main/install.ps1 | iex네, 그래도 됩니다. setup을 한 번 실행하면 그 실행 파일은 자동으로 컴퓨터 안의 고정 위치(~/.claudetower/bin/)로 복사되어 안전하게 정착합니다. 그 이후로는 원래 다운로드하신 파일을 지우거나, 이름을 바꾸거나, 다른 폴더로 옮기셔도 전혀 문제없습니다.
혹시 실수로 그 고정 위치의 파일까지 지워서 상태표시줄이 안 보이게 되더라도, claudetower setup을 다시 한 번 실행하면 자동으로 복구됩니다.
그냥 더블클릭하면 되나요? 파일을 더블클릭하면 검은 창이 잠깐 떴다가 바로 사라집니다 — 이건 고장이 아닙니다. 이 프로그램은 "명령어"와 함께 실행해야 뭔가를 하는 프로그램이라, 아무 명령어 없이 그냥 실행하면 사용법만 보여주고 끝납니다. 실제로 쓰려면 위 "빠른 시작"처럼 터미널을 열어서 명령어를 직접 입력해야 합니다.
매번 터미널을 열어야 하나요? 아니요. 설치(setup)는 딱 한 번만 하면 됩니다. 그 이후로는 Claude Code를 쓸 때마다 이 프로그램이 자동으로, 화면 뒤에서 조용히 실행되어 상태표시줄에 정보를 보여줍니다. 터미널을 다시 열어야 하는 경우는 표시 항목을 바꾸고 싶을 때(setup 재실행), 설치 상태를 확인하고 싶을 때(status), 프로그램 등록을 지우고 싶을 때(uninstall)뿐입니다.
참고: 위 5단계까지만 하면 상태표시줄은 이미 완성입니다. 아래 명령어들은 나중에 표시 항목을 바꾸는 등 추가로 필요할 때만 쓰면 됩니다.
setup실행 중 "터미널에서 짧게 입력해도 실행되게 만들까요?"에 Y로 답하셨다면 새 터미널에서claudetower라고 바로 쓸 수 있고, N으로 답했거나 예전 버전이라면 안 될 수 있습니다. 그래서:
- 제일 쉬운 방법(터미널 필요 없음): 클로드코드 채팅창에서
/claudetower-widgets라고 치거나 "상태표시줄에서 비용 표시 꺼줘"처럼 그냥 말하면 됩니다.- 그래도 터미널에서 직접 치고 싶다면,
claudetower대신 전체 경로~/.claudetower/bin/claudetower.exe(macOS/Linux는~/.claudetower/bin/claudetower)를 쓰면 항상 됩니다.
claudetower --version/--helpclaudetower setup— 상태표시줄 항목 선택 + Claude Code 설정 자동 등록(고정 위치로 자동 정착 포함). 표시 항목을 나중에 바꾸고 싶을 때도 이 명령을 다시 실행하면 됩니다(원하는 항목만 Y, 나머지는 n)claudetower status— 지금 설치돼 있는지, 어떤 항목이 켜져 있는지 확인설치 상태: 설치됨 (claudetower 상태표시줄이 Claude Code에 등록되어 있습니다) 표시 중인 항목: 사용 모델, 프로젝트 위치, Git 브랜치/변경사항, 컨텍스트 사용량, 비용, 사용률(5시간/7일)claudetower widgets— 지금 어떤 항목이 켜져 있는지 확인claudetower widgets off <항목...>/claudetower widgets on <항목...>— 지정한 항목만 켜고 끄기(나머지는 그대로,setup처럼 질문 전부에 다시 답할 필요 없음). 항목 이름:model,location,git,context,cost,rate_limitclaudetower config statusline-refresh <초>— 상태표시줄 갱신 주기를 조절합니다(기본 3초, 세션을 여러 개 띄워두는 경우 5초 이상으로 늘리면 컴퓨터 부담이 더 줄어듭니다).setup을 다시 실행해도 이 값은 유지됩니다. 터미널 없이 클로드코드 채팅창에서 "상태표시줄 갱신을 느리게 해줘"처럼 말해도 됩니다claudetower config powerline <on|off>— 위젯 사이 구분자를 공백 2칸에서 Powerline 스타일 화살표로 바꿉니다(색상 테마 없이 구분 기호만, 기본은 꺼짐). Nerd Font가 설치돼 있지 않은 터미널에서는 화살표가 깨져 보일 수 있으니 켜본 뒤 확인하세요claudetower config padding <n>— Claude Code 공식 상태표시줄 기능인 좌우 여백(문자 수)을 조절합니다(기본값 0). 예:claudetower config padding 2claudetower uninstall— 등록된 상태표시줄 설정만 안전하게 제거(다른 Claude Code 설정은 그대로 둠). Claude Code에 등록된 상태표시줄 설정만 깔끔하게 지워지며, 여러분이 따로 설정해두신 다른 Claude Code 설정은 전혀 건드리지 않습니다claudetower statusline— Claude Code가 내부적으로 호출하는 렌더러(직접 실행할 일 없음)
accounts등 계정 관련 명령은 존재하지 않습니다 — 현재 배포판에는 계정 관련 코드가 전혀 포함되어 있지 않습니다(아래 "② 계정 자동전환" 참고).
setup을 실행하면 /claudetower-widgets라는 대화형 명령도 함께 설치됩니다. 클로드코드 채팅창에 /claudetower-widgets라고 치거나 "상태표시줄에서 컨텍스트랑 비용 꺼줘", "갱신 속도를 느리게 해줘"처럼 말하면, AI가 지금 상태를 보여주고 대화하면서 대신 켜고 끄거나 속도를 조절해줍니다 — 터미널을 열거나 영어 명령어를 외울 필요가 없습니다. /claudetower-widgets만 딱 치고 아무 말도 안 하면, 무엇을 켜고 끌지 체크 메뉴(선택지에 마우스나 화살표로 체크)가 떠서 골라 고를 수도 있습니다(체크한 항목만 바뀌고, 체크 안 한 항목은 그대로 유지).
git clone https://github.com/sodam-ai/ClaudeTower.git
cd ClaudeTower
npm install
npm run builddist/ 폴더에 여러분 운영체제에 맞는 실행파일이 생깁니다.
| 명령 | 하는 일 |
|---|---|
npm install |
개발용 의존성 설치(빌드되는 실행 파일 자체에는 런타임 의존성이 0개입니다) |
npm run build |
dist/에 실행파일 생성 |
npm test / npm run test:display |
상태표시줄(Display) 기능 테스트 실행 |
npm run lint |
코드 스타일 검사 |
npm run lint:boundary |
Display·Account 모듈이 서로 섞이지 않았는지 구조 검사 |
npm run verify |
위 lint·모듈경계·테스트를 한 번에 전부 확인(커밋 전 권장) |
저장소 최상위 폴더의 주요 구성입니다(일반 사용자는 안 보셔도 됩니다).
ClaudeTower/
├── bin/claudetower.js # CLI 진입점(명령어 라우팅)
├── src/
│ ├── display/ # 상태표시줄 기능 — 계정 정보를 전혀 다루지 않는 안전한 모듈
│ │ ├── widgets/ # model, location, git, context, cost, rate-limit 각 위젯
│ │ ├── config/ # 설정 읽기/쓰기, 게이지·텍스트 안전 처리 등
│ │ └── cache/ # Git 정보 임시 저장(파일 캐시)
│ └── accounts/ # 계정 자동전환 관련 코드 — 현재 배포판에는 포함되지 않음(위 "② 계정 자동전환" 참고)
├── test/ # display/accounts 모듈별 테스트
├── scripts/ # 빌드·모듈 경계 검사 스크립트
├── .PRD/ # 설계 배경·의사결정 근거(개발자용)
├── install.sh / install.ps1 # 원라이너 설치 스크립트
└── LICENSE # Apache License 2.0 전문
일반 사용자는 아래 표를 신경 쓰지 않으셔도 됩니다 — 전부 선택사항이며, 아무것도 설정하지 않아도 정상 작동합니다.
| 환경 변수 | 용도 | 비고 |
|---|---|---|
COLUMNS |
터미널 폭(칸 수) — Claude Code가 자동으로 설정해 줌 | 게이지 폭 자동 확장·줄 길이 자동 조절에 사용(위 "예시" 참고). 사람이 직접 설정할 일은 거의 없음 |
CLAUDETOWER_SETTINGS_PATH |
Claude Code settings.json 대신 사용할 경로 |
주로 테스트·격리 실행용. 지정하지 않으면 기본 위치(~/.claude/settings.json) 사용 |
CLAUDETOWER_WIDGET_CONFIG_PATH |
위젯 설정 파일(config.json) 대신 사용할 경로 |
위와 동일한 용도 |
CLAUDETOWER_INSTALL_DIR |
실행 파일 설치 위치를 바꿈 | 위와 동일한 용도 |
CLAUDETOWER_SKILLS_DIR / CLAUDE_CONFIG_DIR |
/claudetower-widgets 채팅 명령 파일 설치 위치를 바꿈 |
위와 동일한 용도 |
CLAUDETOWER_CACHE_DIR |
Git 정보 임시 저장 폴더 위치를 바꿈 | 위와 동일한 용도 |
이 변수들은 주로 이 프로젝트 자신의 자동 테스트가 실제 사용자 파일을 건드리지 않도록 격리하는 용도로 만들어졌습니다. 직접 설정하실 필요는 거의 없지만, 문제 상황을 재현하거나 진단할 때 유용할 수 있어 정확한 이름을 여기 남겨둡니다.
쉬운 비유로 설명드리면: Claude Code는 대화할 때마다 "지금 상황"(어떤 폴더에서 작업 중인지, 모델이 뭔지, 비용이 얼마인지 등)을 이 프로그램에게 살짝 알려줍니다. 이 프로그램은 그 정보를 받아서 "보기 좋게 정리한 한 줄"로 바꿔서 다시 Claude Code에게 돌려주고, Claude Code는 그걸 화면 맨 아래에 그대로 보여줍니다. 안내판을 만들어주는 사람을 옆에 앉혀둔 것과 비슷합니다 — 여러분이 어디 있는지(폴더), 지금 몇 시인지(사용률 재설정 시간) 등을 보고 표지판만 만들어줄 뿐, 여러분의 지갑이나 신분증(계정 정보)에는 손대지 않습니다.
실제로 화면 한 줄이 만들어지기까지 컴퓨터 안에서 벌어지는 순서를 그대로 적으면 이렇습니다(모두 여러분 컴퓨터 안에서만 일어나며, 보통 1초도 안 걸립니다).
- Claude Code와 대화를 주고받는 동안, Claude Code가 정해둔 주기마다(기본 3초,
config statusline-refresh로 조절 가능) 자동으로 이 프로그램을 실행합니다. - Claude Code가 "지금 상황"(작업 폴더 경로, 사용 모델, 컨텍스트 사용량, 비용, 사용률)을 이 프로그램에 짧은 텍스트(JSON)로 전달합니다.
- 이 프로그램은 켜져 있는 항목(모델/위치/Git/컨텍스트/비용/사용률)을 하나씩 확인합니다 — 값이 없거나 표시할 수 없는 항목은 조용히 건너뜁니다(예: git 저장소가 아니면 Git 항목은 건너뜀).
- Git 항목은 컴퓨터에 설치된
git프로그램에게 브랜치명·변경사항 개수를 직접 물어봅니다. 같은 대화 세션 안에서 5초 이내에 다시 물어보면, 다시 조회하지 않고 방금 확인한 값을 그대로 재사용합니다(컴퓨터 부담을 줄이기 위한 임시 저장, 아래 "보안·데이터 흐름" 참고). - 확인된 항목들을 사람이 읽기 좋은 한 줄 문자열로 합칩니다. 이때 화면 폭에 비해 줄이 너무 길면, 상대적으로 덜 중요한 항목부터 자동으로 빼서 줄바꿈이 생기지 않게 합니다.
- 완성된 한 줄을 Claude Code에게 돌려주면, Claude Code가 이 문자열을 화면 맨 아래에 그대로 표시합니다.
- 아무것도 외부로 전송하지 않습니다. 여러분 컴퓨터 안에서만 동작합니다.
- Claude Code가 매번 상태표시줄 프로그램에 현재 상황(프로젝트 경로, 컨텍스트 사용량 등)을 전달하면, 그 값을 화면에 예쁘게 보여주기만 합니다 — 계정 정보나 대화 내용은 저장하지 않습니다.
- 화면에 표시되는 값(예: 프로젝트 폴더명)에 비정상적으로 긴 문자열이나 터미널 제어 문자가 섞여 있어도, 화면이 깨지지 않도록 자동으로 안전하게 다듬어서(길이 제한 + 위험 문자 제거) 보여줍니다. 항목 하나하나뿐 아니라 전체 한 줄의 길이도 화면 폭을 넘지 않도록 자동으로 관리됩니다(위 "워크플로우" 5번 참고).
- Git 브랜치명·변경사항 개수는 컴퓨터에 잠깐(5초) 임시 저장했다가 재사용됩니다 — 이 임시 저장 파일에도 개인정보나 계정 정보는 들어가지 않으며(저장되는 값은 브랜치명·변경 파일 개수뿐), 저장 자체에 실패하더라도 화면 표시에는 영향이 없도록 설계되어 있습니다(아래 "파일·문서 위치" 참고).
- 프로그램이 컴퓨터에 실제로 저장하는 파일은 "표시할 항목 목록"과 위 Git 임시 저장 파일 정도뿐이며, 어느 쪽에도 개인정보나 계정 정보는 전혀 들어가지 않습니다.
이 프로그램이 여러분 컴퓨터에 실제로 만들거나 사용하는 파일들의 위치입니다.
| 파일/폴더 | 위치(Windows 기준) | 무엇인가요? |
|---|---|---|
| 설치된 실행 파일 | C:\Users\사용자이름\.claudetower\bin\claudetower.exe |
setup 실행 시 자동으로 복사되는, 실제로 작동하는 파일(진짜 "본체") |
| 표시 항목 설정 | C:\Users\사용자이름\.claudetower\config.json |
어떤 항목을 보여줄지 저장한 작은 파일 |
| Git 정보 임시 저장 | C:\Users\사용자이름\.claudetower\cache\ |
Git 브랜치명·변경사항 개수를 5초만 임시 저장해두는 폴더(컴퓨터 부담 감소용). 개인정보·계정 정보 없음. 지워도 다음 실행 시 자동으로 다시 만들어집니다 |
| Claude Code 전역 설정 | C:\Users\사용자이름\.claude\settings.json |
Claude Code 자체의 설정 파일. 이 프로그램은 이 파일 안의 "statusLine" 부분만 사용하고 나머지(다른 설정들)는 절대 건드리지 않습니다 |
| 설정 백업 파일 | C:\Users\사용자이름\.claude\settings.json.bak |
설정을 바꾸기 직전의 원본이 자동으로 백업되는 파일 — 문제가 생기면 이 파일을 보고 되돌릴 수 있습니다 |
macOS/Linux에서는
C:\Users\사용자이름대신~(홈 폴더, 보통/Users/사용자이름또는/home/사용자이름)를 사용합니다.
개발자용 설계 문서: 이 프로그램이 왜 이렇게 만들어졌는지에 대한 상세한 기록은 저장소 안의 .PRD/ 폴더에 정리되어 있습니다(일반 사용자는 안 보셔도 됩니다).
이 프로그램은 처음부터 "상태표시줄" 부분과 "계정전환" 부분을 완전히 분리해서 설계했습니다. "상태표시줄 방"은 화면에 정보를 보여주기만 하는 방이라 늘 안전합니다. "계정전환 방"은 이용약관 충돌 문제로 신중하게 검토되고 있는 중입니다 — 내부적으로 일부 구성요소가 실험적으로 개발돼 있긴 하지만, "상태표시줄 방"과는 전혀 연결되어 있지 않고 실제 배포되는 프로그램에도 포함되지 않습니다(자세한 내용은 아래 "② 계정 자동전환" 참고).
원래 이 프로젝트는 여러 개의 Claude 계정을 자동으로 바꿔가며 쓸 수 있게 해주는 기능을 나중에 추가할 계획이었습니다. 2026-07-15에 Anthropic(Claude를 만든 회사)의 공식 이용약관을 직접 확인해본 결과, 이 기능을 안전하게 만들 방법이 없다는 것을 확인했습니다.
- Anthropic은 서드파티(외부) 프로그램이 구독제(Free·Pro·Max) 계정으로 로그인해서 그 계정을 대신 사용하는 것을 명시적으로 금지하고 있습니다. 2026-01-09부터는 이를 서버에서 기술적으로도 차단하고 있다는 사실을 여러 매체를 통해 교차 확인했습니다.
- 또한 API 키가 아닌 방식으로 자동화 스크립트가 서비스에 접근하는 것 자체도 별도로 금지되어 있어서, 로그인 정보를 직접 다루지 않는 우회 방법(예: 로그인은 Claude Code 자체 기능에 맡기고 설정 폴더만 자동으로 바꾸는 방식)을 시도하더라도 이 조항에 걸립니다.
이 이용약관 충돌 판단 자체는 지금도 그대로 유효합니다. 다만 이 결정은 이후 내부적으로 다시 검토된 바 있습니다(검토 배경과 근거는 저장소의 .PRD/07_OAUTH_FLOW_SPEC.md에 기록되어 있습니다). 어느 경우든 변하지 않는 사실은, 이 기능과 관련된 코드가 실제로 배포되는 실행 파일에는 전혀 포함되어 있지 않다는 것입니다 — 저장소의 자동화된 빌드 검증 절차가 매 빌드마다 이를 확인합니다. 상태표시줄 기능은 이 사안과 무관하게 계속 정상적으로 작동합니다.
정식 출시(릴리스)된 버전별 변경 내용입니다(현재 최신: v0.4.0). 항목을 클릭하면 펼쳐집니다.
v0.4.0 — 게이지 동적 폭 + config padding 명령 추가 (최신)
터미널이 넓을 때(120칸 이상) 막대 그래프(게이지)가 5칸에서 10칸으로 자동으로 더 촘촘하게 표시되는 기능과, 상태표시줄 좌우 여백을 조절하는 새 명령 claudetower config padding <n>(기본값 0)이 추가되었습니다. 두 기능 모두 좁은 터미널이나 기본값 그대로 쓰는 기존 사용자에게는 아무 영향이 없습니다(폭 자동조절은 좁을 때 항상 기존 5칸을 유지, padding 기본값은 이전과 동일한 0). 이 외에 claudetower config statusline-refresh가 빈 문자열 같은 잘못된 입력을 더 안전하게 걸러내도록 내부 방어 코드를 보강했습니다(화면에 보이는 동작 변화는 없음).
v0.3.0 — Powerline 구분자 명령 추가
새 명령 claudetower config powerline <on|off>로 상태표시줄 위젯 사이 구분자를 기본 이중 공백에서 Powerline 스타일 화살표 글리프(U+E0B1)로 바꿀 수 있습니다. 색상 테마는 없고 글리프만 적용되며, 기본값은 꺼짐(OFF, 선택적 적용)이라 기존 사용자는 직접 켜지 않는 한 아무 변화도 없습니다. 이 글리프는 Nerd Font 전용 영역(Private Use Area) 문자를 사용하므로, Nerd Font가 설치되지 않은 터미널에서는 깨지거나 빈 문자로 보일 수 있습니다 — 켜기 전에 먼저 확인해 보세요.
v0.2.0 — 설치 안정화, 자가복구, 위젯 메뉴
설치 스크립트가 상태표시줄과 동시에 실행될 때 파일이 손상되던 결함과 /claudetower-widgets 명령이 사라지는 근본 원인을 수정하고 자가복구 기능을 추가했습니다. Windows PATH 자동등록 옵션과 갱신 속도 조절 명령(config statusline-refresh, 기본 갱신주기 1초→3초)을 신설했고, uninstall이 설정·스킬 파일을 실수로 지우던 결함도 막았습니다. /claudetower-widgets를 인자 없이 실행하면 체크박스로 위젯을 켜고 끌 수 있으며, 컨텍스트·비용·모델명·폴더명·재설정 시간 표시의 경계값 결함도 함께 수정했습니다. 계정 자동전환 기능은 Anthropic 이용약관 검토 결과 이 시점 기준으로 만들지 않기로 판단되어, ClaudeTower는 상태표시줄 전용 도구로 남았습니다(이 판단은 이후 다시 검토된 바 있으나, 관련 코드는 지금도 배포판에 포함되지 않습니다 — 위 "② 계정 자동전환" 참고).
v0.1.10 — 퍼센트 표시 결함 수정, 원라이너 설치 안정화
컨텍스트·사용률 퍼센트가 정상 범위(0~100)를 벗어나면 있을 수 없는 숫자가 그대로 표시되던 결함 수정. curl/PowerShell 한 줄 설치 안정화. "Anthropic 공식 제품 아님" 고지 추가.
v0.1.9 — 위젯 빠른 켜고 끄기 + 채팅 설정
claudetower widgets on/off 추가. /claudetower-widgets 채팅 명령 자동 설치.
v0.1.8 — 재설정 시간 상시 표시, 설치 안정성 개선
재설정 시간을 사용률과 무관하게 항상 표시하도록 변경(이전엔 70% 이상일 때만 표시). 또한 setup으로 새 버전을 설치할 때 Claude Code가 실행 파일을 계속 사용 중이라 설치가 조용히 실패하던 결함을 수정(임시 파일 복사 후 안전하게 교체 + 자동 재시도).
v0.1.7 — 재설정 시간 표시
사용률이 위험 수준(70% 이상)일 때 "언제 다시 채워지는지" 재설정 시간을 함께 표시.
v0.1.6 — 설치 위치 고정, 자동 복구
설치 파일을 지우거나 이름을 바꾸거나 옮겨도 더 이상 고장 나지 않도록 개선(고정된 안전 위치로 자동 정착).
v0.1.5 — 설치 상태 확인 명령 추가
status(설치 상태 확인) 명령 추가, uninstall 실행 후 실제로 완전히 제거됐는지 재확인하는 절차 추가.
v0.1.4 — 모델 표시, 퍼센트 표기 정리
"사용 모델" 표시 항목 추가, 사용률 숫자가 가끔 지저분하게(예: 14.000000000000002%) 표시되던 결함 수정.
v0.1.3 — 제거 명령, 그래프 개선
uninstall(제거) 명령 추가, 막대 그래프 색상 개선, 위치 정보가 더 빠르게 갱신되도록 개선.
v0.1.2 — 더블클릭 오류 수정
프로그램 파일을 그냥 더블클릭했을 때 창이 바로 꺼져버리던 문제 수정.
v0.1.1 — 막대 그래프 추가
표시 항목을 숫자(%) 대신 막대 그래프(게이지바)로도 함께 보여주도록 개선.
v0.1.0 — 최초 배포
위치·컨텍스트·비용·사용률 4개 항목 표시, setup 설치 마법사.
| 증상 | 원인 / 해결 방법 |
|---|---|
| Releases 페이지에서 404 오류가 떠요 | 주소를 정확히 입력했는지 확인하세요(대소문자·오타 주의). |
| 파란 경고창에서 "실행" 버튼이 안 보여요 | "추가 정보"를 먼저 눌러야 그 아래에 "실행" 버튼이 나타납니다. |
| exe를 더블클릭했는데 창이 바로 꺼져요 | 고장이 아닙니다. 인자 없이 실행하면 도움말만 보여주고 끝납니다 — 실제로 쓰려면 터미널을 열어서 claudetower-win-x64.exe setup처럼 명령을 직접 입력해야 합니다. |
claudetower status에서 **"등록은 되어 있으나 실행 파일을 찾을 수 없습니다(고장 상태)"**가 떠요 |
설치 파일이 있던 자리를 지웠거나 옮긴 경우입니다. claudetower setup을 다시 실행하면 자동으로 복구됩니다. |
setup으로 새 버전을 설치했는데 안 바뀌어요(예: 버전 번호가 그대로) |
v0.1.8부터 자동으로 몇 차례 재시도하도록 고쳐졌지만, 백신 프로그램 검사 등으로 그보다 오래 걸리면 여전히 실패할 수 있습니다. Claude Code를 잠깐 닫아둔 상태에서 setup을 다시 실행해보세요. |
| 상태표시줄이 안 보여요 | 세 가지 원인이 있습니다. ① 설정은 다음 상호작용부터 반영됩니다 — Claude Code와 한 번 더 대화해보세요. ② 이 폴더(워크스페이스)의 신뢰(trust) 확인 창을 아직 수락하지 않았다면 상태표시줄 자체가 실행되지 않고, 화면에 statusline skipped · restart to fix라고 뜹니다 — 신뢰 확인 창을 수락한 뒤 Claude Code를 다시 시작하세요. ③ Claude Code 설정에서 disableAllHooks를 켜두면 상태표시줄도 함께 꺼집니다(Claude Code 공식 사양) — 필요 없다면 꺼주세요. |
/claudetower-widgets(채팅으로 위젯 켜고 끄기)가 갑자기 안 돼요 |
근본 원인을 확정했습니다 — 이 프로그램 자신의 자동 검증 절차가 실수로 실제 설정 파일을 지우는 결함이었습니다(사용자 잘못이 아닙니다). 재발 방지 코드와 자가복구를 모두 적용했습니다(v0.2.0부터 포함됨). 그보다 이전 버전을 쓰고 계시다면 최신 버전으로 업데이트하시고, 지금 버전에서 겪으신다면 claudetower setup을 다시 실행하면 즉시 복구됩니다. |
| 컨텍스트 퍼센트가 이상하거나 비어있어요 | 세션 초반이나 /compact 직후에는 값이 비어있을 수 있습니다(정상 동작, Claude Code 공식 동작 방식). |
| Windows에서 실행파일 실행 시 경고가 떠요 | 아직 디지털 서명이 없어 "알 수 없는 게시자" 경고가 뜰 수 있습니다. "추가 정보" → "실행"으로 진행하세요(정식 서명 배포 전까지는 정상입니다). |
개발자용 — npm run build가 실패해요 |
node --version으로 22 이상인지 확인하세요. |
그래도 해결이 안 되면: claudetower status 명령을 실행한 화면을 캡처(스크린샷)해서 Issues 페이지에 문의해주시면 원인 파악이 훨씬 빨라집니다.
- 설치하면 자동으로 제 계정 정보를 가져가나요? 아니요. 계정 관련 코드는 이 버전에 아예 포함되어 있지 않습니다. 이 프로그램은 여러분의 아이디·비밀번호·인증 토큰을 볼 수도, 저장할 수도 없는 구조입니다.
- 인터넷으로 뭔가 전송되나요? 아니요, 전부 로컬에서만 동작합니다.
- 계정 자동전환 기능을 만들 계획이 있나요? 이 기능은 Anthropic 이용약관과 충돌한다는 판단이 확인돼 있고, 이 판단은 지금도 유효합니다. 관련 검토는 내부적으로 계속되고 있지만, 현재 배포되는 프로그램에는 이 기능이 전혀 포함되어 있지 않습니다(자세한 내용은 위 "② 계정 자동전환" 참고).
- 원본 다운로드 파일을 지워도 정말 괜찮나요? 네,
setup을 한 번 실행한 뒤라면 괜찮습니다 — 위 "설치 파일을 지우거나 옮겨도 되나요?" 참고. - 돈이 드나요? 아니요, 무료입니다. 다만 이 프로그램 자체와, 이 프로그램이 화면에 표시해주는 "비용($)" 정보는 서로 다릅니다 — 그 비용은 여러분이 Claude Code(AI)를 사용하면서 발생하는 별도의 비용이며, 이 프로그램과는 무관합니다.
- 왜 프로그램 이름이 "가제"라고 되어 있나요? 상표 저촉 여부에 대한 법률 검토는 2026-07-15에 끝났고, "ClaudeTower"라는 이름을 그대로 쓰기로 결정했습니다(낮은 우선순위의 잔존 리스크는 있지만 감수하기로 함, 자세한 근거는 아래 "법률·저작권·라이선스" 참고). 다만 사용자 규모가 크게 늘거나 Anthropic으로부터 직접 연락이 오는 경우에는 이름을 바꿀 가능성도 완전히 배제하지 않기 때문에, 완전한 "정식 확정"까지는 아니라는 뜻에서 여전히 "가제"라고 표시하고 있습니다.
- 이 프로그램을 회사에서 써도 되나요? 개인 사용을 전제로 만들어졌으며, 상업적 판매나 회사 납품 목적으로는 만들어지지 않았습니다. 자세한 내용은 아래 "법률·저작권·라이선스"를 반드시 읽어주세요.
⚠️ 이 섹션은 법률 자문이 아닙니다. 아래 내용은 이 프로젝트의 현재 상태를 있는 그대로, 정직하게 설명한 것이며, 확정된 사실과 아직 결정되지 않은 사항을 명확히 구분해서 적었습니다. 법적으로 중요한 판단이 필요하시면 반드시 변호사 등 전문가와 상담하세요.
이 프로그램과 Anthropic의 관계: 이 프로그램은 Anthropic(Claude와 Claude Code를 만든 회사)이 만들거나 공식적으로 인정한 제품이 아닙니다. 개인 개발자가 Claude Code를 더 편하게 쓰기 위해 만든 독립적인 보조 도구이며, Anthropic과 어떠한 제휴·후원·협력 관계도 없습니다. "Claude"라는 이름이 이 문서에 등장하는 것은 오직 "이 프로그램이 Claude Code와 함께 작동한다"는 사실을 설명하기 위해서일 뿐, Anthropic이 이 프로그램을 만들었거나 보증한다는 뜻이 아닙니다.
라이선스(확정된 사실): 이 프로젝트는 Apache License 2.0을 채택합니다(MIT보다 특허권 관련 조항이 명시적으로 포함된 점이 특징). 저작권자는 SoDam AI Studio이며, 라이선스 전문은 저장소의 LICENSE 파일에 있습니다.
라이선스(아직 확정되지 않은 사항): 프로그램의 정식 이름은 완전히 영구 확정된 상태는 아닙니다. "ClaudeTower"라는 이름의 상표권 저촉 여부에 대한 법률 검토는 2026-07-15에 끝났고, 검토 결과 낮은 우선순위의 잔존 리스크를 감수하고 이 이름을 그대로 유지하기로 결정했습니다(재검토 조건: 사용자 규모가 크게 늘어나거나 Anthropic이 직접 연락해오는 경우). 이 "가제" 상태가 완전히 해소되기 전까지는 npm install -g 배포 채널도 의도적으로 열지 않습니다(패키지 이름은 사실상 영구 점유되는 자원이기 때문입니다).
상업적 사용 — 엄격한 금지 원칙: 이 프로그램의 현재 버전(v0.4.0, Phase 1 MVP)은 ❌ 상업적 판매, ❌ 유료 서비스화, ❌ 회사·기관에 대한 유료 납품 목적으로 사용하도록 설계되지 않았습니다. 이 프로그램은 무료·개인 사용 목적으로만 배포됩니다. 이렇게 엄격하게 제한하는 이유: 이 프로젝트는 원래 계정 자동전환 기능을 나중에 추가할 계획이었는데, 검토 결과 그 기능이 Claude 서비스의 이용약관과 충돌한다는 사실이 확인됐습니다(위 "② 계정 자동전환" 참고). 이 조사 과정에서, 만약 이 기능이 실제로 프로그램에 포함되어 배포된다면 그 기능을 켜지 않고 상태표시줄 기능만 쓰는 분에게도 이 위험이 잠재적으로 함께 딸려올 수 있다는 점도 함께 확인됐습니다. 상업적 사용을 처음부터 배제해온 설계 원칙은 이런 위험을 애초에 키우지 않기 위한 것이며, 계정 자동전환 관련 코드가 실제 배포판에 전혀 포함되지 않은 지금도 그대로 유지됩니다. (현재 배포판에는 계정 관련 코드가 전혀 없어 위 이용약관 충돌 위험이 실제로 발생할 여지가 없지만, 상업적 사용 금지라는 설계 원칙 자체는 이 사안과 무관하게 프로젝트 전체에 계속 적용됩니다.)
"라이선스가 허용하는 것"과 "이 프로젝트가 권장하는 것"의 차이 (중요): Apache License 2.0 자체에는 "상업적 사용 금지" 같은 조항이 없습니다. 라이선스 조건(저작권·라이선스 고지 유지 등)만 지키면 수정·복제·재배포·상업적 사용이 원칙적으로 가능하도록 설계된 permissive(허용적) 라이선스입니다. 즉 위 "상업적 사용 금지" 문구는 **라이선스가 법적으로 금지한다는 뜻이 아니라, 이 프로젝트가 권장하지 않는다는 안내(설계 의도)**입니다.
| 하고 싶은 일 | 라이선스가 허용하나요? | 이 프로젝트가 권장하나요? |
|---|---|---|
| 코드를 수정해서 쓰기 | ✅ 허용 | ✅ 권장(저작권·라이선스 고지는 유지) |
| 그대로 복제·포크하기 | ✅ 허용 | ✅ 권장 |
| 수정본을 다시 배포하기 | ✅ 허용(라이선스 사본·저작권 고지 포함 조건) | ✅ 권장 |
| 교육 자료로 활용하기 | ✅ 허용 | ✅ 권장 |
| 판매·유료 서비스화 | 라이선스 조항만 보면 가능 | ❌ 권장하지 않음(위 참고) |
| 회사·고객사에 납품 | 라이선스 조항만 보면 가능 | ❌ 권장하지 않음(위 참고) |
상업적 사용을 실제로 법적 구속력 있게 제한하고 싶다면 Apache 2.0이 아닌 다른 라이선스 체계로의 전환이 필요합니다 — 이는 프로젝트 소유자가 별도로 결정할 사항입니다.
외부 코드·아이디어 재사용: 이 프로젝트를 설계하는 과정에서 다른 여러 오픈소스 상태표시줄/계정 관리 도구(예: ccstatusline, starship-claude 등)를 참고했지만, 소스 코드를 그대로 복사하지 않았고 "아이디어·설계 패턴"만 참고했습니다. 만약 앞으로 실제 코드를 일부라도 차용하게 될 경우, 해당 원본 프로젝트 라이선스가 요구하는 고지 의무를 반드시 따를 예정입니다(현재는 법무 검토가 완료되지 않은 사항입니다).
책임 제한: 이 프로그램은 Apache License 2.0의 표준 조항에 따라 "있는 그대로(AS IS)" 제공되며, 어떠한 형태의 명시적·묵시적 보증도 제공하지 않습니다. 이 프로그램을 사용함으로써 발생하는 어떠한 손해에 대해서도 저작권자(SoDam AI Studio)는 책임을 지지 않습니다(정확한 법률 조항 전문은 LICENSE 파일 참고).
AI가 개발에 관여한 사실에 관하여: 이 프로젝트의 코드와 문서 상당 부분은 AI 코딩 도구(Claude Code)의 도움을 받아 작성되었습니다(저장소의 커밋 기록에 "Co-Authored-By: Claude"로 명시). AI가 생성·보조한 콘텐츠의 저작권 성립 여부, 학습 데이터 출처, 기존 저작물과의 유사성·저촉 가능성은 국가·관할권마다 법리가 다르고 아직 확립되지 않은 영역입니다. 이 프로젝트를 그대로 또는 변형해서 사용·재배포·상업적으로 활용할 계획이시라면, AI 보조 생성물이 포함되어 있다는 사실을 인지하시고 필요 시 저작권·출처·상업적 이용 가능 여부를 직접 확인하시길 권장합니다(법무 검토 필요).
NOTICE 파일에 관하여: 이 프로젝트는 별도의 NOTICE 파일을 두지 않습니다. Apache License 2.0 제4조(d)는 배포하는 결과물에 이미 NOTICE 파일이 포함된 경우에만 그 내용을 계속 전달하도록 요구합니다. package.json에는 현재 런타임 의존성이 하나 있으나(@napi-rs/keyring, OS 자격증명 저장소 접근용), 이는 아직 배포판에 포함되지 않은 계정 관련 코드(위 "② 계정 자동전환" 참고)에서만 사용되며, ClaudeTower가 실제로 배포하는 실행 파일에는 포함되지 않습니다 — 빌드 시 사용되지 않는 코드는 자동으로 제외되며, 저장소의 자동화된 검증 절차가 매 빌드마다 이를 확인합니다(빌드 도구인 esbuild·eslint 역시 개발 전용이며 배포되는 실행 파일에는 포함되지 않습니다). 이 기능이 실제로 배포판에 포함되는 시점이 오면 이 판단을 다시 검토해야 합니다.
자세한 배경은 .PRD/04_PROJECT_SPEC.md의 "법률·저작권·라이선스·상업적 사용 요구사항" 참고.
이 프로젝트의 설계 배경·의사결정 근거·보안 요구사항은 .PRD/ 폴더에 전부 정리되어 있습니다.