한국어 | English

Claude Code용 상태표시줄 CLI 도구. (계정 자동전환 기능은 검토 끝에 법적 문제로 만들지 않기로 확정했습니다 — 아래 "② 계정 자동전환" 참고.)

📖 컴퓨터·AI 프로그램이 처음이신가요? 이 README보다 훨씬 더 자세하고 쉬운 완전 사용 가이드(GUIDE.md)를 준비해뒀습니다.

지금 상태(중요): 이 프로젝트는 상태표시줄(Display) 기능만 제공합니다(현재 정식 출시 버전: v0.3.0). 아래 "① 상태표시줄"은 지금 실제로 잘 동작합니다. "② 계정 자동전환"은 만들지 않기로 확정되었습니다 — Anthropic의 공식 이용약관을 직접 확인한 결과 이 기능을 안전하게 구현할 방법이 없다는 것이 확인되었기 때문입니다(2026-07-15 확정, 자세한 이유는 아래 "② 계정 자동전환" 참고).

• ① 상태표시줄
  • 빠른 시작(5단계)
  • 설치 방법
  • 명령어 목록
  • 채팅으로 켜고 끄기
  • 개발자용 빌드
  • 보안·데이터 흐름
  • 아키텍처
• ② 계정 자동전환(개발하지 않기로 결정됨)
• 업데이트 내용 요약
• 트러블슈팅
• 자주 묻는 질문(FAQ)
• 법률·저작권·라이선스
• 더 자세한 설계 문서

📖 훨씬 더 자세하고 초보자 친화적인 안내는 완전 사용 가이드(GUIDE.md)를 참고하세요 — 사전 준비물, 다운로드부터 실행까지 화면별 캡처 수준의 설명, 워크플로우 그림, 전체 FAQ가 담겨 있습니다.

Claude Code 화면 아래에 지금 작업 중인 프로젝트 위치·사용 모델·컨텍스트 사용량·비용·사용률을 색과 막대 그래프로 보여줍니다. 여러분의 Claude 계정 정보나 비밀번호를 전혀 다루지 않습니다.

예시:

Sonnet 5  📁 my-project  컨텍스트 ██░░░ 45%  💰 $1.50  5시간 ████░ 78%·1:41  7일 ███░░ 71%·일06:00

(사용률과 무관하게 재설정 시간이 항상 함께 표시됩니다.)

Node.js를 설치할 필요가 없습니다. 아래 순서만 따라 하시면 됩니다.

1. Releases 페이지에서 내 컴퓨터에 맞는 파일을 내려받습니다.
   • Windows → claudetower-win-x64.exe
   • macOS(Apple Silicon) → claudetower-macos-arm64
   • Linux(x64) → claudetower-linux-x64
2. 받은 파일을 아무 폴더에나 둡니다. 이름을 바꾸거나 나중에 다른 폴더로 옮겨도 괜찮습니다(아래 "설치 파일을 지우거나 옮겨도 되나요?" 참고).
3. 그 폴더에서 터미널을 엽니다(Windows: 파일 탐색기 주소창에 cmd 입력 후 Enter).
4. 아래 명령을 실행합니다.

   claudetower-win-x64.exe setup
   

   (macOS/Linux는 파일명 앞에 ./를 붙입니다: ./claudetower-macos-arm64 setup) 화면에 뜨는 질문(모델/위치/컨텍스트/비용/사용률 각각 표시할지)에 Y 또는 N으로 답하면 끝입니다. 이때 실행 파일이 컴퓨터 안의 고정된 안전한 위치(~/.claudetower/bin/)로 자동 복사됩니다. (Windows에서는 이어서 "터미널에서 claudetower라고 짧게 써도 되게 만들까요?"라는 질문이 한 번 더 뜹니다 — 어느 쪽으로 답해도 상태표시줄 자체는 동일하게 작동합니다.)
5. Claude Code에서 다음 대화부터 상태표시줄이 바로 보입니다(재시작 불필요).

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/sodam-ai/ClaudeTower/main/install.sh | sh

