OSS · Claude Code プラグイン

compact-ops

/compactの後、agentは自分が何をしていたかを忘れる。

compact-opsは、圧縮のたびに10見出しの構造化stateファイルを書き、圧縮直後とclaude --resume時に注入し直す透過型プラグインです。公式hookのみで動き、全hookがfail-open。一度入れたら、あとは普通に/compactするだけです。

summaryを置き換えない。外側から保険をかける。

GitHubで入手 公開当日の実弾ログ →

無料 · MIT · 公式hookのみ · 外に出るのは自分のclaude CLI呼び出しだけ

  • 10 見出し固定のstateファイル
  • 60% で事前警告(閾値変更可)
  • 72h resume復旧のfallback窓
  • 30日 stateのディスク保持
  • 圧縮後に脱線しない summary+stateファイルの二重の手がかりで再開
  • auto-compactに驚かない 60%で1回だけ警告+Plan/Phase/直近判断の3行recitation
  • PC再起動を跨いで復旧 claude --resume時に72時間以内の直近stateを注入
  • 壊れても邪魔をしない 全hookがfail-open。標準のcompactionは必ず通る
ターミナルデモ: hooks.jsonの実イベント名、PreCompactバックアップhookの実行(実際のバイト数削減込み)、実際のstateファイルの10見出し構造

4つのhook、常駐プロセスなし

どれも公式のClaude Code hookイベントです。バックグラウンドプロセスもポーリングもありません。

  • PreCompact transcriptをバックアップ(gzip)し、LLMが10見出しのstateファイルを書く
  • PostCompact 使用率警告のcooldownをリセットする
  • SessionStart compact│resumeのmatcherで、stateファイルと原文再読noteを注入する
  • UserPromptSubmit transcriptから使用率を計算し、閾値超過で一度だけ警告する

4つとも全部fail-open。全部失敗しても、compact-opsを入れていないときと同じようにcompactionは通ります。

3ステップで動く

  1. claude plugin install compact-ops リポジトリをclone、ローカルmarketplaceに追加、インストール。1回だけ
  2. /compact 普通に圧縮するだけ。PreCompactがtranscriptをバックアップし、stateファイルを自動で書く
  3. 復旧ガイダンスが注入される 新しいコンテキストにstateファイル+「原文の再読を優先」note+呼び出し済みskill一覧が入る

誰のためのツールか

  • Claude Codeヘビーユーザー 1日に1回以上compactを跨ぐ長いセッションを回している人
  • agent運用者 長時間・定期実行のセッションを走らせ、翌日claude --resumeで続きをやる人
  • セッションを引き継ぐチーム stateファイルは素のMarkdown。人間がそのまま引き継ぎメモとして読める
  • hook自作派 公式hookだけで完結するプラグインの実装例として。全hook fail-open設計込み

どんな時に使うか

  • auto-compactに作業途中の判断を消されたことが一度でもあるとき。60%警告で切りのいい瞬間を自分で選べる
  • 複数日にわたる作業の前に。stateはcompactもセッション終了もPC再起動も跨いで残る
  • agentが承認済みの許可を取り直しに来たり、失敗済みの手を打ち直したとき。まさにそれがstateファイルの固定見出し
  • 圧縮後のagentに「それさっき決めたよ」と言った覚えがあるなら、その事故のためのプラグインです

インストール

git clone https://github.com/kenimo49/compact-ops.git
claude plugin marketplace add /path/to/compact-ops --scope user
claude plugin install compact-ops@compact-ops-local

前提はClaude Code v2.x、jq、LLM backendとしてのclaude CLI。Linux / macOS対応。インストール後は普通に/compactを実行するだけで動きます。

