Work Tracker

AI 업무 자동 추적 및 주간보고 생성 시스템. Claude Code / Codex CLI Hooks로 모든 대화, 코드 변경, 명령 실행을 100% 결정론적으로 자동 기록하고, MCP 도구를 통해 일일 통계, 주간보고, 데이터 내보내기를 수행합니다.

아키텍처

Claude Code / Codex CLI 이벤트 (자동 발생)
    │
    ▼
Hooks (build/hooks 바이너리)        ← 자동 추적 (대화/코드 변경/토큰·모델)
    │
    ▼
SQLite DB (work-tracker.db)
    │
    ├──▶ 일자별 JSON 캐시 (data/YYYY/MM/DD.json)   ← 과거 날짜 조회 결과 캐싱
    ▼
MCP Server (build/mcp-server)      ← 조회/보고서 (글로벌)
    │
    └──▶ Git 커밋 이력 수집 (작업한 프로젝트 레포 자동 스캔)

핵심 기능

자동 추적 (Hooks)

• SessionStart / SessionEnd: 세션 관리 및 일일 요약(daily_summary) 집계
• UserPromptSubmit: 사용자 프롬프트 100% 자동 캡처
• PostToolUse (Edit|Write): 코드 변경 자동 기록 (파일 경로, 생성/수정 타입, 추가·삭제 라인 수)
• PostToolUse (Bash): 실행 명령 기록 (300자 절삭)
• Stop: 응답 완료 시 어시스턴트 메시지 저장 + transcript 파싱으로 토큰 사용량·모델명 자동 집계 (같은 세션의 이전 행 토큰을 리셋해 중복 누적 방지) + 일일 요약 갱신
• PostCompact: 컨텍스트 압축 시 요약 보존

모든 기록에 작업 디렉토리(dir)가 함께 저장되어 프로젝트별 작업량이 자동 구분됩니다. DB 스키마 변경 시 하위 호환 마이그레이션(dir, model, tokens_used 컬럼)이 자동 적용됩니다.

MCP 도구 (글로벌)

도구	설명
get_daily_stats	일일 작업 통계 (대화 수, 토큰·모델별 사용량, 코드 변경, 프로젝트별 작업량, 주요 변경 파일 TOP 5)
export_data	기간별 데이터 JSON 내보내기 (대화, 코드 변경, 일일 요약)
generate_weekly_report	주간보고 증적 데이터 + 작성 지침 반환 → LLM이 보고서 작성

MCP 서버는 글로벌 등록되어 어느 프로젝트에서든 사용할 수 있습니다.

주간보고 생성 (generate_weekly_report)

증적 데이터를 수집해 LLM에게 전달하고, 정해진 양식·작성 규칙에 따라 보고서를 작성하게 합니다.

• 일자별 JSON 캐시: 과거 날짜는 data/YYYY/MM/DD.json 캐시에서 로드, 캐시 미스·당일 데이터만 DB 조회 (조회 결과는 자동 캐싱)
• 프로젝트별 집계: 대화 수, 코드 변경, 변경 파일 목록, 소요시간
• 작업 시간 계산: 세션 간격 합산 방식 — 연속 메시지 간격이 30분 이내면 같은 세션으로 간주해 실작업 시간 산출
• Git 커밋 이력 수집: 기간 내 작업한 프로젝트 디렉토리의 레포를 자동 스캔, 레포별 git config user.email 기준 본인 커밋만 필터링
• 모델별 토큰 집계: 모델별 턴 수·토큰 사용량 분리 표시
• 시간 절감 추정: 단독 작업 추정(라인당 2분) 대비 실작업 시간 비교
• 작성 지침 내장: '기존 방식 / AI 적용 / 결과' 구조, 정량 성과 표, 증적(Git 이력·주요 변경 파일), AI 활용 팁 섹션까지 보고서 양식과 작성 규칙을 함께 반환 — 없는 사실 추측 금지, 수치 불확실 시 '추정' 표기 등 환각 방지 규칙 포함

설치

요구 사항

• Bun (빌드용)
• Claude Code 또는 Codex CLI

빌드

git clone <repository-url> ~/work_tracker
cd ~/work_tracker
npm run build:all    # Hooks 바이너리 + MCP 서버 빌드

