pp-chrome-history

pp-chrome-history

前提条件：CLI をインストールする

このスキルは chrome-history-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install chrome-history --cli-only
   

2. chrome-history-pp-cli --version で確認します。
3. スキルを実行するエージェント／ランタイムの $PATH に、表示されたインストール先が含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールする方法に切り替えてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（デフォルトは $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/productivity/chrome-history/cmd/chrome-history-pp-cli@latest

インストール後に --version で「command not found」と表示される場合、ランタイムからバイナリのディレクトリが $PATH 経由で見えていません。確認が成功するまで、スキルのコマンドを実行しないでください。

chrome-history-pp-cli は、ローカルの Chrome 履歴 SQLite データベースを読み取り、~/.cache/chrome-history/ にスナップショットを作成し、オフラインの全文検索インデックスを構築して、閲覧履歴に関する質問に回答します。読み取り専用で、ネットワーク通信はゼロです。情報が端末の外に出ることはありません。 すべてのクエリコマンドは --json と --select に対応しており、同じ機能を chrome-history-pp-cli mcp 経由で MCP ツールとしても利用できます。クエリツールは読み取り専用です。ローカル状態を変更するのは sync と archive_enable／archive_disable のみで、端末上でのみ動作し、ネットワーク通信は行いません。オプションの蓄積型アーカイブ（デフォルトでは無効）を使うと、Chrome が後から削除したり、ユーザーが消去したりする履歴を保持できます。詳しくは以下のアーカイブを参照してください。

使用する場面

History データベースから過去の Chrome アクティビティを調べる場合。「あのとき見たページを探して」「何を調べていたか」「Chrome が閲覧履歴をどのようなトピックに分類したか」「X にどのくらい時間を費やしたか」「何をダウンロードしたか」「このサイトに以前アクセスしたことがあるか」など。

使用しない場面（非推奨トリガー）

• macOS 以外 — macOS 専用です。 Chrome DB のパスとフルディスクアクセスの仕組みは macOS 固有のため、Linux／Windows はまだサポートされていません。
• 開いているタブ — これらは History SQLite DB に含まれません（Chrome はバイナリのセッションファイルに保存しています）。このツールが扱うのは履歴であり、現在開いているタブではありません。
• Safari の履歴 — 別の CLI を使用してください（Safari は履歴を別の形式で保存しており、chrome-history-pp-cli が読み取るのは Chrome のみです）。
• ブックマーク、パスワード、自動入力、Cookie — 対象外です。このツールが読み取るのは History DB のみです。

カテゴリ分類（エージェント向け）

静的な domains カテゴリーマップは大まかな分類であり、journeys では Chrome 独自の（ノイズを含む）クラスターを確認できます。実際のトピック分類では、--json のタイトルと URL を読み取り、自分でトピックを推測してください。エージェントによる推論は、静的マップと Chrome のクラスターの両方を上回ります（特に、履歴を個人用の保管庫に分類する場合）。

セットアップ

chrome-history-pp-cli が $PATH にあることを確認してください（たとえば、go install でインストールするか、ビルド済みバイナリを ~/go/bin にシンボリックリンクします）。次に、Chrome の履歴を一度スナップショットに保存します（更新する場合はいつでも再実行できます。Chrome が DB をロックしていても、ツールが安全にコピーします）。

chrome-history-pp-cli sync      # build/refresh the local snapshot
chrome-history-pp-cli doctor    # health check; warns if Chrome's DB schema drifts from the tested version

doctor で Chrome DB を読み取れないと報告された場合は、ターミナルにフルディスクアクセスを許可してください（システム設定 → プライバシーとセキュリティ → フルディスクアクセス）。

質問に回答する前に sync を実行する必要はありません。クエリコマンドは既存のスナップショットを読み取ります。新しい閲覧履歴を取り込む場合（またはスナップショットがまだない初回）にのみ sync を実行してください。

アーカイブ：Chrome が削除する履歴を保持する

