Claude Code의 로그를 분석하는 vidura, 그 메커니즘과 실력 검증

서론

며칠 전, 이런 트윗이 올라왔다.

just shipped vidura v0.1.0

a menu-bar app for claude code that actually reads your session logs and tells you the truth about your friction patterns. every claim backed by evidence pulled straight from your transcripts, not vibes.

「Claude Code의 세션 로그를 읽고, 마찰 패턴(friction patterns)을 증거와 함께 알려주는 메뉴바 앱」— 이것이 사실이라면 대단하다. 하지만 「증거와 함께」라는 것을 어떻게 보장하는 거지? 프라이버시는?

그래서 실제로 구동하며 검증해 보았다.

vidura란

mannasdev/vidura 는 Claude Code의 세션 로그(~/.claude/projects/**/*.jsonl)
를 분석하여 개발자의 「마찰 패턴 (friction patterns)」을 자동으로 탐지하는 오픈 소스 도구이다. v0.1.0 시점에서는 CLI 도구군이 중심이며, 메뉴바 앱은 별도로 다운로드하여 조합하는 구성이다.

제공되는 CLI:

vidura-report — 1회의 리플렉션(reflection)으로 최근의 마찰을 리포트
vidura-sweep — 모든 세션을 포괄적으로 분석하여 DB에 축적
vidura-ledger — 제안 목록·승인·거절
vidura-do — 승인된 제안의 액션 실행
vidura-hook — Claude Code의 훅(hook)에 통합
vidura-state — 현재 상태 표시

설치

pip 한 번으로 설치된다. 의존성 패키지도 없다.

pip install vidura-cli
# 또는 pipx install vidura-cli

아키텍처의 핵심

소스 코드를 읽고 파악한 vidura의 설계를 대략적으로 도식화한다.

JSONL 세션 로그
↓
parse_session() → Turn 객체로 변환
...

1. 리플렉터(Reflector)는 Claude Code 자신

이 부분이 가장 흥미롭다. vidura는 마찰의 판단을 Claude Code CLI 자신에게 맡긴다.

claude -p --max-turns 1 --disallowedTools "*"

즉, Claude Code 사용자라면 추가 인증 없이 프론티어 클래스(frontier-class) 모델이 판단해 준다. --max-turns 1과 --disallowedTools *를 사용하여 프롬프트 인젝션(prompt injection) 대책도 세워두었다.

2. 신호 탐지는 로컬에서 완결

모델에 던지기 전에, 다음과 같은 마찰 신호를 로컬에서 계산한다:

리프롬프트(re-prompt) 연속: 사용자가 유사한 수정을 연속적으로 하고 있는지 여부. 어시스턴트의 텍스트 응답에 대해 다음 사용자 입력에 "no,", "not what", "i meant", "again", "still doesn't", "wrong", "undo" 등의 정정 마커(correction marker)가 포함되어 있는지 체크한다. 순수한 Q&A 세션을 마찰로 오인하지 않도록 하는 장치가 들어있다.

에러 반복: 어시스턴트의 회신에 포함된 에러 문자열("Error:", "Traceback", "Exception:", "failed:")을 정규화하여 카운트한다. 경로(path)나 주소는 정규화되므로, 동일한 논리적 에러가 다른 행 번호에 있더라도 동일한 것으로 판정된다.

도구 에러: 권한 거부 등 도구 실행 결과의 에러도 별도의 트랙으로 카운트한다. 다만, 이는 세션의 포함 게이트(inclusion gate)에는 사용되지 않는다 (너무 빈번하기 때문이다).

3. 증거 검증 기구

모델이 인용한 증거가 실제 로그에 존재하는지, shingle 기반 검증을 거친다. 5단어의 shingle을 잘라내어, 70% 이상이 청크(chunk) 내에 존재하는지 확인될 때까지 해당 제안은 채택되지 않는다. 이를 통해 모델에 의한 날조된 인용을 걸러낸다.

4. 기밀 정보 제거

리플렉터로 보내기 전에, 다음과 같은 패턴이 제거된다:

AWS 키(AKIA...)
LLM API 키(sk-ant-..., sk-...)
GitHub 토큰(ghp_, gho_, github_pat_)
JWT 토큰
Bearer 토큰
PEM 비밀키
Slack 토큰
URL 비밀번호
환경 변수 *_KEY, *_TOKEN, *_SECRET
PASSWORD/PASSWD/PWD 변수

실동 검증

테스트 방법