Windows(PowerShell):

irm https://raw.githubusercontent.com/sodam-ai/ClaudeTower/main/install.ps1 | iex

네, 그래도 됩니다. setup을 한 번 실행하면 그 실행 파일은 자동으로 컴퓨터 안의 고정 위치(~/.claudetower/bin/)로 복사되어 안전하게 정착합니다. 그 이후로는 원래 다운로드하신 파일을 지우거나, 이름을 바꾸거나, 다른 폴더로 옮기셔도 전혀 문제없습니다.

혹시 실수로 그 고정 위치의 파일까지 지워서 상태표시줄이 안 보이게 되더라도, claudetower setup을 다시 한 번 실행하면 자동으로 복구됩니다.

참고: 위 5단계까지만 하면 상태표시줄은 이미 완성입니다. 아래 명령어들은 나중에 표시 항목을 바꾸는 등 추가로 필요할 때만 쓰면 됩니다. setup 실행 중 "터미널에서 짧게 입력해도 실행되게 만들까요?"에 Y로 답하셨다면 새 터미널에서 claudetower라고 바로 쓸 수 있고, N으로 답했거나 예전 버전이라면 안 될 수 있습니다. 그래서:

• 제일 쉬운 방법(터미널 필요 없음): 클로드코드 채팅창에서 /claudetower-widgets라고 치거나 "상태표시줄에서 비용 표시 꺼줘"처럼 그냥 말하면 됩니다.
• 그래도 터미널에서 직접 치고 싶다면, claudetower 대신 전체 경로 ~/.claudetower/bin/claudetower.exe(macOS/Linux는 ~/.claudetower/bin/claudetower)를 쓰면 항상 됩니다.

• claudetower --version / --help
• claudetower setup — 상태표시줄 항목 선택 + Claude Code 설정 자동 등록(고정 위치로 자동 정착 포함)
• claudetower status — 지금 설치돼 있는지, 어떤 항목이 켜져 있는지 확인

  설치 상태: 설치됨 (claudetower 상태표시줄이 Claude Code에 등록되어 있습니다)
  표시 중인 항목: 사용 모델, 프로젝트 위치, 컨텍스트 사용량, 비용, 사용률(5시간/7일)
  

• claudetower widgets — 지금 어떤 항목이 켜져 있는지 확인
• claudetower widgets off <항목...> / claudetower widgets on <항목...> — 지정한 항목만 켜고 끄기(나머지는 그대로, setup처럼 5개 질문에 전부 다시 답할 필요 없음). 항목 이름: model, location, context, cost, rate_limit
• claudetower config statusline-refresh <초> — 상태표시줄 갱신 주기를 조절합니다(기본 3초, 세션을 여러 개 띄워두는 경우 5초 이상으로 늘리면 컴퓨터 부담이 더 줄어듭니다). setup을 다시 실행해도 이 값은 유지됩니다. 터미널 없이 클로드코드 채팅창에서 "상태표시줄 갱신을 느리게 해줘"처럼 말해도 됩니다
• claudetower config powerline <on|off>(신규) — 위젯 사이 구분자를 공백 2칸에서 Powerline 스타일 화살표로 바꿉니다(색상 테마 없이 구분 기호만, 기본은 꺼짐). Nerd Font가 설치돼 있지 않은 터미널에서는 화살표가 깨져 보일 수 있으니 켜본 뒤 확인하세요
• claudetower uninstall — 등록된 상태표시줄 설정만 안전하게 제거(다른 Claude Code 설정은 그대로 둠)
• claudetower statusline — Claude Code가 내부적으로 호출하는 렌더러(직접 실행할 일 없음)