やること

  • PreCompact: transcriptをバックアップ(gzip、JSONLは約1/10に縮む)し、LLMがActive Plan・判断・ブロッカー・編集中ファイル・失敗済みアプローチの10見出しstateファイルを書き出す
  • 圧縮直後: stateファイル+「原文の再読を優先せよ」note+呼び出し済みskill一覧を新コンテキストへ注入
  • claude --resume時: 同じ復旧注入。72時間以内の同一プロジェクト直近stateへのfallbackつきで、PC再起動を跨いでも残る
  • コンテキスト使用率警告はプラグイン単体で計算(デフォルト60%): /compact推奨を一度だけ、Plan / Phase / 直近判断の3行recitation付きで通知
  • stateは~/.claude/compact-ops/に永続化。30日保持、プロジェクト別に整理。session_idはallowlist検証してからファイルパスに使う
  • LLM出力は10見出し全部の存在を検証してから書き込み。不正な出力なら旧stateを保持したままfail-open
  • u-ichi/compact-plus (MIT)派生。外部statuslineスクリプト依存を外し、LLM backendをClaudeだけ(Sonnet primary / Haiku fallback)で完結させた自己完結版

標準のClaude Codeとの違い

圧縮アルゴリズムも標準summaryも同じです。違うのはその外側の全部です。

タイミング標準のClaude Codecompact-opsあり
使用率60%超 無警告。auto-compactは突然来る 1回だけ通知+Plan / Phase / 直近判断の3行recitation
compactの瞬間 built-in promptがsummaryを生成(中身は制御不可) 同じ圧縮に加えて、transcript backup+10見出しのstateファイル
圧縮直後 summaryだけを頼りに再開 stateファイル+原文再読noteを新コンテキストへ注入
セッションを閉じた後 summaryはそのセッション内で消滅 stateは30日残り、claude --resume時も注入される
hookが失敗した時 — fail-open。標準のcompactはそのまま通る

出典はリポジトリREADME。圧縮アルゴリズム自体には一切手を入れず、公式hookで外側から足しています。

stateファイルはこう残る

ターミナルスクリーンショット: 実際のcompact-ops stateファイルの10見出し。Active PlanとSession DecisionsからFailed AttemptsとRecovery Notesまで
実際のstateファイルの見出しだけを表示しています(本文は会話そのものなので非公開)。このページの改修セッション自身も、compactを2回跨いでこの形式のファイルから再開しました。

使い方

# 普通にcompactするだけ — あとはhookが処理
/compact

# 引数はstate生成LLMへのpriority guidanceになる
/compact 重要な設計判断は必ず残して

# ~/.claude/settings.json のenv blockで調整
COMPACT_OPS_WARN_THRESHOLD=70
COMPACT_OPS_PRIMARY_BACKEND=""
COMPACT_OPS_DEBUG=1

自分のリリースで実弾テスト済み

最初の受益者は、これを作っていたセッション自身でした。演出なしの実運用から3つ:

  • v0.2.0のリリース作業中、リリースしている当のセッションで自作の60%警告が67%で発火。警告を書いたのも守られたのも作者本人、同じ夜のことです
  • その数分後、ディレクトリ再構成で自分のhookが3本同時に失敗。それでもcompactionは無傷で完走しました。全hook fail-openの設計が、事故によって本番でテストされた瞬間です
  • いま読んでいるこのページも、compactを2回跨いだセッションで改修され、そのたびに本文が説明しているstateファイルから再開しています

67%警告とhook3本失敗を含む公開当日のログは、ブログに全部書いています。

公開当日の実弾ログ →

知っておくコスト: compact 1回ごとにstate生成のLLM呼び出しが1回増えます(デフォルトSonnet。envでHaikuに下げたり無効化も可)。stateファイルとバックアップには会話がそのまま残ります。umask 077で作成され(ディレクトリ700 / ファイル600)、手元のマシンに置かれたまま30日で自動削除されます。

なぜ作ったか

built-inのsummaryはコードの要点をよく拾います。消えやすいのは運用系の事実のほうです。「pushはもう承認済み」「このアプローチは試して失敗した」「この値の出典はあのファイル」。これらが消えると、agentは承認を取り直しに来て、失敗済みの手を打ち直し、同じ作業に二度支払うことになります。compact-opsはこの種の事実に固定見出しを割り当て、summaryの外側に保存します。譲らなかった設計線がひとつ: stateファイルをプロジェクトファイルより信用させないこと。LLMが書いた要約を別のLLMが無条件に信じる構図は伝言ゲームの高速化でしかないので、復旧ガイダンスは常に原文の再読を促します。

