SynapCap

Codex, Gemini, Claude의 구독 사용량을 한눈에 보는 가벼운 데스크톱 위젯

SynapCap은 로컬에 로그인된 AI 도구의 구독 한도와 리셋 시각을 표시합니다. 개발자 API의 과금액을 계산하는 앱이 아니며 API 키도 요구하지 않습니다.

주요 기능

Codex, Gemini, Claude 사용량을 동일한 사용량 % 기준으로 표시
서비스가 제공하는 5시간 한도와 주간 한도를 각각 표시
Codex 최신 App Server가 제공하는 5시간·주간 한도를 모두 지원하며 기존 설정은 업데이트 후 5시간 표시를 한 번 자동 활성화
상단 탭에서 모델을 고르는 가로 한 모델 집중 듀얼 링 그래프
리셋까지 남은 시간을 간결하게 표시
항상 위에 고정 및 갱신 주기 설정
펼친 위젯은 384px 고정 폭의 가로 한 모델 집중 링 보기로 제공
프로바이더별 5시간·주간 한도 표시 여부 설정
선택형 사용량 임계치 알림: 기본 비활성화, 50~100% 기준 설정, 같은 한도는 하락 후 재상승할 때만 다시 알림
상태 배지를 눌러 감지된 CLI 경로·최근 조회·설치 및 로그인 안내를 확인하고 토큰 없는 진단 정보 복사
시스템 트레이에서 표시, 새로고침, 업데이트 확인, 재시작, 설정, 종료
트레이와 환경설정에서 버그·기능 제안·기타 의견용 GitHub Issue 작성 화면 열기
작업표시줄·Alt+Tab 또는 Dock에는 표시하지 않는 트레이 전용 동작
상단 버전 배지와 트레이 메뉴에서 시작하는 검증형 원클릭 업데이트
어두운 바탕에서도 또렷한 브랜드 아이콘과 설정한 5시간·주간 사용률을 함께 표시하는 반응형 컴팩트 모드
화면 위치에 따라 위·아래 펼침 방향을 자동 선택하고 가장자리 가까이에서 달라붙는 위젯 스냅
전체 화면 경계를 넘지 않도록 자동 보정하며, 작업 표시줄·Dock 위에도 자유롭게 배치 가능
설정을 저장하기 전에 크기·표시 옵션을 위젯에 바로 적용해 보는 적용 기능
Windows·macOS 공통 환경설정 디자인과 종료 확인창
Windows CLI 콘솔 숨김 및 시간 초과 프로세스 정리
중복 실행 시 새 프로세스를 종료하고 기존 위젯을 앞으로 표시
업데이트 후 최초 한 번 새 버전 안내와 정확한 GitHub 릴리스 링크 제공

다운로드

운영체제	설치 파일
Windows 10/11 64비트	`SynapCap-Windows-x64-Setup.exe`
macOS Apple Silicon	`SynapCap-macOS-arm64.dmg`
macOS Intel	`SynapCap-macOS-x64.dmg`

초기 버전은 코드 서명 전이므로 Windows SmartScreen 또는 macOS Gatekeeper 경고가 표시될 수 있습니다. 설치 파일과 함께 제공되는 SHA256SUMS.txt로 파일 무결성을 확인할 수 있습니다.

앱에서 업데이트

새 버전이 있으면 상단 버전 배지와 트레이 메뉴에 표시됩니다. 업데이트를 누르면 현재 운영체제에 맞는 공식 GitHub Release 설치 파일과 SHA256SUMS.txt를 내려받아 SHA-256을 확인합니다. 파일명, Release 주소 또는 체크섬이 하나라도 다르면 설치하지 않고 기존 버전을 그대로 유지합니다.

Windows: 관리자 권한 확인(UAC) 후 설치를 자동으로 진행하고 SynapCap을 다시 실행합니다.
macOS: 현재 앱이 Apple 개발자 서명·공증 전이므로 검증된 DMG까지 자동으로 엽니다. DMG에서 SynapCap을 응용 프로그램 폴더로 드래그해 기존 앱을 교체합니다.

설정에서 자동 업데이트 확인을 끌 수 있습니다. 활성화하면 시작 4초 후와 실행 중 6시간마다 새 버전을 확인하며, 트레이의 업데이트 확인은 설정과 관계없이 언제든 사용할 수 있습니다. 업데이트 파일은 사용자가 설치를 선택한 경우에만 다운로드합니다.

Note

원클릭 업데이트 기능이 들어 있지 않은 v0.1.4 이하에서는 이번 한 번 최신 Release 설치 파일을 직접 받아야 합니다. 원클릭 업데이트가 포함된 버전으로 올라온 뒤부터는 앱 안에서 다음 업데이트를 진행할 수 있습니다.