setup을 실행하면 /claudetower-widgets라는 대화형 명령도 함께 설치됩니다. 클로드코드 채팅창에 /claudetower-widgets라고 치거나 "상태표시줄에서 컨텍스트랑 비용 꺼줘", "갱신 속도를 느리게 해줘"처럼 말하면, AI가 지금 상태를 보여주고 대화하면서 대신 켜고 끄거나 속도를 조절해줍니다 — 터미널을 열거나 영어 명령어를 외울 필요가 없습니다. /claudetower-widgets만 딱 치고 아무 말도 안 하면, 무엇을 켜고 끌지 체크 메뉴(선택지에 마우스나 화살표로 체크)가 떠서 골라 고를 수도 있습니다(체크한 항목만 바뀌고, 체크 안 한 항목은 그대로 유지).

accounts 등 계정 관련 명령은 존재하지 않습니다(계정 자동전환 기능을 만들지 않기로 확정했기 때문입니다 — 아래 "② 계정 자동전환" 참고).

claudetower setup을 다시 실행하면 됩니다. 원하는 항목만 켜고(Y) 나머지는 끄면(n) 바로 반영됩니다 — 별도의 "설정 변경" 명령은 따로 없고 setup이 그 역할을 겸합니다.

git clone https://github.com/sodam-ai/ClaudeTower.git
cd ClaudeTower
npm install
npm run build

dist/ 폴더에 여러분 운영체제에 맞는 실행파일이 생깁니다. 이후 npm run verify로 lint·모듈경계·테스트를 한 번에 확인할 수 있습니다.

• 아무것도 외부로 전송하지 않습니다. 여러분 컴퓨터 안에서만 동작합니다.
• Claude Code가 매번 상태표시줄 프로그램에 현재 상황(프로젝트 경로, 컨텍스트 사용량 등)을 전달하면, 그 값을 화면에 예쁘게 보여주기만 합니다 — 저장하지 않습니다.

이 프로그램은 처음부터 "상태표시줄" 부분과 "계정전환" 부분을 완전히 분리해서 설계했습니다. "상태표시줄 방"은 화면에 정보를 보여주기만 하는 방이라 늘 안전합니다. "계정전환 방"은 설계 구상만 있었을 뿐 실제로 지어진 적이 없으며, 아래 "② 계정 자동전환"에서 설명하는 이유로 앞으로도 짓지 않기로 확정되었습니다.

원래 이 프로젝트는 여러 개의 Claude 계정을 자동으로 바꿔가며 쓸 수 있게 해주는 기능을 나중에 추가할 계획이었습니다. 하지만 2026-07-15에 Anthropic(Claude를 만든 회사)의 공식 이용약관을 직접 확인해본 결과, 이 기능을 안전하게 만들 방법이 없다는 것을 확인했습니다.

• Anthropic은 서드파티(외부) 프로그램이 구독제(Free·Pro·Max) 계정으로 로그인해서 그 계정을 대신 사용하는 것을 명시적으로 금지하고 있습니다. 2026-01-09부터는 이를 서버에서 기술적으로도 차단하고 있다는 사실을 여러 매체를 통해 교차 확인했습니다.
• 또한 API 키가 아닌 방식으로 자동화 스크립트가 서비스에 접근하는 것 자체도 별도로 금지되어 있어서, 로그인 정보를 직접 다루지 않는 우회 방법(예: 로그인은 Claude Code 자체 기능에 맡기고 설정 폴더만 자동으로 바꾸는 방식)을 시도하더라도 이 조항에 걸립니다.

정리하면, "여러 구독제 계정을 자동으로 돌려쓰는" 원래 목표를 규칙을 어기지 않고 구현할 방법이 없었습니다. 그래서 이 기능은 만들지 않기로 확정했습니다 — 나중에 다시 검토할 계획도 없습니다. 상태표시줄 기능은 이 결정과 무관하게 계속 정상적으로 작동합니다.

정식 출시(릴리스)된 버전별 변경 내용입니다(현재 최신: v0.3.0). 항목을 클릭하면 펼쳐집니다. 전체 이력과 상세 설명은 GUIDE.md 11장을 참고하세요.

