# 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](https://bun.sh/) (빌드용)
- [Claude Code](https://claude.ai/code) 또는 [Codex CLI](https://github.com/openai/codex)

### 빌드

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

### MCP 서버 등록

```bash
# 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`

### 크로스 컴파일 (선택)

```bash
# 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