Windows 다운로드 경고

Edge의 일반적으로 다운로드되지 않습니다 표시는 악성 파일 판정이 아니라 아직 코드 서명과 다운로드 평판이 없는 새 설치 파일이라는 의미입니다. 공식 GitHub Release가 아닌 곳에서 받은 파일은 실행하지 마세요.

공식 Release에서 설치 파일과 SHA256SUMS.txt를 받은 다음 PowerShell에서 해시를 확인할 수 있습니다.

Get-FileHash .\SynapCap-Windows-x64-Setup.exe -Algorithm SHA256
Get-Content .\SHA256SUMS.txt

두 SHA-256 값이 일치하는지 확인합니다. v0.1.4 이상은 GitHub CLI로 빌드 출처도 검증할 수 있습니다.

gh attestation verify .\SynapCap-Windows-x64-Setup.exe -R kimNarr/SynapCap

출처와 해시가 모두 맞을 때만 Edge 다운로드 패널에서 파일의 … 메뉴를 열어 유지 → 더 보기 → 그래도 계속을 선택하세요. 출처나 해시가 다르면 파일을 삭제합니다. 경고 자체를 근본적으로 제거하려면 Microsoft Store 배포 또는 신원 확인을 거친 코드 서명이 필요합니다.

macOS 첫 실행에서 차단되는 경우

현재 macOS 설치본은 Apple 개발자 서명과 공증 전이므로 처음 실행할 때 확인되지 않은 개발자 경고가 나타날 수 있습니다. 공식 GitHub Release에서 받은 파일이고 SHA-256이 일치할 때만 다음 절차를 진행하세요.

DMG를 열고 SynapCap을 응용 프로그램 폴더로 옮깁니다.
응용 프로그램 폴더에서 SynapCap을 한 번 실행합니다. 보안 경고가 나오면 확인 또는 완료를 눌러 닫습니다.
Apple 메뉴 → 시스템 설정 → 개인정보 보호 및 보안으로 이동해 아래쪽 보안 영역까지 스크롤합니다.
SynapCap 차단 안내 옆의 그래도 열기를 누르고 로그인 암호 또는 Touch ID로 승인한 다음, 다시 표시되는 창에서 열기를 선택합니다.

그래도 열기 버튼은 앱 실행을 시도한 뒤 약 1시간 동안 표시됩니다. 승인 후에는 다시 설치할 필요 없이 응용 프로그램 폴더에서 SynapCap을 열면 됩니다. 이 절차는 macOS 보안 기능 전체를 끄지 않고 SynapCap만 예외로 등록합니다. 자세한 내용은 Apple의 공식 안내를 참고하세요.

연동 조건

SynapCap은 웹 채팅 페이지를 읽지 않습니다. 각 서비스의 로컬 도구가 설치되고 같은 사용자 계정으로 로그인돼 있어야 합니다.

표시 이름	필요한 로컬 도구	조회 방식
Codex	Codex CLI, 또는 Windows Codex 앱	Codex App Server의 구독 rate limit
Gemini	Antigravity CLI (`agy`)	`agy --print /usage`
Claude	Claude Code CLI (`claude`)	`claude -p /usage`

Claude 사용량은 Claude Code CLI가 반환한 값을 기준으로 표시합니다. 실행 중인 Claude 화면의 값이 먼저 갱신되고 새 CLI 조회에는 수분 뒤 반영되는 경우가 있으므로, 카드의 CLI 기준 배지나 사용량에 마우스를 올려 마지막 조회 시각을 확인하세요. SynapCap은 값을 임의로 보정하지 않습니다.

웹 ChatGPT, Gemini, Claude만 사용하는 계정은 대상이 아닙니다. SynapCap이 사용량 조회를 위해 별도의 유료 API를 호출하지는 않지만, 각 서비스의 구독 정책과 로컬 CLI 동작은 해당 서비스에 따릅니다.

사용 방법

필요한 로컬 AI 도구를 설치하고 로그인합니다.
SynapCap을 실행합니다.
위젯의 새로고침 버튼으로 즉시 조회하거나 자동 갱신을 기다립니다.
톱니바퀴 버튼에서 프로바이더, 표시할 한도, 갱신 주기, 선택형 사용량 알림, 업데이트 확인 여부를 설정합니다. 펼친 위젯은 384px 고정 폭의 가로 한 모델 집중 링 보기입니다.
접기 버튼은 위젯을 프로바이더별 사용률이 보이는 가로형 컴팩트 바로 바꿉니다. 두 한도를 표시하도록 설정했다면 5시간·주간 순서의 15 / 50% 형식으로 표시되며, 폭은 콘텐츠에 맞춰 자동 조절됩니다. 펼치기 버튼으로 원래 크기로 돌아옵니다. × 버튼은 프로그램을 완전히 종료합니다. 트레이 메뉴에서는 표시·숨기기, 업데이트 확인, 재시작과 종료를 제어할 수 있습니다.

