juliantanx/aiusage

Claude Code, Codex, OpenClaw, OpenCode, Hermes, 그리고 Qoder에 걸친 AI 코딩 어시스턴트(AI coding assistant)의 사용량, 토큰 소비량, 비용, 그리고 도구 호출(tool calls)을 추적하세요.

aiusage는 토큰, 비용, 모델 구성(model mix), 도구 활동, 프로젝트, 세션, 그리고 필요 시 멀티 머신 동기화(multi-machine sync)를 통해 사용자의 AI 코딩 도구가 어떻게 사용되고 있는지 이해할 수 있는 단 하나의 로컬 우선(local-first) 공간을 제공합니다.

English | 中文

사전 요구 사항: Node.js 18 이상

npm install -g @juliantanx/aiusage
aiusage parse
aiusage serve

대시보드를 탐색하려면 http://localhost:3847을 여세요.

aiusage가 유용하다면, 더 많은 개발자가 발견할 수 있도록 저장소(repo)에 스타(star)를 눌러주세요.

aiusage는 내장된 백그라운드 파서(background parser)를 실행하지 않습니다. 자동 임포트(automatic imports)를 원한다면, cron 또는 작업 스케줄러(Task Scheduler)를 사용하여 aiusage parse를 예약하세요.

소스에서 빌드하기

git clone https://github.com/juliantanx/aiusage.git
cd aiusage
pnpm install
...

업데이트를 가져온 후에는 변경 사항을 적용하기 위해 다시 빌드하세요:

pnpm build

로컬에서 Node.js 버전을 전환하는 경우, 새 버전에 맞춰 better-sqlite3 네이티브 모듈(native module)을 다시 컴파일하세요:

pnpm rebuild:sqlite

이는 소스에서 개발할 때만 필요합니다. npm install -g를 통해 설치하는 사용자는 이 작업을 수행할 필요가 없습니다. 모듈은 설치 중에 자동으로 컴파일됩니다.

AI 코딩 어시스턴트의 사용량은 기본적으로 분산되어 있습니다: 서로 다른 도구, 서로 다른 로컬 로그, 서로 다른 머신, 그리고 토큰이나 비용에 대한 공유된 뷰(view)가 없습니다.

aiusage는 해당 데이터를 하나의 로컬 우선 대시보드로 가져와 다음과 같은 작업을 가능하게 합니다:

• 토큰 사용량, 비용, 모델 구성, 도구 호출(tool-call) 활동을 한 곳에서 추적합니다.
• Claude Code, Codex, OpenClaw, OpenCode, Hermes, 그리고 Qoder에 걸친 사용량을 집계합니다.
• 개요(overview), 토큰, 비용, 모델, 세션 및 프로젝트 뷰를 통해 시간에 따른 사용량을 이해합니다.
• 공유 가시성이 중요한 경우 GitHub, S3 또는 R2를 통해 여러 머신 간에 동기화합니다.
• 기본적으로 데이터를 로컬에 유지하며, 선택적으로만 동기화를 수행합니다.

aiusage는 다음을 위해 구축되었습니다:

• Claude Code, Codex 또는 기타 AI 코딩 어시스턴트 (AI coding assistants)를 매일 사용하는 개발자.
• 시간에 따른 토큰 사용량 (token usage) 및 지출을 시각화하고 싶은 사람.
• 여러 개의 분리된 로그 대신 하나의 대시보드를 원하는 멀티 툴 (Multi-tool) 사용자.
• 선택적 집계 및 동기화가 필요한 멀티 머신 (Multi-machine) 워크플로우.

aiusage는 현재 다음을 지원합니다:

• Claude Code
• Codex
• OpenClaw
• OpenCode
• Hermes
• Qoder

aiusage를 사용하여 다음을 수행하세요:

• 여러 AI 코딩 어시스턴트 전반의 토큰 및 비용 트렌드 추적.
• 시간에 따른 모델 사용량 및 활동 비교.
• 툴 콜 (tool-call) 볼륨 및 세션 레벨 동작 조사.
• 여러 머신의 사용량을 하나의 뷰로 집계.
• 지속적인 가시성을 위해 로컬 또는 Docker 기반 대시보드 실행.

터미널에 사용량 요약을 출력합니다 (aiusage summary와 동일).

발견된 소스 경로로부터 새로 추가된 로컬 세션 데이터를 가져옵니다.

옵션	설명
--tool <tool>	특정 툴만 파싱합니다: claude-code, codex, openclaw, opencode, hermes, qoder
--progress	stderr에 실시간 진행률 표시줄을 표시합니다 (TTY 전용, 파이프/CI 환경에서는 무음)

