提案と「うまくいかないこと」¶

Interlatch は、記録したセッションから何度も繰り返す失敗を探します。Playwright が受け付けないスクリーンショットのパス、ファイルが変わっていて失敗する編集、何にも一致しない zsh の glob などです。What goes wrong（うまくいかないこと）はその原因を、ノイズと分けて一覧にします。Suggestions（提案）は、修正案を 1 つにまとめた承認待ちの一覧です。 CLAUDE.md や AGENTS.md に書く 1 行、Claude Code の MCP 設定の変更、あなたが実行するセットアップ手順があります。十分な回数確認されたナレッジも、指示ファイルの 1 行として提案されます。

提案を承認するまで何も書き込まれず、書き込む前にファイルをバックアップします。モデルは呼び出しません。どちらもアーカイブから決まったルールで数秒で作られます。

うまくいかないこと¶

読み込むもの： セッションで失敗したツール呼び出し（セッションの再開などで同じ行が 2 回保存されていても 1 回と数えます）と、セッションの分析が各セッションについて書いたフリクションのメモ（英語または日本語）です。1 つのメモが複数の原因に当てはまることもあります。history.jsonl から復元したセッションにはどちらもないため、対象外です。

失敗は既知の原因のカタログと照合されます。原因ごとに修正案があります：

原因	起きること	提案する修正
`edit-stale-context`	読んだあとにファイルが変わっていた、または想定した行がなく、編集が失敗する	指示：編集の直前に該当行を読み直す
`playwright-output-roots`	Playwright MCP が許可されたルートの外のスクリーンショットのパスを拒否する、または `file://` のページを開けない	設定：`--isolated` と出力ディレクトリ。指示：スクリーンショットはファイル名だけで保存し、`http://localhost` でプレビューする
`playwright-browser-in-use`	「Browser is already in use」：別のセッションが Playwright の共有ブラウザーを使っている	設定：`--isolated`。指示：再試行せずに止まる
`playwright-stale-refs`	古いスナップショットの ref や、あいまいなセレクターで Playwright を操作する	指示：ref を使う前にスナップショットを取り直す
`zsh-nomatch`	引用符のない glob が何にも一致せず、zsh がコマンド全体を止める	セットアップ手順：`setopt NO_NOMATCH`。指示：glob はすべて引用符で囲む
`zsh-equals`	zsh が `=` で始まる語を展開する（`echo ====` が失敗する）	セットアップ手順：`unsetopt EQUALS`。指示：区切り線は引用符で囲む
`zsh-dialect`	zsh では動きが違う bash の書き方（`$status` は読み取り専用、単語分割がない）	指示：bash ではなく zsh として書く
`sleep-polling-blocked`	待つための `sleep N; cmd` を Claude Code がブロックする	指示：`run_in_background` か Monitor で待つ
`timeout-missing`	`timeout` がインストールされておらず（macOS）、包んだコマンドが 127 で終わる	セットアップ手順：`brew install coreutils`。指示：代わりに Bash ツールの timeout を使う
`bare-python-modules`	使い捨ての Python をシステムのインタープリターで実行し、モジュールがない、`python` がない	指示：`uv run --with` で実行する
`interactive-aliases`	`cp -i`、`rm -i` のエイリアスでコマンドが止まる、または上書きが飛ばされる	セットアップ手順：エージェントのシェルではエイリアスを使わない。指示：`command cp -f` を使う
`stale-dev-server`	ポートがすでに使われている、または動作確認に古いサーバーが応答する	指示：先にポートの持ち主を確認する
`cwd-drift`	相対パスの `cd sub && …` が違うディレクトリから実行される	指示：絶対パスを使う
`auto-mode-retry`	オートモードの分類器が拒否した操作をもう一度試す	指示：止まって尋ねる
`bash-timeout`	長いコマンドがシェルツールの制限時間に達する	指示：バックグラウンドで実行する
`concurrent-sessions`	同じプロジェクトで別のセッションが動いている間（前後 10 分以内）に、編集・ポート・ブラウザーの衝突が起きる	指示（そのプロジェクトのファイル）：ほかのセッションも同じツリーを使っている前提で動く

