# pi-stats

pi coding agent 세션의 토큰/비용 사용량을 집계하는 확장. `~/.pi/agent/sessions/**` 의
세션 JSONL을 읽어 모델별·일자별로 합산해 `/stats` 커맨드로 보여준다.

## 설치

```bash
pi install npm:pi-stats          # npm
pi install git:github.com/preinpost/pi-stats   # git
pi install /absolute/path/to/pi-stats         # 로컬 경로
```

임시로 써보기:

```bash
pi -e npm:pi-stats
```

## 사용법

```
/stats                        오늘 (전체 프로젝트)
/stats 2026-08-21             특정 날짜 하루
/stats 2026-08-01..2026-08-07 기간 (양끝 포함)
/stats 2026-08-20..           특정일부터 지금까지
/stats ..2026-08-20           처음부터 특정일까지
/stats --project              현재 프로젝트(cwd) 세션만
/stats --daily                일자별 집계 추가
/stats --json                 JSON 출력 (스크립트 연동용)
/stats --help                 도움말
```

플래그는 조합 가능: `/stats 2026-08-01.. --project --daily`

날짜 경계는 단말 로컬 타임존 기준.

## 집계 대상

- 어시스턴트 메시지 usage (`provider/model` 기준 그룹핑)
- toolResult 안의 중첩 LLM usage → `(tools)` 행
- compaction / branch_summary 요약 생성 usage → `(summary)` 행
- 서브에이전트 실행 기록 (`subagent-artifacts/*_worker_*_transcript.jsonl`,
  `type` 필드 없이 중첩 `message.usage`만 있는 레코드 포함)
- compaction `retainedTail` 복사본은 중복이라 제외

## 환경변수

- `PI_STATS_SESSIONS_DIR` — 세션 디렉터리 override (기본 `~/.pi/agent/sessions`)

## 개발

```bash
npm install          # devDeps (typescript, @types/node)
npm run selftest     # 합성 fixture 기반 테스트 (31 케이스 — 파싱/집계/엔드투엔드)
npm run typecheck    # tsc --noEmit
```

selftest는 실제 `~/.pi/agent/sessions`에 의존하지 않고 합성 fixture만 쓰므로
CI 등 어느 환경에서든 결정적으로 동작한다.

## 릴리스

GitHub Actions([`.github/workflows/bump-and-release.yml`](.github/workflows/bump-and-release.yml))가
자동 처리한다:

1. `main`에 push → typecheck + selftest 게이트 통과 시 커밋 메시지 기반 버전 범프
   (`fix:` → patch, `feat:` → minor, `BREAKING CHANGE`/`!:` → major)
2. 태그 + GitHub Release 생성 후 npm publish

수동 릴리스: Actions 탭 → **Bump & Release** → Run workflow → 버전 타입 선택.

필요한 시크릿 (1회): `gh secret set NPM_TOKEN -R preinpost/pi-stats`