---
title: "Wake: 터미널 히스토리를 Claude Code에 연결해주는 도구"
published: 2026-01-24T23:18:38.000Z
canonical: https://jeff.news/article/1186
---
# Wake: 터미널 히스토리를 Claude Code에 연결해주는 도구

터미널 세션을 녹화해서 Claude Code가 개발자의 작업 컨텍스트를 자동으로 파악하게 해주는 Rust 기반 도구. PTY+Shell Hook 하이브리드 아키텍처로 모든 출력을 캡처하고, MCP를 통해 Claude에 계층적 검색을 제공함.

- **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 소켓으로 메인 프로세스와 통신

```mermaid
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 호출 없음 — 터미널 히스토리가 로컬을 떠나지 않음

> [!IMPORTANT]
> 설치 한 줄 (`curl ... | sh`), 초기화 한 줄 (`eval "$(wake init zsh)"`), MCP 연결 한 줄 (`claude mcp add ... wake-mcp`)로 세팅 가능. 21일 지난 세션은 자동 정리됨

## 핵심 포인트

- PTY 래퍼 + Shell Hook 하이브리드로 명령 프레이밍과 전체 출력 모두 캡처
- MCP 통합으로 Claude Code가 터미널 히스토리를 직접 조회 가능
- 계층적 검색: 메타데이터+요약 먼저, 필요시 전체 출력 — 토큰 효율적
- 로컬 LLM(Qwen3-0.6B)으로 명령 출력 자동 요약, API 호출 없음
- Rust + tokio + portable-pty로 구현, 21일 자동 세션 정리

## 인사이트

AI 코딩 어시스턴트의 가장 큰 약점 중 하나가 '개발자가 이전에 뭘 했는지 모르는 것'인데, 이걸 터미널 레벨에서 해결하는 깔끔한 접근. MCP의 실용적 활용 사례로도 인상적.