ノイズは分けて扱い、修正は提案しません。開発ループの中で失敗するテスト・リンター・型チェック、最後のコマンドが 0 以外で終わった読み取り専用のコマンドの連鎖（cat、grep、ls など）、提供元やプラットフォームの障害（過負荷、接続切れ、使用量の上限、ログインの期限切れ）、許可の確認であなたが断ったツール呼び出しです。本当の原因に当てはまる失敗は、ノイズには数えません。

どの既知の原因にも当てはまらないフリクションのメモでも、3 セッション以上で繰り返していれば other として参考に表示します。修正は提案しません。

原因ごとに、影響したセッション数とプロジェクト数、起きた回数、同じ失敗をすぐに再試行した回数、それらのプロジェクトのセッションのうち影響した割合、最初と最後に見た日、まだ起きているか（直近 14 日間に見たか）、直近 12 週間の週ごとのセッション数、例となるセッションが分かります。原因の下には、失敗した呼び出しが多いツールの上位 15 件と、その失敗率が出ます。

ダッシュボードでは： What goes wrong ページ（Suggestions のサイドバー、または ⌘K から）。30 日、90 日（既定）、180 日、全期間と、プロジェクトを選べます。原因をクリックすると、例、エージェント、プロジェクト、修正が出ます。N to review でその提案が開きます。Noise カードには想定内の失敗の件数が出て、Show で一覧になります。

コマンドラインでは： interlatch friction [-p project] [--days N] [--json] [--noise]。--days を付けなければ全期間が対象で、除外したノイズの量を 1 行で表示します。--noise で一覧にします。

提案の出どころ¶

「うまくいかないこと」から。 まだ起きていて、3 セッション以上または 2 プロジェクト以上で起きた原因に提案が出ます。 3 プロジェクト以上で起きていれば指示の行はユーザーレベルのファイルに、そうでなければ最も多く起きたプロジェクトのファイルに入ります。concurrent-sessions は常にプロジェクトのファイルに入り、2 セッション以上で起きたプロジェクトを最大 5 つまで対象にします。行を提案するのは、その原因に実際に当たったエージェントだけです（Claude Code のファイル、Codex のファイル、またはその両方）。あなたが移した原因は、移した先に入ります。

ナレッジから。 次の条件を満たすナレッジが提案になります：

有効で、分析が抽出したものか、あなたが追加したもの（Claude Code や Codex のメモリーノートからは提案しません）
gotcha、fix、command、preference、decision のいずれか
確信度が高いか、established か canonical
変更履歴（「Fixed…」「Added…」「X now does Y」）ではなく、ルールとして書かれている（「never…」「X ではなく Y を使う」「…が必要」）。1 セッションでしか見ていない項目は、さらに command、preference、または明確なルールである必要があります。

タイトルがほぼ同じ項目は 1 つの教訓として扱い、最も信頼度の高いものを提案します。3 プロジェクト以上で見つかった教訓と、分析が global とした preference（プロジェクトのやり方ではなく、あなたの働き方）は、プロジェクトごとではなく、ユーザーレベルのファイルの 1 行になります。ほかの global な項目（ツールの gotcha やコマンドなど）は、元のプロジェクトのファイルに入ります。ユーザーレベルのファイルはすべてのセッションで読まれるためです。あなたが移した教訓は、移した先に入ります。上のカタログがすでに扱っている教訓は、そちらに任せます。行は、項目のタイトル（太字）と本文の最初の 1 文で、最大 240 文字です。ナレッジからの行は 1 ファイルにつき最大 8 件で、段階が高いもの、裏付けるセッションが多いもの、最近のものから順に選びます。却下や適用をした行と、移した教訓は 8 件の枠を使いません。残りは順番を待ち、枠が空くと出てきます。Stale にはなりません。

そのファイルの Interlatch のブロックの外に、ほぼ同じことを書いた行がすでにあれば、提案しません。

3 つの種類¶