compact-plus・素のClaude Codeとの位置関係

compact-opsはu-ichi/compact-plus (MIT)の派生実装です。「圧縮前に構造化stateを書く」というアイデアの骨格はcompact-plusが先に実装しました。下の差分が、派生が存在する理由です。

compact-opscompact-plus素のClaude Code
使用率警告 プラグイン単体で自己計算。追加設定なし 別リポジトリのstatuslineスクリプトに依存 なし。auto-compactは突然来る
stateの置き場所 ~/.claude/compact-ops/に30日保持、プロジェクト別 $TMPDIR(再起動で消える) summaryはセッション内のみ
--resume時の復旧 ✓ 同一プロジェクト72h fallbackつき — —
圧縮直後の注入 SessionStartのcompact matcherで直接 marker経由で次のUserPromptSubmit(2 hookの間接構造) —
LLM backend Sonnet primary / Haiku fallback。Claudeだけで完結 Sonnet primary / Codex fallback (ChatGPT Pro前提) —
ライセンス MIT MIT —

核心のアイデア(PreCompact hookで別LLMに構造化stateを書かせる)はcompact-plus由来です。表は2026年7月時点でREADMEに記録した差分で、前提があなたの環境に合うならcompact-plusも良い選択です。

よくある質問

compact 1回あたりのコストは?

state生成のLLM呼び出しが1回増えます(デフォルトSonnet、失敗時Haiku fallback)。COMPACT_OPS_PRIMARY_BACKENDをHaikuに向ければ安くなり、空文字列にすればstate生成だけを無効化して他のhookは残せます。

built-inのsummary自体は変わりますか?

変わりません。圧縮アルゴリズムとsummaryには一切触れず、公式hookで外側に足すだけです。圧縮後のagentはsummaryとstateファイルという二重の手がかりを持つようになります。

会話データはどこに行きますか?

stateファイルとバックアップは手元の~/.claude/compact-ops/に置かれ、umask 077で作成、30日で自動削除されます。ネットワークに出るのはstate生成のためのclaude CLI呼び出しだけで、これは普段のセッションと同じ経路です。

auto-compactでも動きますか?

動きます。PreCompactは手動・自動どちらのcompactionでも発火するので、backupとstateファイルは常に書かれます。既知の制限がひとつ: 使用率警告はUserPromptSubmit時に計算するため、1ターンで大量のコンテキストを消費して次の発話前にauto-compactが走るケースだけは事前警告が間に合いません。

agentはstateファイルを信用していいの?

地図としてだけ信用し、現地としては信用しない設計です。注入するガイダンスには「stateはプロジェクトファイル・plan・skillの原文よりauthoritativeではない」と明記し、原文を再読してから動くよう促します。

compact-plusとの違いは?

3点です。使用率警告が外部statuslineスクリプト依存でなくプラグイン単体で完結すること、stateが$TMPDIRでなく~/.claude/配下に30日永続化されること、claude --resume時にも72h fallbackつきで復旧注入が入ること。backendもClaudeだけに寄せています。全差分は上の比較表に。

summaryのprompt自体を良くすればいいのでは?

それは触れない場所だからです。built-inの圧縮promptは公開されていません。公式hookはサポートされた表面なので、そこに留まる限りClaude Codeの更新を跨いで動き続けられ、fail-openにする余裕も持てます。

Claude Code以外でも使えますか?

使えません。Claude Code v2.xのhookイベント(PreCompact / SessionStart / UserPromptSubmit)とclaude CLI backendを前提にした実装です。他のagent CLIはhookの表面が異なります。

作者について

作者はKen Imoto。Zenn・Qiita・Dev.to・当サイトで技術記事300本以上、4言語で書籍40冊以上、Zenn・Qiitaで累計40万PV超、Zenodoで研究論文4本を公開し、LLMO Frameworkを設計しています。

詳しいプロフィール →

関連する開発ツール

プロダクト一覧 →

← プロダクト一覧へ