npm에 Throughline 출시: Claude Code의 도구 I/O를 SQLite로 오프로드하는 훅

Claude Code를 위한 훅 플러그인인 Throughline을 npm에 출시했습니다.

기능

Claude Code 세션에서는 컨텍스트 (Context)의 대부분이 "도구 I/O (tool I/O)"의 잔해로 채워집니다. 파일 읽기 내용, grep 결과, Bash 출력 데이터 등은 AI가 이를 읽고 결정을 내린 직후 목적을 달성했음에도 불구하고, 세션이 끝날 때까지 컨텍스트에 남아 토큰 (Tokens)을 소비합니다.

Throughline은 대화를 세 가지 계층으로 관리합니다.

계층 (Layer)	내용 (Content)	컨텍스트 주입 (Context Injection)
L2	대화 본문 (사용자 입력 + AI 응답)	마지막 20개 턴 (turns)을 그대로 주입
...

도구 I/O가 컨텍스트에서 완전히 제거되기 때문에, 파일 읽기, grep 결과, Bash 출력 등이 세션 끝까지 남아있지 않습니다. 오래된 대화는 핵심 사항을 유지하면서 원래 크기의 1/5로 압축되므로, 수십 턴 전에 내려진 결정의 컨텍스트를 여전히 따라갈 수 있습니다.

제 컴퓨터에서 진행한 50턴 세션의 경우, 125,000 토큰을 소비하던 대화가 13,000 토큰 이내로 줄어들었습니다.

설치

npm install -g throughline
throughline install

install 명령은 ~/.claude/settings.json에 훅을 등록합니다. 이는 PC의 모든 Claude Code 프로젝트에 대해 자동으로 실행됩니다. 개별 프로젝트를 위한 별도의 설정은 필요하지 않습니다.

세션 간 데이터 유지

Throughline은 대화를 SQLite로 오프로드 (offload)하므로, /clear를 실행한 후에도 데이터가 남아 있습니다. 이전 세션의 기억을 다음 세션으로 가져오고 싶다면, 이전 세션에서 /tl을 입력하세요.

데이터는 /tl을 입력했을 때만 다음 세션으로 전달됩니다. 입력하지 않으면 새로운 세션으로 시작됩니다. 병렬 창을 열거나 VSCode를 재시작하더라도, "/tl을 입력하지 않는 한 실수로 실행되지 않도록" 설계되었습니다.

이어갈 때, 이전 Claude가 작성한 "다음 단계 메모 (next step memo)"와 마지막 턴의 내부 추론 (thinking) 과정도 함께 전달됩니다. 다음 Claude는 "과거 로그 읽기 (reading past logs)" 모드가 아닌 "중단 지점부터 계속하기 (continue from interruption)" 모드로 실행됩니다.

토큰 모니터 (Token Monitor)

부수적인 결과로, 멀티 세션이 가능한 토큰 모니터가 포함되어 있습니다.

throughline monitor

[Throughline] 1 session
▶ Throughline  2ed5039c  ████░░░░░░░░░░░░░░░░  205.1k /  21%  Remaining 794.9k  claude-opus-4-6

이 모니터는 트랜스크립트 JSONL 파일에서 실제 API 값(message.usage)을 읽어오기 때문에, 글자 수 / 4를 기반으로 한 추정치가 아닌 정확한 값을 제공합니다. 또한 1M 컨텍스트 윈도우 (context windows)의 자동 감지도 지원합니다.

요구 사항 (Requirements)

• Node.js 22.5 이상 (내장된 node:sqlite 모듈 사용)
• Claude Code (훅 (hooks) 지원 필요)
• Claude Max 플랜 (L1 요약을 위한 Haiku 호출에 사용됨; API 키 불필요)
• Windows / macOS / Linux

의존성 (Dependencies)

없음. npm에 게시된 타르볼 (tarball)에는 .mjs 파일만 포함되어 있습니다. 빌드 프로세스나 네이티브 바인딩 (native bindings)이 필요하지 않습니다.

설계 배경과 저의 시행착오 과정은 이 기사에 작성되어 있습니다.

Throughline — GitHub

MIT 라이선스입니다. 버그 리포트와 PR (Pull Request)을 환영합니다.