種類	表示	変更するもの	実行するのは
`instruction`	Instruction	`CLAUDE.md` または `AGENTS.md` の Interlatch のブロックの 1 行	適用したときに Interlatch
`config`	Config change	`~/.claude.json` の Playwright MCP サーバーに追加する引数	適用したときに Interlatch
`environment`	Setup step	シェルの設定：`setopt` の行、`brew install coreutils`、エイリアス	あなた。Interlatch はコマンドを表示するだけで実行しません。実行したら完了にします

指示の行が入る場所¶

	ユーザーレベル	プロジェクトレベル
Claude Code	`~/.claude/CLAUDE.md`（`$CLAUDE_CONFIG_DIR` があればその中）	`<project>/CLAUDE.md`
Codex	`~/.codex/AGENTS.md`（`$CODEX_HOME` があればその中）	`<project>/AGENTS.md`
GitHub Copilot、IBM Bob、Google Antigravity	なし（対象外）	`<project>/AGENTS.md`

ユーザーレベルのファイルは [sources] claude_dirs と codex_dirs の最初のフォルダーに従います（設定）。そのため、バックグラウンドの処理とあなたのシェルが同じファイルに書きます。プロジェクトの行は、今もあるフォルダーにだけ提案し、ホームフォルダーやその上のフォルダーには提案しません。そこにある CLAUDE.md はすべてのプロジェクトに届いてしまうためです。

プロジェクトの AGENTS.md が CLAUDE.md に触れていれば、行は CLAUDE.md だけに入ります。CLAUDE.md が @AGENTS.md を読み込んでいれば、AGENTS.md だけに入ります。プロジェクトのファイルを提案するのは、そのプロジェクトで作業するエージェント（3 セッション以上、またはセッションの 5 分の 1 以上）だけで、もう存在しないプロジェクトのフォルダーは対象にしません。ファイルがなければ、適用したときに作ります。

Interlatch のブロック¶

Interlatch が書くのは、ファイルの末尾にある 1 つのブロックの中だけです：

<!-- BEGIN interlatch -->
- Re-read the exact lines (Read, or `sed -n 'a,bp' file`) in the same turn before every edit … <!-- interlatch:friction:edit-stale-context -->
<!-- END interlatch -->

ブロックは、ほかのツールが管理するブロック（agent-ninja-START … agent-ninja-END など）も含めて、ファイルのほかのすべての後ろに置きます。ほかのブロックの中には入れません。
ブロックの外のテキストには一切触れません。ブロックの中にあなたが interlatch: の印なしで書いた行は残します。
各行の末尾には提案を示すコメントが付くため、元に戻すときはちょうどその行だけを消せます。エージェントはこのコメントを無視します。
それ以外には何も足しません。見出しや「generated by」のような文言も入れません。
最後の行を消すとブロックも消えます。その行のために Interlatch が作ったファイルは、元に戻すと削除します。もともとあったファイルは残します。
改行が Windows 形式（CRLF）のファイルはそのまま保ちます。シンボリックリンクのファイルはリンク先に書き、リンクはリンクのままです。
壊れたブロック（END のない BEGIN や、ブロックが 2 つあるなど）は推測で直しません。適用を止め、手で直すファイルを示します。

言語¶

「うまくいかないこと」からの行は、[analysis] language（設定）の言語で書きます。英語か、ja なら日本語です。コマンドと設定の変更はどちらでも同じです。行の末尾の印（）は言語によって変わらないため、ファイルにすでにある行を別の言語で提案し直すことはありません。ブロックの外に同じことを書いた行があれば、どちらの言語でも書かれているものとして扱います。編集していない確認待ちの行は、次の更新で言語が切り替わります。適用済みの行と編集した行はそのままです。ナレッジからの行は、そのナレッジが書かれた言語のままです。

設定の変更¶

playwright-output-roots と playwright-browser-in-use には、次の変更を提案します：

mcpServers.playwright.args += ["--isolated", "--output-dir", "/Users/you/.cache/playwright-mcp"]

