AI 사용 대시보드

직장에서의 AI 사용 지표 대시보드로, 정확한(청구된) 토큰에 초점을 맞추며, 세션 중 훅에 의해 자동으로 수집됩니다 — 별도 수집기를 실행할 필요도 없고, 계속 실행할 서버도 없습니다.

세 가지 독립적인 계층:

1. 수집(훅 기반) — 종료 훅이 정확한 사용량을 로컬 SQLite 파일에 직접 기록합니다 (lib/db.mjs). 데몬도 HTTP도 없습니다.

2. 저장 — Node 내장 node:sqlite를 통한 단일 SQLite 파일(metrics.db) (네이티브 의존성 없음, 빌드 단계 없음). WAL + busy_timeout으로 동시 훅 작성자와 MCP 리더가 안전하게 공유할 수 있습니다.

3. 조회/분석 — 읽기 전용 MCP 서버(stdio, 클라이언트가 요청 시 생성)로 Claude와 Cursor가 차트(아티팩트/캔버스)를 생성하는 데 사용합니다.

이벤트 계약(src/types.ts)이 세 계층을 연결합니다. 토큰은 일급 필드입니다.

정확한 토큰이 자동으로 도달하는 방식

100% 로컬에서 실행됩니다 — 훅은 수명이 짧은 node 프로세스로, SQLite 파일을 열고 턴의 이벤트를 기록한 후 종료됩니다. 포트를 수신하는 것은 없습니다.

⚠️ Cursor에 API 키가 필요한 이유. Cursor의 청구된 토큰 수는 머신에 존재하지 않습니다: Cursor 훅은 토큰을 받지 못하며, 로컬 DB에는 컨텍스트 추정치만 있습니다. 정확한 숫자는 서버 측(Admin API, Team/Business 플랜)에만 존재합니다. 훅이 그 가져오기를 자동화합니다 — 여전히 아무것도 실행할 필요는 없지만 — 관리자 키가 없으면 활동만 볼 수 있고 토큰은 볼 수 없습니다.

설정

npm install                 # no native build — uses Node's built-in SQLite
npm link                    # puts the ai-usage-* commands on your PATH
cp .env.example .env

npm link는 모든 도구를 이름으로 호출할 수 있는 명령어로 노출합니다(ai-usage-claude-hook, ai-usage-cursor-hook, ai-usage-mcp, ai-usage-stats, …). 따라서 아래 어디에도 이 저장소의 절대 경로가 하드코딩되지 않습니다. 각 명령어는 자신의 위치를 스스로 해석하므로 어떤 디렉토리에서도 작동합니다. (전역 링크를 선호하지 않나요? 저장소에서 npx ai-usage-<name>으로 실행하거나, 경로와 함께 node ./hooks/<file>.mjs로 대체하세요.)

시작할 서비스는 없습니다. 훅은 DB에 직접 기록하고 MCP 서버는 클라이언트가 요청 시 생성합니다. DB는 기본적으로 저장소 루트의 metrics.db입니다. 다른 위치에 두는 경우에만 IA_USAGE_DASHBOARD_DB_PATH를 설정하세요:

export IA_USAGE_DASHBOARD_DB_PATH="$HOME/somewhere/metrics.db"   # optional; the commands find the repo DB by default

1. Claude Code 훅 활성화

~/.claude/settings.json에 훅을 등록합니다:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "ai-usage-claude-hook" }] }
    ],
    "SubagentStop": [
      { "hooks": [{ "type": "command", "command": "ai-usage-claude-hook" }] }
    ]
  }
}

완료 — 이후부터 모든 Claude Code 턴이 정확한 사용량을 자동으로 기록합니다. 훅은 조용하며 Claude Code를 절대 차단하지 않습니다. 쓰기가 실패하면 다음 턴에 재시도할 뿐입니다.

2. Cursor 훅 활성화

~/.cursor/hooks.json(또는 <project>/.cursor/hooks.json)을 생성합니다 — 예시는 hooks/cursor-hooks.example.json에 있습니다:

{ "version": 1, "hooks": { "stop": [{ "command": "ai-usage-cursor-hook" }] } }

Cursor의 정확한 토큰을 위해 관리자 키도 내보냅니다 (Cursor Dashboard → Settings → Cursor Admin API Keys):

export CURSOR_API_KEY=<cursor-admin-key>

3. 읽기 전용 MCP 등록 (Claude / Cursor)

claude mcp add ai-usage -- ai-usage-mcp