aiusage parse # 모든 툴 파싱
aiusage parse --tool claude-code # Claude Code 로그만 파싱
aiusage parse --progress # 파싱 중 진행률 표시줄 표시

로컬 웹 대시보드 및 런타임 설정 컨트롤러를 시작합니다.

옵션	설명	기본값
-p, --port <port>	포트 번호	3847

aiusage serve # 3847 포트에서 시작
aiusage serve -p 8080 # 8080 포트에서 시작

터미널에 사용량 요약을 출력합니다.

옵션	설명
--device <id>	디바이스 인스턴스 ID로 필터링
--tool <tool>	툴 유형으로 필터링

aiusage summary # 전체 기간 요약
aiusage summary --tool claude-code # 단일 툴 요약

버전, 디바이스 이름, DB 경로, 스키마 버전, 테이블/뷰 개수, 레코드 개수, DB 크기 및 동기화 상태를 표시합니다.

레코드를 CSV, JSON 또는 NDJSON으로 내보냅니다.

옵션 (Option)	설명 (Description)	필수 여부 (Required)
--format <format>	출력 형식 (Output format): csv, json, ndjson	예 (Yes)
-o, --output <file>	출력 파일 경로 (기본값: stdout)	아니오 (No)

aiusage export --format csv # CSV를 stdout으로 출력
aiusage export --format json -o report.json # JSON을 파일로 저장
aiusage export --format ndjson # NDJSON을 stdout으로 출력

연령(age)을 기준으로 로컬 데이터베이스에서 오래된 레코드를 삭제합니다.

옵션 (Option)	설명 (Description)	기본값 (Default)
--before <duration>	이 기간보다 오래된 데이터를 삭제합니다 (예: 30d, 180d)	180d

aiusage clean # 180일보다 오래된 레코드 삭제
aiusage clean --before 30d # 30일보다 오래된 레코드 삭제
aiusage clean --before 90d --yes # 90일보다 오래된 레코드 삭제, 확인 절차 생략

모든 파싱된 레코드(parsed records), 도구 호출(tool calls), 동기화된 데이터(synced data) 및 파싱 워터마크(parse watermark)를 삭제합니다. 소스 로그 파일(~/.claude, ~/.codex 등)은 영향을 받지 않습니다. 모든 데이터를 처음부터 다시 가져오려면(re-import) 이 명령을 사용하세요.

옵션 (Option)	설명 (Description)
--yes	확인 프롬프트 생략 (실행을 위해 필요)

aiusage reset --yes # 모든 데이터를 삭제한 후, aiusage parse를 실행하여 다시 가져오기

최신 가격 데이터를 사용하여 비용을 재계산합니다.

aiusage recalc

여러 기기의 데이터 집계(aggregation)를 위한 동기화 백엔드(sync backend)를 설정합니다.

옵션 (Option)	설명 (Description)
--backend <backend>	동기화 백엔드 (Sync backend): github, s3, skip
--repo <repo>	GitHub 저장소 (형식: username/repo-name)
--token <token>	GitHub 개인 액세스 토큰 (Personal Access Token)
--bucket <bucket>	S3 버킷 이름
--prefix <prefix>	S3 객체 접두사 (기본값: aiusage/)
--endpoint <endpoint>	S3 엔드포인트 URL
--region <region>	S3 리전 (기본값: auto)
--access-key-id <id>	S3 액세스 키 ID
--secret-access-key <key>	S3 비밀 액세스 키
--device <alias>	기기 별칭 (Device alias)

aiusage init --backend github --repo user/aiusage-data --token ghp_xxx
aiusage init --backend s3 --bucket my-bucket --endpoint https://xxx.r2.cloudflarestorage.com --access-key-id AKIAxxx --secret-access-key xxx

설정된 원격 백엔드 (remote backend)를 통해 데이터를 Push 및 Pull 합니다.

aiusage sync

aiusage serve
# http://localhost:3847 접속

aiusage serve는 다음 대시보드 (dashboard) 페이지들을 호스팅합니다:

Home (— 실시간 카운터 홈페이지. 처음 로드될 때 /api/refresh를 호출하여 로컬에서 한 번의 증분 파싱 (incremental local parse)을 실행한 후 요약 데이터를 로드합니다. 그 이후에는 설정된 대시보드 폴링 간격 (dashboard poll interval)에 따라 새로고침됩니다.**)