~/.claude.json（$CLAUDE_CONFIG_DIR/.claude.json があればそちら）に playwright という名前のサーバーがあり、これらの引数が足りないときだけ提案します。適用すると足りない引数だけを追加し、すでに設定されているフラグの値はそのままにします。ほかのキーはすべて残し、ファイルはインデント 2 スペースで書き直します。引数がそろうと、提案は stale になります。新しく始めた Claude Code のセッションから反映されます。

Interlatch が行う設定の変更はこれだけです。編集したテキストも確認します。Playwright のサーバーを指していて、追加できるのは --isolated と --output-dir <絶対パス> だけです。元に戻すと、Interlatch が追加した引数だけを消します。

確認と適用¶

ダッシュボードでは： レールの Suggestions。まだ見ていない提案の数がバッジに出て、ページを開くと消えます。サイドバーと上部のスイッチで To review（確認待ち）、Applied（適用済み）、Done（完了）、Stale、Dismissed（却下）を切り替え、メニューでユーザーレベルの提案か 1 つのプロジェクトに絞り込めます。提案は変更するファイルごとにまとまり、セットアップ手順は別のまとまりになります。各カードには次のものが出ます：

種類、出どころ（from what goes wrong または from knowledge）、エージェント
根拠：「seen in 31 sessions across 17 projects · still happening · last 2026-10-01」、ナレッジなら「established · confirmed in 2 sessions · agents-chronicle」と、開ける例のセッション 2 件
警告（後述）
行そのもの。編集できます。入力欄を離れると文言が保存され、以後の更新でも残ります。Reset to the proposed text で元に戻せます。

Preview はファイルへの変更をそのまま差分で表示し、書き込みはしません。Apply で書き込みます。Dismiss で一覧から外します。セットアップ手順はコマンドと Copy を表示し、実行したら Mark done を押します。Check again で最新のセッションとナレッジを今すぐ確認します。

行を移す¶

確認待ちの指示の行は、Interlatch が選んだのとは別の場所に移せます。プロジェクトのカードの Move to every project で、代わりにユーザーレベルのファイルに入れます。ユーザーレベルのカードの Move to プロジェクト only（複数のプロジェクトから来たときは Move to its projects）で、元のプロジェクトのファイルに戻します。繰り返す失敗なら、2 セッション以上で起きたプロジェクトを最大 5 つまで対象にします。選んだ場所はその教訓や原因ごとに記憶します。確認待ちのカードはまとめて移り（プロジェクトの 2 枚のカードがユーザーレベルの 1 枚になります）、編集した文言も一緒に移り、以後の更新でもそのままです。適用済みの行は、書き込んだ場所に残ります。

ホームには、確認待ちがあるときに Suggestions カードが出て、上位 3 件を Approve（承認）と Dismiss 付きで表示します（セットアップ手順には Copy command）。タイトルをクリックするとカード全体が開きます。

コマンドラインでは：

コマンド
`interlatch suggest [-p project] [--all] [--json]`	確認待ちの一覧（`--all` で適用済み、完了、stale、却下も）。対象ファイル、根拠、警告付き
`interlatch suggest show ID`	適用したときの差分、またはセットアップ手順のコマンド
`interlatch suggest apply ID… [--yes]`	それぞれの差分を表示し、書き込む前に確認（`--yes` で確認しない）。セットアップ手順は断ります。自分で実行してください
`interlatch suggest dismiss ID [--reason R]`	二度と提案しない（適用済みのものは先に元に戻す）
`interlatch suggest done ID`	セットアップ手順を実行した
`interlatch suggest undo ID`	適用した行や設定の変更を取り消す。却下や完了にしたものを確認待ちに戻す
`interlatch suggest move ID --to user\\|project`	確認待ちの行をユーザーレベルのファイルに、または元のプロジェクトのファイルに移す
`interlatch suggest refresh`	最新のセッションとナレッジを今すぐ確認する

バックアップ： 書き込む前に、今のファイルを ~/.interlatch/backups/<name>.<time>.bak にコピーします。たとえば CLAUDE.md.2026-10-02T091500.123Z.bak や .claude.json.<time>.bak（先頭のドットが付くため、ls -a で見えます）です。 Interlatch が新しく作るファイルには、バックアップするものがありません。新しい内容は一時ファイルに書いてから置き換えるため、書きかけの状態になることはありません。