• 상태표시줄이 안 보여요: Claude Code와 새로 상호작용을 한 번 해보세요(설정은 즉시 반영되지 않고 다음 상호작용부터 반영됩니다).
• /claudetower-widgets(채팅으로 위젯 켜고 끄기)가 갑자기 안 돼요: 근본 원인을 확정했습니다 — 이 프로그램 자신의 자동 검증 절차가 실수로 실제 설정 파일을 지우는 결함이었습니다(사용자 잘못이 아닙니다). 재발 방지 코드와, 혹시 사라져도 몇 초 안에 스스로 되살리는 자가복구를 모두 적용했습니다(다음 정식 릴리스에 포함 예정). 지금 버전에서 겪으신다면 claudetower setup을 다시 실행하면 즉시 복구됩니다.
• claudetower status에서 "등록은 되어 있으나 실행 파일을 찾을 수 없습니다(고장 상태)"가 떠요: 설치 파일이 있던 자리를 지웠거나 옮긴 경우입니다. claudetower setup을 다시 실행하면 자동으로 복구됩니다.
• exe를 더블클릭했는데 창이 바로 꺼져요: 인자 없이 실행하면 도움말만 보여주고 끝납니다 — 실제로 쓰려면 터미널을 열어서 claudetower-win-x64.exe setup처럼 명령을 직접 입력해야 합니다.
• npm run build가 실패해요(개발자용): node --version으로 22 이상인지 확인하세요.
• Windows에서 실행파일 실행 시 경고가 떠요: 아직 디지털 서명이 없어 "알 수 없는 게시자" 경고가 뜰 수 있습니다. "추가 정보" → "실행"으로 진행하세요(정식 서명 배포 전까지는 정상입니다).
• 컨텍스트 퍼센트가 이상해요: 세션 초반이나 /compact 직후에는 값이 비어있을 수 있습니다(정상 동작, Claude Code 공식 동작 방식).

• 설치하면 자동으로 제 계정 정보를 가져가나요? 아니요. 계정 관련 코드는 이 버전에 아예 포함되어 있지 않습니다.
• 인터넷으로 뭔가 전송되나요? 아니요, 전부 로컬에서만 동작합니다.
• 계정 자동전환 기능을 만들 계획이 있나요? 아니요. 검토 끝에 법적 문제로 만들지 않기로 확정했습니다(자세한 이유는 위 "② 계정 자동전환" 참고).
• 원본 다운로드 파일을 지워도 정말 괜찮나요? 네, setup을 한 번 실행한 뒤라면 괜찮습니다 — 위 "설치 파일을 지우거나 옮겨도 되나요?" 참고.

• 이 프로그램은 Anthropic의 공식 제품이 아닙니다. 개인이 만든 비공식 보조 도구이며, Anthropic과 제휴·후원 관계가 없습니다.
• 라이선스: Apache License 2.0 (저작권자: SoDam AI Studio — LICENSE 참고)
• 이 프로젝트는 개인 사용을 목적으로 하며, 상업적 판매·유료 서비스화는 계획에 없습니다.
• 라이선스(Apache 2.0)는 상업적 사용을 법적으로 금지하지 않습니다. 다만 이 프로젝트는 상업적 사용을 권장하지 않습니다 — 둘의 차이는 GUIDE.md 17-7 참고.
• 이 프로젝트의 코드·문서 일부는 AI(Claude Code)의 도움을 받아 작성되었습니다(커밋 기록에 "Co-Authored-By: Claude" 명시). AI 보조 콘텐츠의 저작권·출처는 법리가 아직 확립되지 않은 영역이니, 필요 시 직접 확인하세요.
• 런타임 의존성이 0개라 재배포되는 제3자 코드가 없으므로 별도의 NOTICE 파일을 두지 않습니다.
• 자세한 배경은 .PRD/04_PROJECT_SPEC.md의 "법률·저작권·라이선스·상업적 사용 요구사항" 참고.

이 프로젝트의 설계 배경·의사결정 근거·보안 요구사항은 .PRD/ 폴더에 전부 정리되어 있습니다.