OSS on Claude Code 始めました

Throughline を npm に公開した — Claude CodeのツールI/OをSQLiteに退避するhook

Sat, 18 Apr 2026 12:00:00 +0900

Throughline っていうClaude Code用のhookプラグインをnpmに公開した。

何をするか

Claude Codeのセッションで、コンテキストの大半は「ツールI/O」の残骸で埋まってる。ファイルを読んだ中身、grepの結果、Bashの出力。AIがその場で使って、判断して、次に進んだ時点で役目を終えてるデータ。でも最後までコンテキストに居座ってトークンを食い続ける。

Throughlineは会話を3層に分けて管理する。

層	中身	コンテキストへの注入
L2	会話本文（ユーザー発言 + AI応答）	直近20ターンはそのまま注入
L1	L2を要点を欠落させない程度（1/5）に要約したもの	20ターンより古いターンはL1を注入
L3	ツールI/O・システムメッセージ・thinking	注入せずSQLiteに退避、必要になったらClaude自身が取り出す

ツールI/Oはコンテキストから完全に抜くので、読み終わったgrep結果やBash出力がセッション最後まで居座らない。古い会話は1/5に圧縮されるが要点は残るので、数十ターン前の判断の文脈もちゃんと追える。

手元の50ターンセッションで実測すると、125,000トークン使ってた会話が、13,000トークンに収まる。

インストール

npm install -g throughline
throughline install

install は ~/.claude/settings.json にhookを登録する。PC内の全Claude Codeプロジェクトで自動で動く。プロジェクトごとの設定は不要。

セッション間の引き継ぎ

Throughlineは会話をSQLiteに退避してるので、/clear してもデータ自体は残ってる。次のセッションに記憶を持ち越したい時は、前のセッションで /tl って打つ。

/tl を打った時だけ、次のセッションに引き継がれる。打たなければ新規セッションとして始まる。並行ウィンドウを開いても、VSCodeを再起動しても、「/tlを打たない限り誤爆しない」ようにできてる。

引き継ぎ時には、前のClaudeが書いた「次の一手メモ」と、最終ターンの内部推論（thinking）も一緒に渡る。次のClaudeは「過去ログを読む」じゃなく「中断地点から続ける」モードで動く。

トークンモニター

副産物として、マルチセッション対応のトークンモニターもついてくる。

throughline monitor

[Throughline] 1 セッション
▶ Throughline 2ed5039c ████░░░░░░░░░░░░░░░░ 205.1k / 21% 残 794.9k claude-opus-4-6

transcriptのJSONLからAPIの実測値（message.usage）を読むので、文字数÷4の推定じゃなくて正確な値が出る。1Mコンテキストの自動検出にも対応。

要件

Node.js 22.5+（node:sqlite 組み込みモジュールを使うため）
Claude Code（hooks対応）
Claude Max契約（L1要約のHaiku呼び出しに使う、APIキーは不要）
Windows / macOS / Linux

依存関係

ゼロ。npmに公開してるtarballは .mjs ファイルだけ。ビルドもネイティブバインディングも不要。

Claude Codeの"続きから"を実装するのに、自動検知を諦めた話

Sat, 18 Apr 2026 09:00:00 +0900

前の記事でThroughlineを公開した。コンテキストの大半を占めてるツールI/Oを退避するやつ。

あの時点では"動いてた"。自分の環境では。

でも記事を出した直後から、おかしな挙動に気づき始めてた。

並行で別のウィンドウを開くと、新しいセッションが前のセッションの記憶を勝手に拾う。VSCodeを再起動すると、毎回「前回のセッションから続き」扱いになる。一度も /clear してないのに。

原因: /clear を検知できない

Claude Codeのhookには SessionStart ってイベントがあって、source っていうフィールドで startup（新規起動）と clear（/clear後）を区別できる、はずだった。

ところがVSCode拡張だと、/clear しても source が startup に潰される。GitHub issue #49937 に上がってる既知の問題。CLI単体なら動くけど、拡張だと識別できない。

自分はVSCode拡張で使ってる。つまり「startupとclearを区別する」前提の設計が、根本から崩れてた。

ヒューリスティックで補おうとした

じゃあ時間差で判定するか。前のセッションの最終活動から10秒以内ならclear、それ以上ならstartup、みたいな。

これも壊れた。

並行でウィンドウを2つ開いてると、両方が"最近活動してた"ので両方が継承先候補になる
VSCode再起動でもtranscriptは残ってるので"最近"に見える
プロセスツリーを追いかけようとしたけど、CLIとextensionでプロセス構造が違う

“そもそも検知できる条件が無い"と気づいた。

発想を変えた

検知しようとするから失敗する。ユーザーが宣言すれば、検知はいらない。

作ったのが /tl ってスラッシュコマンド。ユーザーが次のセッションに記憶を引き継ぎたい時だけ打つ。打つと handoff_batons ってテーブルにそのセッションIDが書き込まれる。バトンを置くイメージ。

次のセッション開始時、バトンが1時間以内に置かれてたら、そのセッションの記憶を引き継ぐ。なければ、何もしない。新規セッションとして始まる。

並行ウィンドウもVSCode再起動も、「バトンが置かれてない限り誤爆しない」が原理的に保証される。

明示的なのは一見面倒だけど、「勝手に引き継いで迷惑」の方が遥かに困る。誤爆ゼロの方が価値があった。

でも、これだけじゃ物足りなかった

バトンができて、次のセッションが前のセッションの会話ログを読めるようになった。でも実際に使ってみて思ったのが、「ただログを読んでるだけ」感。

