ClaudeTower (가제)

한국어 | English

Claude Code용 상태표시줄 + (예정) 계정 자동전환 CLI 도구.

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

지금 상태(중요): 이 프로젝트는 Phase 1까지만 구현되어 있습니다(현재 버전: v0.1.10). 아래 "① 상태표시줄"은 지금 실제로 동작합니다. "② 계정 자동전환"은 코드 자체가 아직 존재하지 않습니다(꺼져있는 게 아니라 안 만들어졌습니다) — Phase 2에서 사용자 동의 절차와 함께 추가될 예정입니다.

① 상태표시줄 (항상 안전, 설치만 하면 끝)

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

예시:

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

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

빠른 시작 — 프로그램 다운로드해서 바로 쓰기 (일반 사용자용, 5단계)

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/)로 자동 복사됩니다.
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을 다시 한 번 실행하면 자동으로 복구됩니다.

명령어 목록 (지금 실제로 있는 것만)

• 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 uninstall — 등록된 상태표시줄 설정만 안전하게 제거(다른 Claude Code 설정은 그대로 둠)
• claudetower statusline — Claude Code가 내부적으로 호출하는 렌더러(직접 실행할 일 없음)

터미널 없이, 클로드코드 채팅창에서 바로 켜고 끄기

setup을 실행하면 /claudetower-widgets라는 대화형 명령도 함께 설치됩니다. 클로드코드 채팅창에 /claudetower-widgets라고 치거나 "상태표시줄에서 컨텍스트랑 비용 꺼줘"처럼 말하면, AI가 지금 상태를 보여주고 대화하면서 대신 켜고 꺼줍니다 — 터미널을 열거나 영어 명령어를 외울 필요가 없습니다.

accounts, config 등 계정 관련 명령은 아직 존재하지 않습니다(Phase 2 예정).

표시 항목을 나중에 바꾸고 싶으면

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가 매번 상태표시줄 프로그램에 현재 상황(프로젝트 경로, 컨텍스트 사용량 등)을 전달하면, 그 값을 화면에 예쁘게 보여주기만 합니다 — 저장하지 않습니다.

아키텍처 (비유로 설명)

이 프로그램은 두 개의 완전히 분리된 방으로 나뉘어 있습니다. "상태표시줄 방"은 화면에 정보를 보여주기만 하는 방이라 늘 안전합니다. "계정전환 방"은 아직 지어지지도 않았습니다 — 나중에 지어지더라도 상태표시줄 방과는 열쇠가 통하지 않는 별도의 방입니다. 코드 검사 도구(ESLint)와 자동 테스트가 매번 두 방 사이에 몰래 문이 생기지 않았는지 확인합니다.

② 계정 자동전환 (Phase 2 예정, 아직 없음)

이 기능은 코드 자체가 아직 존재하지 않습니다. 완성되면 "여러분의 Claude 계정이 정지될 수도 있는 위험이 있습니다. 켜지 않아도 상태표시줄은 정상 작동합니다"라는 경고와 함께 명시적 동의 절차를 거쳐야만 켤 수 있도록 설계되어 있습니다(자세한 설계는 .PRD/01_PRD.md 참고).

트러블슈팅

• 상태표시줄이 안 보여요: Claude Code와 새로 상호작용을 한 번 해보세요(설정은 즉시 반영되지 않고 다음 상호작용부터 반영됩니다).
• claudetower status에서 "등록은 되어 있으나 실행 파일을 찾을 수 없습니다(고장 상태)"가 떠요: 설치 파일이 있던 자리를 지웠거나 옮긴 경우입니다. claudetower setup을 다시 실행하면 자동으로 복구됩니다.
• exe를 더블클릭했는데 창이 바로 꺼져요: 인자 없이 실행하면 도움말만 보여주고 끝납니다 — 실제로 쓰려면 터미널을 열어서 claudetower-win-x64.exe setup처럼 명령을 직접 입력해야 합니다.
• npm run build가 실패해요(개발자용): node --version으로 22 이상인지 확인하세요.
• Windows에서 실행파일 실행 시 경고가 떠요: 아직 디지털 서명이 없어 "알 수 없는 게시자" 경고가 뜰 수 있습니다. "추가 정보" → "실행"으로 진행하세요(정식 서명 배포 전까지는 정상입니다).
• 컨텍스트 퍼센트가 이상해요: 세션 초반이나 /compact 직후에는 값이 비어있을 수 있습니다(정상 동작, Claude Code 공식 동작 방식).

자주 묻는 질문 (FAQ)

• 설치하면 자동으로 제 계정 정보를 가져가나요? 아니요. 계정 관련 코드는 이 버전에 아예 포함되어 있지 않습니다.
• 인터넷으로 뭔가 전송되나요? 아니요, 전부 로컬에서만 동작합니다.
• 나중에 계정 자동전환 기능이 생기면 자동으로 켜지나요? 아니요. 여러분이 직접 동의해야만 켜지도록 설계되어 있습니다.
• 원본 다운로드 파일을 지워도 정말 괜찮나요? 네, setup을 한 번 실행한 뒤라면 괜찮습니다 — 위 "설치 파일을 지우거나 옮겨도 되나요?" 참고.

법률·저작권·라이선스

• 이 프로그램은 Anthropic의 공식 제품이 아닙니다. 개인이 만든 비공식 보조 도구이며, Anthropic과 제휴·후원 관계가 없습니다.
• 라이선스: Apache License 2.0 (저작권자: SoDam AI Studio — LICENSE 참고)
• 이 프로젝트는 개인 사용을 목적으로 하며, 상업적 판매·유료 서비스화는 계획에 없습니다.
• 자세한 배경은 .PRD/04_PROJECT_SPEC.md의 "법률·저작권·라이선스·상업적 사용 요구사항" 참고.

더 자세한 설계 문서

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