Overview (— 오늘, 이번 주, 이번 달, 지난 30일 또는 전체 기간에 대한 총계, 비용, 활성 일수 및 도구별 상세 내역. /overview)

Tokens— 유형별 상세 내역 또는 통합 합계 뷰를 포함한 시간 경과에 따른 토큰 사용량 추세.

Cost— 도구별 및 모델별 상세 내역을 포함한 비용 추세.

Models— 모델 점유율 및 분포.

Tool Calls— 도구 호출 (tool call) 빈도 및 순위.

Projects— 프로젝트 수준의 사용량 집계 (rollups).

Sessions— 필터 및 페이지네이션 (pagination)을 지원하는 세션 브라우징.

Pricing— 활성 모델 가격 참조.

Settings— 설정 파일을 수동으로 편집하지 않고도 기기 이름, 주 시작 요일, 대시보드 폴링 간격, 자동 파싱 간격, 소스 경로, 동기화 백엔드, 자격 증명 (credentials) 및 로컬 데이터 보관 정책을 구성합니다.

Docs— CLI 참조 및 기능 가이드가 포함된 앱 내 문서.

Settings 동작 (Settings behavior)

**Dashboard Poll Interval (대시보드 폴링 간격)**은 밀리초 (milliseconds) 단위이며, 초기 로드 이후의 홈페이지 새로고침 주기만 제어합니다.

**Auto-Parse Interval (자동 파싱 간격)**은 밀리초 (milliseconds) 단위이며, aiusage serve가 실행 중인 동안에만 백그라운드에서 aiusage parse 실행을 예약합니다. 비활성화하려면 0으로 설정하거나 빈칸으로 둡니다.

**Local Data Retention (로컬 데이터 보관)**은 aiusage serve가 실행 중인 동안에만 주기적인 정리 (cleanup)를 수행합니다. 데이터를 영구적으로 보관하려면 0으로 설정하거나 빈칸으로 둡니다.

Source path (소스 경로) 변경 사항은 다음 파싱 (parse) 시점에 적용됩니다.

Sync backend and credential (동기화 백엔드 및 자격 증명) 변경 사항은 다음 동기화 (sync) 시점에 적용됩니다.

다중 머신 집계 (multi-machine aggregation) 또는 클라우드 액세스가 필요하신가요? 다음 시나리오 중 하나를 선택하세요:

시나리오	방법	설명
다중 머신, 데이터 집계	Multi-Machine Sync (다중 머신 동기화)	GitHub/S3/R2를 통해 동기화
다중 머신 + 통합 대시보드	Docker Deployment (Docker 배포)	동기화된 데이터로부터 24/7 대시보드 실행

단일 머신 사용의 경우, Quick Start (빠른 시작)만으로 충분합니다.

이 기능을 사용하여 여러 머신의 토큰 사용량을 하나의 대시보드로 집계할 수 있습니다. Claude Code, Codex, OpenClaw, OpenCode, Hermes, 그리고 Qoder와 함께 작동합니다.

Architecture (아키텍처):

Machine A ──┐
Machine B ──┼──▶ GitHub / S3 / R2 (공유 스토리지) ──▶ 모든 머신: aiusage summary / serve
Machine C ──┘

Step 1 — 동기화 백엔드 (sync backend) 선택

Option A: GitHub (권장)

• GitHub에 private (비공개) 리포지토리를 생성합니다 (예: aiusage-data)
• repo 권한(scope)을 가진 Personal Access Token (개인 액세스 토큰)을 생성합니다

Option B: AWS S3 / Cloudflare R2

• S3 또는 R2 버킷을 생성합니다
• 읽기/쓰기 권한을 가진 IAM 사용자 또는 역할을 생성합니다
• Access Key ID, Secret Access Key, 그리고 Endpoint를 기록해 둡니다

Step 2 — 각 머신에 설치 및 구성

Claude Code, Codex, OpenClaw, OpenCode, Hermes, 또는 Qoder를 사용하는 모든 머신에서 다음을 수행합니다:

# aiusage CLI 설치
npm install -g @juliantanx/aiusage
# 동기화 백엔드 구성 — GitHub
...

Step 3 — 각 머신에서 파싱(Parse) 및 동기화(Sync)

aiusage parse
aiusage sync

Step 4 — 어떤 머신에서든 집계된 데이터 확인

aiusage sync
aiusage summary
aiusage serve

Automate (자동화 권장)

# Linux/macOS
crontab -e
# 추가:
...

동기화 작동 방식 (How sync works)