過去ログを読むAIと、中断地点から続けるAIは、体感が違う。

前者は「よし、状況を把握した。じゃあ今から何をしましょうか？」って聞いてくる。後者は「さっきの続きだと、あと◯◯を確認すればいいよね」って進める。

ここで2つ足した。

in-flight memo. /tl を打った瞬間、今動いてるClaude自身に「次の一手、今の仮説、未解決の問題、進行中のTODO」をMarkdownで書いてもらう。それをバトンに添付する。

thinkingの保存. Claudeのextended thinking（内部推論）ブロックもL3として保存しておく。次のセッションの注入時、最終ターンのthinkingを頭に出す。前のClaudeが何を考えてたかが、次のClaudeに渡る。

結果、次のセッションの注入テキストはこういう形になる。

あなたは中断されたタスクを再開します。

[前のClaudeが書いた in-flight memo]
次やること: X のテストを書く。仮説: Y が原因だと思う。未解決: Z。

[前のClaudeが最後に考えてたこと]
Z の挙動が気になる。もしかしたら...

[直近20ターンの会話]
...

“読む"じゃなく"続ける”

これで手応えが変わった。

コンテキストの87%が使い捨てだったので自分で対策した話

Thu, 16 Apr 2026 00:00:00 +0000

MAXプランの週間クォータが3日で溶けた。

×20のクォータがあるはずなのに、水曜には残量が怪しくなってる。それ自体は「まあそんなもんか」で済ませてたんだけど、ふと気になった。コンテキストウィンドウの中身って、実際どうなってるんだろう。

前の記事ではAI秘書のトークン節約について書いた。CLAUDE.mdを削ったり、MCPツール定義を削ったり。でも今回はAI秘書じゃなくて、Claude Code自体の話。道具のほうが大食いだったとは。

きっかけ

4月14日、スペイン語圏のあるツイートが目に留まった。

「Claude Codeのトークン浪費の大半はユーザー側に原因がある」

言いたいことはわかる。CLAUDE.mdが肥大化してるとか、プロンプトが冗長だとか。でも「大半がユーザー側」って、ちゃんと測って言ってるのか？

じゃあ俺が測ってやる、と思った。

実測してみた

Claude Codeの内部transcript（セッションを記録してるJSONL）を解析した。

1ターンあたり188,000トークン。うち164,000トークン（87%）が会話履歴。

CLAUDE.mdは12,700トークン。MCPツール定義は3,900トークン。合わせても全体の9%。これを半分にしても5%弱しか浮かない。

本丸は会話履歴の肥大化だった。CLAUDE.mdを必死に削ってた自分がちょっと恥ずかしい。

犯人はツールI/O

じゃあ履歴の中身は何か。

開いて驚いた。履歴の約80%がツールの入出力だった。 ファイルの読み取り結果、Bashコマンドの出力、grepの結果。AIがその場で使って、判断して、次に進んだ時点で役目を終えてるデータ。

なのに、それがコンテキストウィンドウにずっと居座って、毎ターントークンを食い続けている。

50ターンのセッションだと、最初のほうにgrepした結果がまだコンテキストにいる。もう二度と見ることはないのに。

/compactの矛盾

「/compactすればいいじゃん」って思うかもしれない。自分もそう思ってた。

でも/compactの仕組み、AIに全履歴を読ませて要約させるんだよね。

トークンを節約するために、トークンを大量に消費する。しかも要約の過程でニュアンスが消える。「あの時なぜこの設計にしたか」みたいな文脈が、丸められて消えることがある。

要約後にまた作業を続ければ、また肥大化して、またcompactして…の繰り返し。根本解決じゃない。

時間じゃなく、種類で分ける

ここで発想を変えた。

MemGPTやLangChainのSummaryBufferMemoryは、古いものから要約する。時間ベースの圧縮。でも問題は「古さ」じゃない。

10ターン前の「この設計にした理由」は今でも価値がある。さっきのgrepの結果は、1ターン前でも用済み。

時間じゃなく、種類で分ければいい。

会話本文（人間が書いたこと、AIが答えたこと）→ 残す
ツール入出力（ファイル内容、コマンド結果）→ 退避する

この発想で作ったのがThroughlineだ。

3層モデル

Throughlineは会話を3つのレイヤーに分解してSQLiteに保存する。

L1（Skeleton） — 古いターンの一行要約。軽量モデルが生成する。1ターン約10トークン。

L2（Body） — 直近20ターンの会話本文。ユーザーの発言とAIの応答がそのまま残る。圧縮なし、ロスレス。

L3（Detail） — ツール入出力、システムメッセージ。SQLiteに退避してコンテキストには一切残さない。必要になったらAIが自分でSQLiteから引っ張ってくる。

/clearを打っても大丈夫。SQLiteは消えないから、次のセッション開始時にトランザクション一発で前セッションの記憶を引き継ぐ。PIDを追いかけたり、時間窓で判定する必要はない。決定的に動く。

数字で言うとこう。

Throughlineなし（50ターン、/clearなし）：
 コンテキスト ≈ 125,000トークン（80%が用済みのツールI/O）

Throughlineあり（50ターン → /clear → 復帰）：
 コンテキスト ≈ 13,000トークン
 （直近20ターンのL2 + 古い30ターンのL1要約）

約90%の削減。

失敗した設計の話もしておく

最初からこの形だったわけじゃない。

初期の設計では、L2を「重要な判断の構造化抽出」にしようとした。[DECISION] WebSocketを採用、[CONSTRAINT] ポート8080は使えない みたいなタグ付きで、会話から重要な情報だけ引き抜くイメージ。