각 카드와 환경설정 목록에는 Codex, Gemini, Claude의 식별용 브랜드 아이콘이 표시됩니다. 조회에 실패하면 카드에 설치 필요, 로그인 필요, 시간 초과 또는 조회 오류가 표시되며 마우스를 올려 상세 원인을 확인할 수 있습니다. macOS 설치본은 Finder에서 실행해도 Homebrew와 사용자 로컬 CLI 경로를 자동 탐색합니다. 사용량 링 위로 마우스를 올리면 사용량 상세 툴팁이 즉시 표시되며, 기간 표식과 리셋 시간은 읽는 흐름을 방해하지 않도록 툴팁을 표시하지 않습니다.

오류 해결

앱 표시	의미	확인 및 조치
`설치 필요`	해당 로컬 CLI 실행 파일을 찾지 못함	아래 설치 명령을 실행하고 `--version`으로 확인한 뒤 CLI를 한 번 실행해 로그인합니다. 사용하지 않는 서비스는 설정에서 비활성화할 수 있습니다.
`로그인 필요`	CLI는 있지만 구독 계정 인증이 없거나 만료됨	터미널에서 `codex`, `agy` 또는 `claude`를 직접 실행하고 브라우저 로그인 절차를 완료합니다. Antigravity가 인증 코드를 보여 주면 복사한 뒤 `agy`가 기다리는 터미널 입력란에 붙여 넣고 Enter를 누릅니다.
`시간 초과`	CLI가 제한 시간 안에 응답하지 않음	네트워크를 확인하고 실행 중인 CLI를 종료한 뒤 SynapCap에서 다시 새로고침합니다. 반복되면 해당 CLI를 직접 실행해 표시되는 오류를 확인합니다.
`조회 오류`	출력 형식 변경 등 그 밖의 오류	상태 배지를 눌러 감지 경로와 해결 안내를 확인합니다. 필요하면 토큰이 없는 진단 보고서를 복사해 GitHub Issue에 첨부합니다.

Important

SynapCap은 Apple Music, 다른 앱의 데이터, 네트워크 볼륨 또는 외장 볼륨 접근 권한이 필요하지 않습니다. macOS에서 이런 권한 요청이 나타나면 허용하지 않음을 선택해도 됩니다. 앱을 완전히 종료한 뒤 MCP 격리 기능이 포함된 최신 버전으로 업데이트하세요.

macOS에서 세 서비스가 모두 설치 필요로 표시되면 터미널에서 필요한 CLI만 설치합니다. Codex 앱과 웹 채팅 로그인만으로는 macOS 사용량을 조회할 수 없습니다.

# Codex CLI
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Antigravity CLI
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash

설치 후 경로와 버전을 확인하고 각 CLI를 한 번 실행해 로그인합니다.

codex --version
agy --version
claude --version

codex
agy
claude

로그인을 마치면 SynapCap을 완전히 종료했다가 다시 실행하고 새로고침합니다. 로그인 후에도 Antigravity만 실패하면 macOS의 키체인 접근 앱에서 Antigravity CLI 항목의 접근 제어 목록에 agy가 허용되어 있는지 확인합니다. v0.1.1 이상은 macOS Finder에서 실행해도 Homebrew, ~/.local/bin, npm·pnpm·Bun·Volta·asdf·nvm 경로를 자동 탐색합니다. 자세한 설치 방법은 Codex CLI, Antigravity CLI, Claude Code 공식 문서를 참고하세요.

데이터와 개인정보

API 키를 입력하거나 SynapCap 서버로 전송하지 않습니다.
구독 사용량은 설치된 로컬 CLI 프로세스에서 읽습니다.
설정은 사용자 컴퓨터에만 저장됩니다.
복사형 진단 보고서는 운영체제·앱 버전·프로바이더·CLI 경로와 조회 오류만 포함하며 토큰과 API 키를 수집하지 않습니다.
자동 업데이트 확인은 시작 4초 후와 실행 중 6시간마다 GitHub의 최신 Release 정보만 조회하며 설정에서 끌 수 있습니다. 트레이에서는 수동으로 즉시 확인할 수 있습니다. 사용자가 설치를 선택하면 운영체제별 자산과 체크섬을 공식 Release에서 내려받아 검증합니다.
SynapCap은 사용자의 MCP 설정을 삭제하거나 일괄 비활성화하지 않습니다. Claude 조회는 빈 MCP 구성으로, Antigravity 조회는 기존 CLI 로그인 상태를 유지하면서 MCP 실행 도구가 제외된 제한 경로와 샌드박스로 실행합니다.