고의로 버그를 포함한 Python 파일을 만들고, Claude Code에게 수정을 시켜 세션 로그를 생성. 권한 거부(permission denial)를 대량으로 발생시키도록 설계.

# 1세션째: 44턴, 101초, Write 권한 거부 2회
claude -p "이 파일 broken.py의 버그를 고쳐줘. 테스트도 작성해줘."
# 2세션째: 30턴, 49초, Bash 권한 거부 6회
...

결과

$ vidura-report
Vidura friction report — 62 sessions scanned
- [permission-prompt-fatigue] confidence=0.68
...

제대로 작동했다. 권한 거부를 감지하고, allowlist(허용 목록)화를 제안해 왔다. 증거로서 실제 로그 메시지도 인용되어 있다.

스윕 (Sweep, 망라 분석)

$ vidura-sweep --batches 3
vidura sweep: batch 1/2 done (4 sessions)
vidura sweep: batch 2/2 done (11 sessions)
...

15세션에서 1건의 제안. 스윕은 여러 배치(batch)로 나누어 순차적으로 리플렉션(reflection)하므로, CI/CD 관점에서 안전하다.

제안 승인 및 액션

$ vidura-ledger accept 1
$ vidura-do 1 --dry-run
[dry-run] would copy to clipboard: /fewer-permission-prompts

제안을 승인하면, vidura-do로 실제 액션을 실행할 수 있다. 이 케이스에서는 /fewer-permission-prompts를 클립보드에 복사할 뿐이다 (Tier 1). 보다 심도 높은 액션 (Tier 2: 파일 추가, Tier 3: 명령어 실행)도 있지만, 사전에 dry-run으로 확인할 수 있다.

프라이버시 검증

"redaction gate(삭제 게이트)"의 실효성을 체크해 보았다.

from vidura.redact import redact
redact("Bearer sk-ant-abc123def456...")
# → "[REDACTED]" ✓
...

API 키 종류는 확실히 제거된다. 다만, 이메일 주소나 일반적인 비밀번호 변수명은 대상에서 제외된다. README의 "redaction gate"를 과신해서는 안 된다.

고정 Fix Index

vidura가 제안할 수 있는 마찰(friction) 패턴은 29개의 하드코딩된 Fix Index로 한정되어 있다. 아래가 전부다:

패턴	설명
permission-prompt-fatigue	권한 거부의 빈번한 발생
...

즉, 제안할 수 있는 것은 이 29가지 패턴에 매칭되는 것뿐이다. 지식인(Q&A) 같은 방식이 아니라, 이 범위의 마찰 패턴을 자동 검출하는 도구라는 위치 선정이다.

좋았던 점

마찰 검출이 실제로 작동함: 권한 거부 패턴을 훌륭하게 검출함
증거 날조 방지: shingle 검증 기구가 확실함
프라이버시 설계: 기밀 정보 제거 + 리플렉터가 로컬(macOS 상에서 완결)에서 동작
dry-run 안전성: 모든 액션을 사전에 확인 가능
의존성 프리: pip 한 번으로 동작. pipx조차 필요 없음

아쉬운 점

검출 가능한 마찰이 29개 패턴으로 한정: 새로운 패턴은 코드 수정이 필요함
증거의 입도가 거침: 범용적인 로그 메시지만 인용할 수 있는 경우가 있음
기밀 정보 제거의 허점: 이메일 주소나 일반적인 비밀번호 변수는 미지원
리플렉터 호출 비용: claude -p를 호출하므로 API 사용량이 증가함 (1회 report당 수십 엔 정도지만)
메뉴바 앱은 미검증: v0.1.0 시점에서는 CLI가 메인

요약

vidura는 "Claude Code의 세션 로그에서 마찰(friction)을 자동으로 탐지한다"는 주장을 실증할 수 있는 도구였다. 아키텍처의 정교함(Claude Code 자체를 리플렉터(reflector)로 활용, 증거 검증 메커니즘, 기밀 정보 제거)과 v0.1.0 수준의 미흡함(29가지 패턴의 제한, 리플렉터 비용)이 모두 확인되었다.

"단순한 느낌(vibes)이 아닌 증거"라는 주장은 거짓이 아니며, 실제 로그에서 인용된 증거가 제시된다. 다만, 그 증거가 어느 정도 구체적인지는 로그의 내용에 따라 달라진다.

메뉴바 앱은 아직 테스트해보지 못했으므로, 이를 포함한 전체 검증은 다음 기회에 진행하겠다.

Insights