デフォルトでは、スナップショットはChrome の現在の履歴を反映します。Chrome が古い閲覧履歴を削除したり、ユーザーが履歴を消去したりすると、次回の sync でもそれらの閲覧履歴はスナップショットから削除されます。オプションのアーカイブを使うと、履歴が Chrome による削除後も残るように、蓄積される永続的なコピーを保持できます。これはオプトインで、デフォルトでは無効です。通常の「何を閲覧したか」という質問にはスナップショットだけで十分なので、むやみに有効にしないでください。

chrome-history-pp-cli archive enable     # turn on the durable archive (seeds from the current snapshot)
chrome-history-pp-cli sync --accumulate  # refresh: append new visits into the archive (dedup on url+visit_time)
chrome-history-pp-cli archive status --json

• 有効にすると、読み取りは自動的にアーカイブから回答します（スナップショットのすべてのデータを含みます）。クエリ方法を変える必要はありません。search／list／domains／report／heatmap／timeline／sql では、より完全な履歴が参照されます。Chrome 固有の詳細ビュー（journeys／downloads／searches／dwell／graph／profile／visited）では、引き続き現在のスナップショットを参照します。
• sync --accumulate で最新の状態を保ちます（追加のみで、削除されることはありません）。
• 管理： archive disable（蓄積を停止し、ファイルは保持） · archive clobber（アーカイブを現在のスナップショットを基準に初期化） · archive reset --force [--purge]（モードをオフにして archive.db を移動。--purge を指定すると削除） · archive vacuum（圧縮）

主なコマンド

• 検索： search <query>（FTS）、visited <url|domain>、topic <name>（FTS と Journeys を統合）、list、searches（過去の検索語）
• 集計： domains、report（時間と生産性の区分）、heatmap、profile（行動の概要）、dwell（推定滞在時間）
• 再構成： journeys（Chrome 独自のトピッククラスタ）、timeline <date>（セッション単位）、rabbitholes（注意散漫への移行）、graph（ナビゲーショングラフ）
• データ： downloads、sql "<SELECT…>"（読み取り専用）、sync、doctor、version、mcp
• アーカイブ（永続的な履歴、オプトイン）： archive enable|status|disable|clobber|reset|vacuum、sync --accumulate

使用例

# Find a page you half-remember
chrome-history-pp-cli search "github actions cache" --since 30d --limit 20

# What topics has Chrome grouped my browsing into? (its own Journeys clusters)
chrome-history-pp-cli journeys --limit 25

# Everything I browsed about a topic (FTS + clusters merged) — good for feeding a vault/agent
chrome-history-pp-cli topic "model context protocol" --since 90d --json

# Where did my time go this week, and what was productive vs distracting?
chrome-history-pp-cli report --since 7d

# A behavioral snapshot: peak hours, busiest weekday, top domains/searches
chrome-history-pp-cli profile

# Agent-friendly: narrow deeply nested output to just the fields you need
chrome-history-pp-cli journeys --json --select label,page_count --limit 10

# Keep history that Chrome would later prune/clear (opt-in, one-time enable + periodic refresh)
chrome-history-pp-cli archive enable
chrome-history-pp-cli sync --accumulate     # run periodically; reads then see the fuller archive automatically

エージェント向けの注意事項

• 解析には --json を、応答を小さく保つには --select a,b（ドット区切りのパス）を優先してください。
• クエリコマンドは既存のローカルスナップショットから回答します。読み取り前に sync を実行する必要はありません。新しい閲覧履歴を取り込む場合にのみ sync を実行してください（データストアが本当に空の場合、クエリによって run sync first と通知されます）。アーカイブモードが有効な場合、sync／sync --accumulate は永続アーカイブにも書き込むため、読み取りだけを目的に同期しないでください。
• searches／downloads／journeys は Chrome 固有です。将来の Safari CLI では、データを偽装するのではなく「利用不可」として報告します。
• すべてのデータはデバイス上にローカルに保存されます。閲覧データがデバイスの外に送信されることはありません。