Wake: 터미널 히스토리를 Claude Code에 연결해주는 도구

• Wake는 터미널 세션을 녹화해서 Claude Code가 "내가 뭘 했는지" 볼 수 있게 해주는 도구임. 에러 메시지를 복붙하거나 "X도 해보고 Y도 해봤는데 안 됐어"라고 설명하는 대신, AI가 그냥 알고 있는 상태가 되는 거임

PTY + Shell Hook 하이브리드 아키텍처

• 터미널 활동 캡처에 두 가지 접근이 있었음:
  • Shell Hook만 쓰는 방법: zsh/bash의 preexec/precmd 훅으로 입력한 명령과 종료 코드만 알 수 있음. 하지만 stdout/stderr는 셸을 바이패스해서 터미널로 직행하기 때문에 "무슨 일이 일어났는지"는 모름
  • PTY 래퍼: 사용자 셸을 pseudo-terminal 안에서 실행하고 중간에서 모든 바이트를 관찰. 사용자 경험은 동일하지만 모든 걸 캡처함
• Wake는 둘 다 씀. Shell Hook이 프레이밍(명령 시작/끝/종료코드)을, PTY가 콘텐츠(실제 출력)를 담당. 훅은 Unix 소켓으로 메인 프로세스와 통신

sequenceDiagram
    participant 사용자 as 사용자 셸
    participant PTY as PTY 레이어
    participant 훅 as Shell Hook
    participant 소켓 as Unix 소켓
    participant DB as SQLite

    사용자->>PTY: 명령 입력
    훅->>소켓: "명령 X 시작"
    PTY->>PTY: 출력 바이트 버퍼링
    사용자->>PTY: 명령 완료
    훅->>소켓: "명령 X 종료 (exit code)"
    PTY->>DB: 명령 + 출력 저장

구현 디테일

• Rust로 구현, portable-pty로 크로스플랫폼 PTY 처리, 메인 루프는 tokio 비동기
• 시그널 처리가 생각보다 중요함: SIGWINCH(터미널 리사이즈)를 자식에게 포워딩해야 하고, SIGINT/SIGTSTP도 제대로 처리해야 ctrl-c, ctrl-z가 정상 작동
• 출력은 두 버전으로 저장: ANSI 이스케이프 코드 포함 raw 바이트 + AI용 plaintext 스트립 버전
• 5MB 이상 출력은 기본 truncate (설정 변경 가능). npm install 전체 로그를 컨텍스트 윈도우에 넣을 필요는 없으니까

MCP 통합 — 핵심 가치

• Claude Code의 MCP(Model Context Protocol)를 통해 도구 노출:
  • wake_list_commands → 가벼운 메타데이터 (명령, 종료코드, 출력 크기, 요약)
  • wake_get_output → 특정 명령의 전체 출력
  • wake_search → 전체 히스토리 검색
• 계층적 검색(tiered retrieval)이 핵심 설계: 먼저 메타데이터+요약을 보여주고, Claude가 관련 있다고 판단한 것만 전체 출력을 가져옴. 토큰 낭비 방지

로컬 LLM 요약

• v0.6.0부터 llama.cpp + Qwen3-0.6B (~380MB)로 로컬 LLM 요약이 기본 활성화됨
• 명령 완료 시 자동으로 요약 생성. "테스트 3개 실패: auth timeout, null pointer, missing mock" 같은 식으로 Claude가 전체 출력 안 봐도 맥락을 파악할 수 있게 해줌
• CPU만으로 동작, API 호출 없음 — 터미널 히스토리가 로컬을 떠나지 않음