Windows에서 일반 CLI 콘솔은 숨김 처리합니다. Claude는 공식 엄격 MCP 설정으로 실행하며 Antigravity는 macOS Keychain을 포함한 기존 사용자 인증을 그대로 사용합니다. SynapCap의 짧은 Antigravity 조회에서는 별도 자동 업데이터를 실행하지 않습니다. macOS에서는 CLI 탐색 중 Music 같은 보호 폴더나 네트워크·외장 볼륨도 조회하지 않습니다.

소스에서 실행

Python 3.12를 권장합니다.

git clone https://github.com/kimNarr/SynapCap.git
cd SynapCap
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python main.py

macOS:

source .venv/bin/activate
python -m pip install -r requirements.txt
python main.py

설정 파일

설정 파일 위치는 설치 방식에 따라 달라집니다.

환경	위치
Windows 설치본	`%APPDATA%\SynapCap\synapcap.json`
macOS 설치본	`~/Library/Application Support/SynapCap/synapcap.json`
소스 실행	저장소 루트의 `synapcap.json`

전체 형식은 synapcap.example.json을 참고하세요. 실제 설정 파일은 토큰이나 로컬 정보가 섞일 가능성에 대비해 Git에서 제외됩니다.

개발과 테스트

python -m pip install -r requirements-build.txt
python -m unittest discover -s tests -v
python scripts/manage_version.py current

Windows 실행 번들:

.\scripts\build_windows.ps1 -Version 0.1.1 -SkipInstaller

저장소의 주요 구성은 다음과 같습니다.

SynapCap/
├─ main.py                 # 앱 시작과 구성 연결
├─ subscription_usage.py   # 로컬 CLI 사용량 어댑터
├─ providers.py            # 프로바이더와 사용량 모델
├─ diagnostics.py          # 토큰 없는 로컬 CLI 진단 보고서
├─ release_notes.py        # 업데이트 후 1회 변경 사항 안내
├─ single_instance.py      # 중복 실행 방지와 기존 위젯 활성화
├─ usage_alerts.py         # 사용량 임계치 알림 상태 관리
├─ ui/                     # 위젯, 설정, 트레이, 아이콘
├─ workers/                # 백그라운드 갱신 스레드
├─ scripts/                # 빌드와 버전 관리
├─ packaging/              # 운영체제별 설치 패키지 정의
├─ docs/                   # 다운로드 페이지와 릴리스 문서
└─ tests/                  # 단위·UI 테스트

패치와 릴리스

버전은 MAJOR.MINOR.PATCH로 관리합니다. 오류 수정은 0.1.0 → 0.1.1처럼 패치 버전을 올립니다.

python scripts/manage_version.py bump patch
python scripts/manage_version.py check v0.1.1

v* 태그가 푸시되면 GitHub Actions가 앱 버전과 태그를 검증하고 Windows 설치 파일, 두 종류의 macOS DMG, 체크섬과 CHANGELOG 기반 릴리스 노트를 게시합니다. 자세한 절차는 릴리스와 패치 관리 문서를 참고하세요.

의존성 업데이트는 Dependabot이 월별 PR로 제안하며 dev와 main의 변경은 Windows·Linux 테스트를 거칩니다.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
docs		docs
packaging/windows		packaging/windows
scripts		scripts
tests		tests
ui		ui
workers		workers
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
config.py		config.py
diagnostics.py		diagnostics.py
feedback.py		feedback.py
main.py		main.py
providers.py		providers.py
pyproject.toml		pyproject.toml
release_notes.py		release_notes.py
requirements-build.txt		requirements-build.txt
requirements.txt		requirements.txt
single_instance.py		single_instance.py
subscription_usage.py		subscription_usage.py
synapcap.example.json		synapcap.example.json
theme.py		theme.py
updates.py		updates.py
usage_alerts.py		usage_alerts.py
version.py		version.py

Navigation Menu

Repository files navigation

SynapCap

주요 기능

다운로드

앱에서 업데이트

Windows 다운로드 경고

macOS 첫 실행에서 차단되는 경우

연동 조건

사용 방법

오류 해결

데이터와 개인정보

소스에서 실행

설정 파일

개발과 테스트

패치와 릴리스

기여와 보안

라이선스

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

SynapCap

주요 기능

다운로드

앱에서 업데이트

Windows 다운로드 경고

macOS 첫 실행에서 차단되는 경우

연동 조건

사용 방법

오류 해결

데이터와 개인정보

소스에서 실행

설정 파일

개발과 테스트

패치와 릴리스

기여와 보안

라이선스

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages