HN 日本語サマリー

← 一覧へ戻る
プログラミング

Show HN: Mindwalk – コードベースの3Dマップでコーディングエージェントのセッションを再生する

Show HN: Mindwalk – Replay coding-agent sessions on a 3D map of your codebase (github.com)

139 pointsby cosmtrek61 コメント

要約

Mindwalkは、コードベースを3Dマップとして可視化し、コーディングエージェントのセッション再生を可能にするツールです。エージェントがコードベースのどの部分を関連性が高いとみなし、どこを探索し、どのように理解したかを、マップ上の光の動きとして直感的に把握できます。このツールはローカルで動作し、セッションデータは外部に送信されません。

全文翻訳

mindwalk

コードベースの3Dマップ上でコーディングエージェントのセッションを再生する可視化ツール。

mindwalk-demo-en-tree-60s.mp4[動画]

問題点

セッションログはエージェントが何を行ったかを記録しますが、タスクをどのように理解したかは示しません。リポジトリのどの部分を関連性が高いとみなし、行動する前にどこを探求したか、そのフットプリントが意図したスコープと一致していたかなどです。生のJSONLを一行ずつ読むだけでは、これらの疑問には答えられません。

アイデア

リポジトリを夜の地図のように描き出し、セッションをその中を移動する光として再生します。エージェントが検索、読み取り、編集した場所は地図が光り、それ以外の場所は暗いままで、エージェントのタスク理解は一目でわかる形状になります。1つのGoバイナリがClaude Code、Codex、piのセッションログを完全にローカルで読み取ります。表示のために何も外部に送信しません。唯一の例外はオプションのセッション評価です。明示的に実行すると、そのセッションの要約(タスクの文言、ファイルパス、イベントのダイジェスト)が、あなたのclaudeまたはcodex CLIの背後にあるモデルに送信されます(セッション評価を参照)。

クイックスタート

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mindwalk

インストーラーはバイナリをchecksums.txtに対して検証し、~/.local/binにインストールします(INSTALL_DIRで上書き可能。リリースを固定するにはVERSIONを使用)。WindowsアーカイブはGitHub Releasesにあります。ソースからビルドするには: make setup && make build → bin/mindwalk。

引数なしで実行すると、mindwalkは~/.claude/projects、~/.codex/sessions、~/.pi/agent/sessionsをスキャンし、UIをランダムなローカルポートで提供し、ブラウザを開きます。

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR] [--pi-dir DIR]
mindwalk open [--no-open] <session.jsonl>   特定のセッションを1つ開く
mindwalk map [--no-open] <repo>             セッション不要でリポジトリマップを開く
mindwalk build <repo> [-o out]              リポジトリのシティマップJSONを書き出す
mindwalk trace <session> [-o out]           正規化されたトレースJSONを書き出す
mindwalk analyze <session> [--judge claude|codex] [--model name] [--no-rubric]
                                            1つのセッションを評価する(下記参照)

画面の見方

  • ツリー / 地形ビュー — リポジトリを放射状ツリーまたはツリーマップ平面として表示。光の強さは、ファイルがどれだけ深く、どれだけ頻繁に触られたかに比例します。
  • タッチ状態 — 各ファイルは最も深いタッチ状態を保持します: 閲覧済み(モスグリーン)、読み取り(月光ブルー)、編集済み(ウォームアンバー)、未訪問(ダーク)。セッションが触れたがリポジトリに存在しなくなったファイルは、ワイヤーフレームのゴーストとして残ります。HUDは、摩擦信号(エラー率、変更されたファイル、最後の検証後の編集)をレビュー用ストリップに折りたたみます。
  • 再生デッキ — 実行のバケット化されたヒストグラム上でセッションをスクラブまたは再生します。バーはクール/ウォームのスペクトル上に配置されます:観察(検索、読み取り、実行)はクールなまま(観測)、変更(編集、検証)はウォームに光ります(ミューテーション)。そのため、編集フェーズが一目で際立ちます。再開、速度、ビデオエクスポートはデッキの⋯メニューに折り込まれます。エクスポートは、再生を完全にクライアントサイドで.webmに記録します。
  • タイムラインマーク — ◇コンテキストの圧縮、○サブエージェントの起動、›ユーザーのターン。各マークはクリックしてジャンプできるターゲットです。
  • エージェントレンズ — セッションがサブエージェントを起動した場合、HUDにはサブエージェント数とエージェントパネルが表示されます。レンズを選択して同じマップ上で任意のサブエージェントのトレースを再生し、その後メインのトレースに戻ることができます。
  • インスペクター — ファイルをクリックするとその訪問履歴がピン留めされ、訪問行をクリックすると再生ヘッドがその瞬間にジャンプします。
  • 評価 — ローカルエージェントCLIにセッションの軌跡を評価させ、独自の要求から作成された基準に対してスコアリングします。セッション行には、評価状態が控えめなバッジとして表示されます。セッション評価を参照してください。
  • リポジトリマップ — mindwalk map <repo>(またはセッションレールのフォルダアイコン)は、セッションが添付されていない任意のリポジトリのシティマップをレンダリングします。高さは注意ではなく、コード行数をエンコードします。

[画像: 地形ビューでの同じセッション]

[画像: 同じセッション上のエージェントレンズ]

キーボード: Space 再生/一時停止 · ←/→ ステップ(⇧ ×10) · Home/End 終了 · S 速度 · V 表示 · E 次の編集 · X 次のエラー · M 次のマーク · ⌘B セッションレール。

セッション評価

評価パネル(およびmindwalk analyze)は、ローカルエージェントCLIにセッションの進行状況を評価させます。レポートには2つのレイヤーがあります。

  • プロセス次元 — 探索、スコープ、迷走、検証:4つの固定レンズで、すべてのセッションで同じなので、レポートは比較可能に保たれます。
  • タスクスコアカード — スコアリングの前に、ジャッジは独自の要求の文言から基準を作成します。このタスクにとって何が完了とみなされるか、セッションが複数のタスクを扱った場合はタスクごとにグループ化されます。各基準は、次元とともに、1回のパスでセッションに対してスコアリングされます。

どちらのレイヤーのすべての発見事項も、クリックして確認できるタイムラインイベントを引用する必要があります。そして、いかなる決定もモデルの判断ではありません。次元と基準の判定は、発見の深刻度から機械的に集計されます。ログが基準を満たしたかどうかを示せない場合、そのカバレッジは低下し、判定は「シグナルなし」と表示されます。検証不可能な基準は、失敗ではなく、盲点です。ジャッジ(インストールされているCLI)とそのモデルをパネルで選択します。レポートは、実際に誰が評価したかを記録します。

スコアカードは邪魔にならないように脇に置かれます。ツールイベントがないセッションやタスクテキストが少なすぎるセッションはスキップされ、基準のドラフトが失敗すると次元のみのレポートに格下げされます。--no-rubric(または分析APIの"rubric": false)は、1回のジャッジコールで明示的にスキップします。スコアカードがどのように構築されるか、そしてなぜそのように形状作られるかについては、docs/dynamic-rubric-evaluation.mdでカバーされています。

マシンから離れるもの、そして要求したときだけ離れるもの: 評価は、あなたのclaudeまたはcodex CLIを実行します。最大2回の密封された呼び出し、1回は基準のドラフト、もう1回はスコアリングです。どちらも、そのセッションの要約のみをモデルに送信します。ユーザーメッセージの文言、ファイルパス、および1行のイベントダイジェストです。セッションの表示中は何も送信されず、他のセッションも含まれません。ジャッジサブプロセスは密封された状態で実行されます。ツール、MCPサーバー、ユーザーまたはプロジェクト設定、セッションの永続性はありません。

レポートは~/.mindwalk/reportsにセッションごとにキャッシュされます。セッションの内容が変更されると、レポートは古くなります(自動再実行なし)。タスクの文言が変わっていないセッションを再評価すると、ドラフトされた基準が再利用されます。スコアは移動する可能性がありますが、物差しは移動しません。

内部構造

意図的に分離された3つのアーティファクト:

  1. トレース — セッションログをファイルタッチイベントの順序付けられたストリームに正規化したもの(internal/adapter、エージェント形式ごとに1つのアダプター)。アダプターはサブエージェントセッションをエージェントグラフに相関させるため、各サブエージェントのトレースを個別に再生できます。
  2. シティマップ — リポジトリの決定論的なレイアウト(internal/citymap)。同じツリーは常に同じマップを生成するため、再生はセッション間で比較可能です。
  3. レポート — LLMジャッジによる1つのセッションに関する証拠に裏打ちされた発見事項(internal/judge):4つの固定プロセス次元とタスク固有のスコアカード。ジャッジは発見事項のみを提供し、判定は常に機械的に集計されるため、レポートも比較可能です。

ローカルGoサーバー(internal/server)がこれらを結合し、React/Three.jsフロントエンド(web)を提供します。schema/はエクスポートされたJSONコントラクトをミラーリングします。

貢献

Issueとプルリクエストを歓迎します。動作する開発環境を設定するには:

make setup   # フロントエンドの依存関係をインストール
make serve   # 作業ツリーからweb/distを提供する:8765で開発サーバーを実行
make test    # go test + フロントエンドビルド — PR送信前に実行
make build   # 埋め込みアセットとbin/mindwalkを再生成

基本ルール(完全なアーキテクチャノートについてはAGENTS.mdを参照):

  • 境界を維持する: アダプターはレンダリングを知らず、シティマップ生成は再生に依存せず、ジャッジは正規化されたトレースのみを読み取り、サーバーはピースを接続するだけです。
  • Goコードはgofmtで整形してください。internal/server/staticは手動で編集せず、make buildで再生成してください。
  • トレース、シティマップ、またはレポートのJSON形状が変更された場合は、schema/と変更と同じ箇所にある関連テストを更新してください。

Star History

[画像: Star History Chart]

ライセンス

MIT © 2026 Ricko Yu