Cursor의 경우 저장소에 이미 .cursor/mcp.json이 포함되어 있습니다 (저장소에서 npm run mcp 실행 — 경로 불필요).

클라이언트에서: "token_usage 도구를 사용하고 (기간 30일, group_by model) 막대 차트를 만들어" → 아티팩트/캔버스.

쿼리 도구 (MCP)

이벤트별 캡처되는 지표

• message (Claude Code 및 Cursor): 정확한 토큰, model, 그리고 meta에: stop_reason, latency_ms (턴 시간), n_tools, tools, web_search/web_fetch, gitBranch.

• tool_use: 호출된 도구당 하나 (top_tools/tool_stats에 공급).

• error: 오류가 있는 tool_result당 하나 (분모 = tool_use → 오류율).

• productivity (Cursor, 일별): 추가/수락된 줄, 표시/수락된 탭, 적용.

세션별 작업 (Jira/이슈) 연결

각 AI 세션은 작업에 연결되어 이슈별 AI 노력을 측정합니다. 해석은 세션 시작 시 자동으로, 정밀도 순서대로 수행됩니다:

1. .dash-task — 저장소 루트의 파일에 ID가 있음 (명시적 재정의).

2. Git 브랜치 — 브랜치 이름의 Jira 스타일 ID (feature/PROJ-123-... → PROJ-123).

3. 사용자 프롬프트 — 언급된 ID 또는 명시적 마커 #task PROJ-123 (언제든 수정 가능).

4. 위 중 정확히 해석되는 것이 없으면 → SessionStart 훅이 컨텍스트를 주입하여 Claude가 시작 전에 사용자에게 ID를 묻도록 지시합니다 (최선 노력 — SessionStart 훅은 차단할 수 없으므로 모델이 질문을 건너뛸 수 있음). 묻는지 여부와 관계없이 답변은 UserPromptSubmit 훅이 자체적으로 캡처하므로, 작업을 설정하는 보장된 방법은 .dash-task, 브랜치 이름, 또는 #task PROJ-123입니다.

관련 훅 (~/.claude/settings.json에 등록):

"SessionStart":    [{ "hooks": [{ "type": "command", "command": "ai-usage-session-task" }] }],
"UserPromptSubmit":[{ "hooks": [{ "type": "command", "command": "ai-usage-task-capture" }] }]

ID 패턴은 DASH_TASK_PATTERN (정규식)으로 구성할 수 있습니다. 기본값은 Jira 스타일 (PROJ-123)입니다. task_id는 모든 이벤트의 일급 필드가 됩니다. by_task 또는 token_usage group_by=task_id로 쿼리하세요.

슬래시 명령어 /dash_stats

Claude Code에서 직접 작업의 통계를 조회합니다:

/dash_stats DEMO-100   → stats for the given task
/dash_stats            → uses the ACTIVE task of the current session

토큰(입력/출력/캐시), 메시지, 도구 호출 + 오류율, p50/p95 지연 시간, 모델별 분석 및 상위 도구를 반환합니다 — 모두 해당 이슈에 대한 것입니다.

구성 요소: ai-usage-stats 명령어 (scripts/task-stats.mjs — 작업을 해석하고 lib/db.mjs의 taskStats()를 통해 로컬 SQLite DB를 직접 읽음) + ~/.claude/commands/dash_stats.md의 명령어. ai-usage-stats DEMO-100으로 실행하거나 (저장소에서 npm run stats -- DEMO-100). 기본이 아닌 DB를 가리키려면 IA_USAGE_DASHBOARD_DB_PATH를 사용하세요. 활성 작업은 세션의 가장 최근 작업 상태입니다.

기록 백필 (선택 사항, 한 번 실행)

훅은 지금부터 캡처합니다. 기존 전체 기록을 한 번에 가져오려면:

npm run collect:claude                       # scans ~/.claude/projects/**.jsonl
CURSOR_API_KEY=<key> npm run collect:cursor

둘 다 멱등적입니다 (ext_id로 중복 제거) — 다시 실행해도 중복되지 않습니다.

다음 단계

• Claude Code 비용 (토큰 × 모델별 가격표).

• 주문형 아티팩트를 넘어 고정 대시보드 (HTML).

• SQLite → Postgres 마이그레이션 (lib/db.mjs만 교체).

• 다중 머신 수집 — DB를 오프박스에 두어야 한다면 insertEvents() 앞에 얇은 수집 엔드포인트를 다시 도입하세요 (현재는 머신에서 단일 사용자로 파일에 직접 실행).