• 각 머신은 첫 실행 시 생성되는 고유한 deviceInstanceId를 가집니다.
• 각 장치는 원격 백엔드의 자체 일일 파일({deviceInstanceId}/YYYY/MM/DD.ndjson)에 기록합니다.
• Pull (가져오기) 과정에서 다른 장치들의 파일을 로컬 synced_records로 읽어옵니다.

테이블; 업로드(upload)는 이 장치의 파일만 기록합니다. - 장치별로 분할된 파일(Device-partitioned files)은 쓰기 충돌을 방지하므로 별도의 잠금(locking)이 필요하지 않습니다.

• 동기화 빈도는 외부 스케줄러 또는 수동 실행에 의해 결정됩니다. aiusage에는 내장된 동기화 데몬(sync daemon)이 포함되어 있지 않습니다.
• 세션 ID(Session IDs)는 sha256(device + sessionId)를 통해 익명화됩니다.

24/7 대시보드를 위해 서버에서 사전 빌드된 이미지를 실행하세요. 컨테이너 자체는 어떠한 AI 코딩 도구도 실행하지 않습니다. 이 컨테이너는 웹 대시보드를 제공하며, aiusage serve와 동일한 런타임 설정 컨트롤러(runtime settings controller)를 실행할 수 있고, GitHub, S3 또는 R2에서 동기화된 데이터를 가져올 수 있습니다.

아키텍처 (Architecture):

Machine A ──┐ ┌── Browser: https://aiusage.your-domain.com
Machine B ──┼──▶ GitHub / S3 / R2 ──▶ Cloud Server (Docker)
Machine C ──┘ └── port 3847

데이터 흐름 (How data flows)

• 각 개발 장치(dev machine)는 로컬 사용 데이터를 업로드하기 위해 aiusage parse && aiusage sync를 실행합니다.
• Docker 컨테이너는 해당 데이터를 로컬 SQLite 데이터베이스로 가져오기 위해 aiusage sync를 실행합니다.
• 웹 대시보드는 로컬 데이터베이스를 읽어 집계된 통계(aggregated stats)를 표시합니다.

Docker 내 데이터 저장 (Data storage in Docker)

항목	컨테이너 경로	설명
데이터베이스 (Database)	/root/.aiusage/cache.db	집계된 사용 데이터가 포함된 SQLite 데이터베이스
설정 (Config)	/root/.aiusage/config.json	동기화 백엔드 설정, 런타임 설정 및 자격 증명
상태 (State)	/root/.aiusage/state.json	동의 및 동기화 런타임 상태
워터마크 (Watermarks)	/root/.aiusage/watermark.json	증분 파싱 커서 (Incremental parse cursors)

모든 데이터는 VOLUME으로 선언된 /root/.aiusage 아래에 저장됩니다. 컨테이너 재시작 시 데이터를 유지하려면 이 볼륨을 반드시 마운트해야 합니다.

1단계 — 이미지 가져오기 및 실행 (Step 1 — Pull image and run)

# 이미지 가져오기 (Pull image)
docker pull juliantanx/aiusage
# 컨테이너 실행 (데이터 유지를 위해 볼륨 마운트)
...

-v 플래그가 없으면 컨테이너가 제거될 때 데이터가 손실됩니다.

2단계 — 예약된 동기화 (Step 2 — Scheduled sync)

# 컨테이너에 cron 설치 및 예약된 작업 생성
docker exec -it aiusage bash -c "apt-get update && apt-get install -y cron"
docker exec -it aiusage bash -c \
...

참고:

parse 명령은 로컬 AI 세션 로그를 컨테이너에 마운트(mount)하지 않는 한 여기서는 필요하지 않습니다. 표준 배포(standard deployment) 방식에서는 원격 백엔드(remote backend)로부터 데이터를 가져오기 위해 sync 명령만 필요합니다.

3단계 — 접속 (Step 3 — Access)

http://<server-ip>:3847을 엽니다.

커스텀 도메인을 사용하는 HTTPS 설정의 경우:

# Caddy (자동 HTTPS, 권장)
caddy reverse-proxy --from aiusage.your-domain.com --to localhost:3847
# 또는 Nginx
...

직접 이미지 빌드하기 (선택 사항)

프로젝트 루트(root)에 Dockerfile이 포함되어 있습니다:

docker build -t aiusage .

항목	경로
로컬 데이터베이스 (Local database)	~/.aiusage/cache.db
...

aiusage parse는 다음 기본 위치에서 세션 로그를 자동으로 탐색(auto-discovers)합니다: