내 Claude Code 사용량을 GitHub 잔디처럼 - token-garden

token-garden이 뭔데?

token-garden은 LLM 토큰 사용량을 GitHub 잔디 스타일로 시각화하는 CLI 도구다.

Claude Code가 남기는 세션 로그를 파싱해서 SQLite에 일별로 저장하고, 터미널에서 1년치 사용 패턴을 한눈에 보여준다.

두 가지 시각화 스타일

Grid — GitHub 잔디 스타일

token-garden view --style grid

52주 × 7일의 격자에 색상 농도로 토큰 사용량을 표현한다. GitHub 잔디와 동일한 방식이다.

사용량 없음: 회색
적음 → 많음: 연한 초록 → 진한 초록 (5단계)

실제 데이터의 백분위수(20/40/60/80/100%)를 기준으로 색상이 결정되기 때문에, 자신의 사용 패턴에 맞게 자연스럽게 분포된다.

월 라벨과 요일 행이 함께 표시되어, 몇 월 며칠에 집중적으로 사용했는지 직관적으로 파악할 수 있다.

Garden — 식물 성장 스타일

token-garden view --style garden

주간 토큰 사용량을 식물 이모지로 표현하는 모드다. 토큰을 많이 쓴 주는 큰 나무가 자라고, 적게 쓴 주는 작은 새싹이 나온다.

주간 토큰	식물
0	(빈 칸)
1 ~ 9,999	🌱 새싹
10,000 ~ 49,999	🌿 풀
50,000 ~ 99,999	🌲 나무
100,000 ~ 199,999	🌳 큰 나무
200,000 이상	🌴 야자수

주 번호와 함께 막대 그래프도 같이 보여줘서, 어떤 주에 가장 활발하게 Claude Code를 사용했는지 한눈에 비교할 수 있다.

어떤 점이 좋은가

1. 장기적인 사용 패턴이 보인다

cctoken 같은 도구가 "지금 얼마나 쓰고 있는지"에 집중한다면, token-garden은 "한 해 동안 어떻게 써왔는지"를 보여준다. 잔디를 보면 자연스럽게 알게 된다 — 프로젝트 마감 전에 토큰을 폭발적으로 쓴다든지, 주말에는 거의 안 쓴다든지.

2. SQLite로 데이터를 관리한다

로그 파일을 매번 파싱하는 게 아니라, sync 명령으로 한 번 파싱해서 SQLite에 저장한다. 그래서 view는 항상 빠르고, 데이터가 쌓여도 성능 걱정이 없다. DB 파일은 ~/.token-garden/db.sqlite에 저장된다.

3. 연도별로 볼 수 있다

token-garden view --year 2025    # 2025년만
token-garden view --year 2026    # 2026년만
token-garden view --all          # 데이터가 있는 모든 연도

작년과 올해의 사용 패턴을 비교해볼 수도 있다.

4. 멀티 프로바이더 구조

현재는 Claude Code 로그만 지원하지만, 내부적으로 프로바이더 패턴으로 설계되어 있다. providers/base.py에 인터페이스가 정의되어 있고, providers/claude.py와 providers/openai.py가 각각 구현체로 존재한다. OpenAI 지원도 준비 중이다.

설치 방법

Homebrew (추천)

brew install token-garden

pipx / pip

pipx install token-garden
# 또는
pip install token-garden

소스에서 설치

git clone https://github.com/HongChaeMin/token-garden.git
cd token-garden
pip install -e .

Python 3.11 이상이 필요하다.

사용법

1단계: 데이터 동기화

token-garden sync

Claude Code의 세션 로그(~/.claude/projects/)를 파싱해서 SQLite에 저장한다. 2020년 1월 1일부터 현재까지의 모든 기록을 수집하므로, 첫 실행 시 과거 데이터도 전부 반영된다.

새로운 사용 기록을 반영하려면 sync를 다시 실행하면 된다. 이미 저장된 데이터는 upsert 방식으로 업데이트되기 때문에 중복 걱정은 없다.

2단계: 시각화

token-garden view                  # 기본: 최근 365일 그리드
token-garden view --style grid     # GitHub 잔디 스타일
token-garden view --style garden   # 식물 성장 스타일
token-garden view --year 2026      # 특정 연도
token-garden view --all            # 전체 연도

프로젝트 구조

token_garden/
├── providers/
│   ├── base.py        # 프로바이더 인터페이스
│   ├── claude.py      # Claude Code 로그 파서
│   └── openai.py      # OpenAI (준비 중)
├── views/
│   ├── grid.py        # GitHub 잔디 스타일 뷰
│   └── garden.py      # 식물 성장 스타일 뷰
├── cli.py             # CLI 엔트리포인트
├── db.py              # SQLite 데이터 관리
└── sync.py            # 로그 동기화 로직

깔끔하게 역할이 분리되어 있어서, 새로운 프로바이더나 뷰 스타일을 추가하기 쉬운 구조다.

기술 스택

Python 3.11+ — 메인 언어
SQLite — 토큰 사용 데이터 저장
Rich — 터미널 UI 렌더링

마무리

코딩을 얼마나 했는지는 GitHub 잔디로 보고, Claude Code를 얼마나 썼는지는 token-garden으로 본다. 매일 터미널에서 AI와 함께 개발하는 시대에, 내 AI 사용 습관을 시각적으로 돌아보는 것도 의미가 있지 않을까.

sync 한 번, view 한 번이면 내 1년치 토큰 잔디가 펼쳐진다.

GitHub: https://github.com/HongChaeMin/token-garden

목차

태그