tokenarchive

AI 코딩 사용량의 일일 스냅샷, 영원히 보관됩니다.

ccusage는 Claude Code, Codex, Gemini 등의 비용을 알려줄 수 있습니다 — 하지만 로컬 머신에 있는 로그까지만 가능하며, 그 로그는 순환됩니다. tokenarchive는 ccusage 리포트를 하루에 한 번 스냅샷으로 저장하고, 모든 스냅샷을 추가 전용 JSON 아카이브로 보관하며, 이를 바탕으로 대시보드를 렌더링합니다. 선택적으로 Cloudflare Worker가 아카이브 사본을 머신 밖에 패스키 뒤에 보관합니다.

여기 있는 모든 것을 이끄는 두 가지 원칙:

• 어떤 것도 지워지지 않습니다. 스냅샷이 곧 아카이브이며, 모든 데이터베이스는 스냅샷에서 재구축할 수 있는 파생 복사본입니다.

• 부재가 0으로 보고되지 않습니다. 스냅샷이 없는 날은 그렇게 표시됩니다. $0.00라고 표시하면 우리가 확인해 봤는데 아무것도 쓰지 않았다고 주장하는 셈입니다.

빠른 시작 (macOS)

npx tokenarchive

설치 프로그램은 기기 이름과 선택적 Worker URL을 요청하고, 런타임을 ~/.local/share/tokenarchive/app에 배치하며, 일일 작업(23:50 및 로그인 시마다 — 스크립트는 멱등)을 예약하고, security가 ingest 토큰을 묻도록 하여 설치 프로그램의 손을 거치지 않게 하며, 실제 실행 한 번으로 전체를 검증합니다. 재구성이 필요하면 언제든 다시 실행하세요. --uninstall은 아카이브를 제외한 모든 것을 제거합니다.

스냅샷은 ~/.local/share/tokenarchive/{device}/{date}.json에 저장됩니다. 아무것도 설치하지 않고 한 번만 시도하려면:

git clone https://github.com/ddyy/tokenarchive && cd tokenarchive && ./snapshot.sh

다른 플랫폼: 스케줄링 접착 코드를 제외한 모든 것이 이식 가능합니다. sync.js, 임포터, 대시보드는 순수 Node입니다. snapshot.sh를 systemd 타이머나 cron 작업으로 포팅하면 나머지도 따라옵니다.

Related MCP server: Semantic Code Search MCP Server

대시보드

generate-dashboard.js는 단일 자체 포함 HTML 파일을 빌드합니다 — 프레임워크 없음, 서버 없음, 외부 요청 없음. 먼저 새 스냅샷을 로컬 SQLite 읽기 모델(import-snapshots.js)로 가져온 다음 증분 방식으로 재생성합니다.

모든 패널은 필터입니다: 모델, 기기, 에이전트, 일자 또는 결제 기간을 클릭하거나 드래그하면 페이지의 나머지가 따라옵니다(⌘는 선택 추가, ⇧는 범위 확장). 필터는 차원 간 AND로 결합되며 URL 프래그먼트에 저장되므로 보기를 북마크할 수 있습니다.

표시 전환 — 합계 위와 스크롤 시에도 나타나는 고정 바에 있는 — 은 페이지 전체를 달러 또는 토큰 단위로 측정합니다: 차트와 축, 적용 범위 음영, 그리고 순서가 바뀌는 모든 목록까지. 행 위에 마우스를 올리면 잘려 있던 전체 이름, 비용, 토큰, 산출된 백만 토큰당 요율, 화면에서 차지하는 비율, 그리고 프로젝트의 경우 세션 수와 해당 기간이 표시됩니다:

커버리지 스트립은 날짜별 셀 하나로 표시되므로, 공백이 그대로 보입니다 — 스냅샷이 없는 날은 사용량 0일로 그려지지 않습니다:

여러 기기