MCP 서버 등록

# Claude Code (글로벌)
claude mcp add work-tracker -s user ~/work_tracker/build/mcp-server

# Codex CLI
codex mcp add work-tracker -- ~/work_tracker/build/mcp-server

설정 예시: examples/mcp.claude.json, examples/mcp.codex.toml

크로스 컴파일 (선택)

# Windows
bun build src/hooks.ts --compile --target=bun-windows-x64 --outfile build/hooks-win.exe
bun build src/mcp-server.ts --compile --target=bun-windows-x64 --outfile build/mcp-server-win.exe

# Linux
bun build src/hooks.ts --compile --target=bun-linux-x64 --outfile build/hooks-linux
bun build src/mcp-server.ts --compile --target=bun-linux-x64 --outfile build/mcp-server-linux

Hooks 설정

Claude Code

.claude/settings.json에 hooks가 이미 구성되어 있습니다. 프로젝트 안에서 바로 동작합니다.

글로벌 적용 (모든 프로젝트에서 추적):

~/.claude/settings.json에 hooks를 등록하세요. $HOME 경로를 사용합니다. 전체 예시: examples/settings.global.json

Codex CLI

.codex/hooks.json에 hooks가 구성되어 있습니다. 전체 예시: examples/hooks.codex.json

차이점:

• SessionEnd, PostCompact 이벤트 미지원 → Stop에서 대체 (daily_summary 갱신 포함)
• async 옵션 미지원
• 토큰 집계 시 Codex transcript 포맷(token_count 이벤트) 자동 인식
• Windows hooks 임시 비활성화

Windows

• 빌드 시 자동으로 .exe 확장자 생성 (build/hooks.exe, build/mcp-server.exe)
• Hooks 설정에서 .exe 경로 사용 필요
• Codex CLI hooks는 Windows 미지원
• 상세: SETUP_GUIDE.md 5. Windows 설정 참고

파일 구조

work_tracker/
├── src/
│   ├── hooks.ts              # Hooks 핸들러 (자동 추적, 토큰/모델 집계)
│   └── mcp-server.ts         # MCP 서버 (통계/보고서/캐시/Git 수집)
├── build/
│   ├── hooks                 # Hooks 바이너리
│   └── mcp-server            # MCP 서버 바이너리
├── data/                     # 일자별 JSON 캐시 (자동 생성, gitignore)
│   └── YYYY/MM/DD.json
├── .claude/
│   └── settings.json         # Claude Code hooks 설정
├── .codex/
│   └── hooks.json            # Codex CLI hooks 설정
├── examples/
│   ├── settings.project.json
│   ├── settings.global.json
│   ├── hooks.codex.json
│   ├── mcp.claude.json
│   └── mcp.codex.toml
├── scripts/
│   └── generate-report.sh    # 보고서 생성 스크립트
├── work-tracker.db           # SQLite DB (자동 생성, gitignore)
└── package.json

사용법

일일 통계

오늘 작업 통계 알려줘
3월 28일 통계 보여줘

→ MCP 도구 get_daily_stats 자동 호출

주간보고

주간보고 작성해줘
이번 주 주간보고 생성해줘

→ MCP 도구 generate_weekly_report 호출 → 증적 데이터 + 작성 지침 반환 → LLM이 보고서 작성 후 주간보고_시작일_종료일.md로 저장

데이터 내보내기

이번 달 데이터 내보내줘
3월 1일부터 31일까지 데이터 export 해줘

→ MCP 도구 export_data 호출 → JSON 파일 저장

데이터베이스

SQLite (work-tracker.db)에 자동 생성되며, 주요 테이블:

테이블	용도
conversations	대화 기록 (사용자/어시스턴트/시스템, 작업 디렉토리, 모델, 토큰)
code_changes	코드 변경 (파일, 타입, 라인 수, 작업 디렉토리)
daily_summary	일일 통계 집계 (대화/코드/라인/토큰)
weekly_reports	주간보고서 캐시

과거 날짜의 원본 데이터는 data/YYYY/MM/DD.json에 캐싱되어 반복 조회 시 DB 접근을 최소화합니다.

작성자

홍우영 (dud0880@inswave.com)

라이선스

MIT License