警告¶

よく読んでほしい提案には警告が付きます。警告があっても適用はできます。

Public repository（公開リポジトリ）： プロジェクトの origin が公開の GitHub リポジトリで、コミットすれば誰でもその行を読めます。Interlatch は git remote get-url origin を実行し、GitHub のリモートなら gh repo view で確認して、結果を 1 週間覚えておきます。gh がない場合やほかのホストでは公開かどうか分からないため、警告は出しません。
Looks sensitive（機密情報の可能性）： 行にメールアドレス、GUID、プライベート IP アドレス、ホームフォルダーのパス（/Users/<name>/、/home/<name>/）、よく知られた公開ホスト以外のホスト名、トークンやキーらしいものが含まれています。ダッシュボードでは、編集して Preview を押すとこの警告も更新されます。
File not tracked by git（git で管理されていないファイル）： ファイルは git リポジトリの中にありますがコミットされておらず、行はこのコンピューターにだけ残ります。

以後の更新¶

一覧は、バックグラウンド同期のたび（モデルは呼び出さず、数秒で終わります）、Check again、interlatch suggest refresh で更新されます。

状態	意味
`new`（To review）	確認待ち。更新で根拠は新しくなりますが、あなたが編集した文言は残ります
`applied`	書き込み済み。フリクションの修正なら、その後その原因に当たったセッションを数えます（「seen in 2 sessions since applied」、または「not seen since applied」）
`done`	実行済みにしたセットアップ手順
`stale`	原因が起きなくなった、またはファイルにすでに書かれている。原因がまた起きれば確認待ちに戻ります
`dismissed`	以後のセッションで何が起きても、二度と提案しません。Restore（または `interlatch suggest undo ID`）で戻せます

元に戻す¶

適用済みのカードの Undo、または interlatch suggest undo ID で、行をブロックから（設定の変更なら引数を ~/.claude.json から）取り除き、提案を確認待ちに戻します。
まとめて消すには、ファイルの  から  までを削除します。更新で行が書き戻されることはありませんが、それらの提案は Undo か Dismiss をするまで適用済みのまま表示されます。
変更したファイルの以前の版は、すべて ~/.interlatch/backups/ にあります。
interlatch uninstall は、提案で変更した指示ファイルや ~/.claude.json には触れません。消したい場合は先に元に戻してください。

Interlatch が決してしないこと¶

適用していないものを書き込むこと。更新で変わるのは一覧だけです。
セットアップ手順を実行すること、シェルの起動ファイル（~/.zshrc、~/.zshenv）を編集すること。コマンドを表示するだけで、実行するのはあなたです。
指示ファイルのブロックの外に書くこと、~/.claude.json の Playwright サーバーの args 以外を変えること。
作成者の表示や「generated by」のような文言を加えること。
このためにセッションをどこかへ送ること。外部への呼び出しは、後述の gh repo view だけです。

設定¶

キー	既定値
`suggestions.enabled`	`true`	バックグラウンド同期のたびに一覧を更新する。オフにすると一覧はそのままですが、Check again と `interlatch suggest refresh` は使えます
`suggestions.notify`	`false`	バックグラウンド同期で新しい提案が見つかったら、デスクトップ通知（「3 new suggestions. Open the dashboard > Suggestions」）を表示する

interlatch config set suggestions.notify true で変えるか、config.toml の [suggestions] に書きます（設定）。

プライバシー¶

「うまくいかないこと」と提案が読むのは、ローカルのデータベースと、変更する可能性のある指示ファイルだけです。公開リポジトリを警告するために、行を提案するプロジェクトで git remote get-url origin を実行し、GitHub のリモートなら、あなた自身の gh のログインで gh repo view <owner>/<repo> --json visibility を実行します。GitHub に送るのはリポジトリの名前だけで、結果は 1 週間保存します。gh がなければ何も送りません。データとプライバシーを参照してください。