아카이브는 파일 시스템부터 기기별로 분할됩니다: 스냅샷은 {data}/{device}/{date}.json에 저장되고, 모든 데이터베이스 행에는 기기가 포함되며, 가져오기는 upsert 전용입니다. 따라서 머신끼리 병합되거나 덮어써지지 않으며, 두 머신의 파일이 하나의 데이터 디렉터리에 함께 들어가면 결합된 아카이브가 됩니다 — Worker, 동기화 폴더, 복사된 디렉터리 모두 동일하게 작동합니다.

건강 상태는 기기별로 판단됩니다. 각 기기는 고유한 초록/노랑/빨강 점, 고유한 마지막 스냅샷 날짜, 고유한 누락 일수 목록을 가지므로, 한 기기가 최신이라 해서 조용해진 다른 기기를 숨길 수 없습니다. 보고를 중단한 기기의 모든 기록은 유지됩니다 — 아카이브는 절대 지우지 않으며, 그저 공백을 보여줄 뿐입니다.

아래의 Worker는 파일을 직접 옮기지 않고 이 작업을 수행하는 방법입니다.

Worker

worker/ 디렉토리는 Cloudflare Worker로, 스냅샷 푸시를 수락하고 WebAuthn 패스키 뒤에서 동일한 대시보드를 D1에서 제공합니다. 원본 스냅샷은 R2에 그대로 보관됩니다 — 이것이 단순한 뷰가 아닌 백업인 이유입니다: /admin/replay는 노트북 없이 버킷에서 D1을 재구축할 수 있습니다. 다섯 가지 명령으로 배포하는 방법은 worker/README.md를 참조하세요.

배포 후 /auth에서 패스키를 등록하세요. 첫 번째 패스키가 아카이브를 소유합니다. 다른 기기를 추가하려면 로그인 상태에서 패스키를 등록하면 됩니다. 그런 다음 /admin에서 기기별 ingest 토큰을 생성하세요(토큰 표시에 설정 지침이 포함됩니다). 동기화하지 않는 머신도 아무것도 잃지 않습니다 — 파일 자체가 아카이브이며, 다음 동기화 성공 시 모두 따라옵니다. ingest는 최신 데이터를 덮어쓸 수 없습니다 — 이전 데이터가 최신 데이터를 덮어쓰지 않도록 보호됩니다.

/admin은 나머지를 관리합니다: ingest 토큰(한 번만 표시되며 기기별로 폐기 가능), 스냅샷 인벤토리, 그리고 /admin/replay — R2의 원본에서 D1을 재구축합니다.

두 번째 머신을 추가하려면 동일한 Worker URL로 설치 프로그램을 실행하고 해당 기기 전용 ingest 토큰을 발급받으세요. 토큰은 발급된 기기로만 ingest할 수 있으므로, 하나를 해지해도 다른 기기는 영향을 받지 않습니다.

MCP

에이전트에게 자신의 사용량을 물어보세요. 네 가지 읽기 전용 도구(usage_summary, usage_by_project, usage_by_day, archive_health)와 하나의 공유 구현체가 있습니다:

• 로컬 — 이 머신의 SQLite 아카이브를 대상으로:

  claude mcp add tokenarchive node /path/to/tokenarchive/mcp-server.js

• 원격 — 아카이브를 보관하지 않는 머신용으로 Worker가 /mcp에서 제공:

  claude mcp add --transport http tokenarchive https://YOUR-WORKER/mcp \
    --header "Authorization: Bearer YOUR-TOKEN"

기본적으로 읽기 전용입니다: 쓰기, 삭제 또는 재작성하는 도구는 존재하지 않습니다.

설정

모든 항목은 환경 변수로 덮어쓸 수 있으며, 필수 항목은 없습니다:

테스트

bash test/run.sh

대부분의 스위트는 자체 포함입니다. 세 개(static, interaction, tooltip)는 ~/.local/share/tokenarchive/index.html에서 마지막으로 생성한 대시보드를 대상으로 실행되므로, 머신에 실제 아카이브가 필요합니다 — 먼저 스냅샷을 한 번 실행하세요.

라이선스

MIT