goaltree

GoalT（Goal Tree）

複数の親を持ち、価値が伝播する目標グラフです。構想段階のオープンソースプロジェクトで、問題点を指摘してくれる方を探しています。

アイデア

多くの優先順位付けツールは、きれいな階層構造を前提としています。1つの目標がサブ目標に分かれ、そのサブ目標がさらに小さな目標に分かれる、という具合です。しかし、実際の仕事はそのような形になることはほとんどありません。ある機能が同時に2つの別の要素に依存することもあれば、1つのバグ修正が3つの異なる取り組みに、それぞれ別の理由で貢献することもあります。ツリーではそうした関係を表現できません。グラフなら表現できるかもしれません。

GoalT は、まさにそのための小さなエンジンです。

• ルート目標は1つです。 すべてはそこにつながっています。
• すべての目標は、複数の子と複数の親を持つことができます。 ツリーではなく DAG です。
• 各親は、子の間で価値を合計1.0だけ配分します。
• 複数の親を持つ目標は、それぞれの親から価値を受け取ります。 そのため、本当に多くのことに貢献する目標は自然と上位に浮かび上がります。
• 目標を追加すると、グラフ全体ではなく、影響を受ける部分だけを再計算します。
• 循環は明示的に拒否され、黙ってループすることはありません。

価値の再配分（親が子の間で自身の価値をどのように分けるか）は、プラグインで変更できます。デフォルトでは単純な均等分割です。決定論的で、API キーは不要で、必ず収束します。代わりに LLM を使い、状況に応じて重みを決めることもできます（例：「今週のスプリントでは、仕上がりより速度を重視する」）。エンジンは LLM の数値をそのまま信用しません。返された値は必ず検証され、再正規化されるため、モデルが異常な値を返した場合でもグラフの数学的な整合性が保たれます。

インストールせずに試す

上の「Open in Colab」バッジをクリックしてください。セットアップ不要で、ブラウザーで demo.ipynb が開きます。セルを上から順に実行してください。

ローカルインストール

要件： Python 3.10 以降（Claude Code サーバーに必要な mcp パッケージが要求します）。macOS で pip install が「Requires-Python >=3.10」や「No matching distribution found for mcp」のようなエラーで失敗する場合は、Python が複数インストールされていて、pip が誤った方を参照している可能性があります（Xcode Command Line Tools に同梱された Python でよく発生します）。python3 --version で確認し、3.10 以降であれば、pip install ... とだけ実行するのではなく、python3 -m pip install ... を使用してください。これにより、サーバーの実行に使われる Python と同じ環境にパッケージがインストールされます。

python3 -m pip install goaltree

コアエンジンに必要なのは networkx だけです。より大きな機能は追加パッケージとして提供されているため、実際に使うものだけをインストールしてください。

python3 -m pip install "goaltree[viz]"   # + matplotlib, for visualize.draw
python3 -m pip install "goaltree[mcp]"   # + the Claude Code MCP server and dashboard
python3 -m pip install "goaltree[all]"   # everything

ソースからインストールする場合：

git clone https://github.com/GOAL-T/goaltree.git
cd goaltree
python3 -m pip install -e ".[all]"

from goaltree import GoalGraph

g = GoalGraph()
g.add_root("root", "Ship v2 of the product")
g.add_goal("a", "Improve onboarding", parents=["root"])
g.add_goal("b", "Improve performance", parents=["root"])
g.add_goal("c", "Fix export bug", parents=["a", "b"])  # depends on both

print(g)

GoalGraph(root='root')
  1.000  Ship v2 of the product (root)
  1.000  Fix export bug (c)
  0.500  Improve onboarding (a)
  0.500  Improve performance (b)

c が1.000になり、ルートも1.000になること、そして a、b、c の合計がルートを上回ることに注目してください。これは意図的な動作であり、バグではありません。価値はグラフ全体ではなく、親ごとに保たれます（各親は子の間で合計1.0を分配します）。2つの親を持つ目標は、両方から価値を受け取ります。

つまり、この数値は固定予算に対する取り分ではなく、ルートの1.0と比較しても意味はありません。これは引き寄せの重みであり、「これにどれだけのものがかかっているか」に答えるものであって、「プロジェクトのどの割合を占めるか」に答えるものではありません。この例では、エクスポートのバグは両方のサブ目標に不可欠です。そのため、このバグが重要になることなく、グラフ内のほかの作業を進めることはできません。1.000はまさにそれを表しています。

LLM を使った再配分の例を含む詳しい手順については、demo.ipynb をご覧ください。

Claude Code 内で使う

GoalT は Claude Code プラグインとして提供されています。MCP サーバー（会話中にツリーを作成、照会）と、サーバーと同時に自動起動し、Claude が現在取り組んでいる目標をリアルタイムで強調表示するライブダッシュボードが含まれています。

プラグインとしてインストールする（推奨）

まず、サーバーの依存関係を一度だけインストールします。

python3 -m pip install "goaltree[mcp]"

次に、Claude Code 内で以下を実行します。

/plugin marketplace add GOAL-T/goaltree
/plugin install goalt@goalt-marketplace

これにより、MCP ツールとアクティビティフックの両方が自動的に設定されます。GoalT は、サーバーの起動時にパッケージをインストールすることは意図的にありません。起動時に pip install を実行するプラグインは、確認したばかりのリポジトリの外からネットワーク経由でコードを取得します。そこまでプラグインを信頼する必要があるような状況であってはなりません。依存関係が不足している場合、サーバーは代わりに実行すべきコマンドを正確に示し、裏で何かをインストールすることはありません。

手動インストール（アクティビティフックなしでも動作します）

git clone https://github.com/GOAL-T/goaltree.git
cd goaltree
claude mcp add --transport stdio goalt -- bash "$(pwd)/bootstrap.sh"

これでツールは使えるようになりますが、「Claude は現在……」というアクティビティの通知は自動化されません。この機能はプラグインのフックに依存しており、上記のプラグインのインストール手順でのみ登録されます。

使用方法

既存のコードベースのオンボーディング： 計画を立てたいプロジェクトで、/goalt:start スラッシュコマンドを実行します。Claude はリポジトリ（README、パッケージマニフェスト、フォルダー構成、存在する場合はデータベースのマイグレーション）を調査し、実際の機能領域を特定して、実際に各ゴールを実装していると確信できるファイルやバックエンドの成果物（データベーステーブル、エッジ関数など）を関連付けた、実際の内容に基づく説明付きのツリーを作成します。構造をでっち上げることはありません。

ゼロから始める場合、 Claude Code のセッションで次のように指示します。

「製品の v2 をリリースするためのゴールツリーを作成してください。サブゴールとしてオンボーディングとパフォーマンスを追加し、両方に依存する共通のバグ修正も追加してください。優先度を表示して、ダッシュボードを開いてください。」

Claude は create_tree、add_goal、list_priorities を呼び出し、その後 open_dashboard によってブラウザーで開くための URL（http://127.0.0.1:8765）を表示します。そこから、次の操作ができます。

• 監視モード：Claude の作業中、ダッシュボードを開いたままにします。ヘッダーにはツール呼び出しのたびに「Claude is currently...」というライブインジケーターが表示されます。Claude Code のフックを通じて連携されているため、確実に表示されます。
• ファイル編集のハイライト（確実）：ゴールに related_files が関連付けられると、そのファイルを編集した際に、追加のツール呼び出しなしで、該当するゴールが光る緑色の枠で自動的に強調表示されます。フックが編集されたパスと、各ゴールの関連ファイルを照合します。
• 自己申告によるハイライト（ベストエフォート）：特定のファイルに明確に対応しないゴールについては、Claude が理由を付けて set_active_goal を呼び出すことができます。ベストエフォートであり、Claude が呼び出すことを選んだ場合にのみ機能するため、確実ではありません。
• 未コミット変更の追跡：ツリーの作成時に project_root が設定されている場合、バックグラウンドスレッドが数秒ごとに git status をポーリングします。関連ファイルに未コミットの変更があるゴールは、現在編集中かどうかに関係なく、琥珀色の枠で表示されます。
• ノードをクリックすると、2 つのタブを備えたサイドパネルが開きます。説明（ゴールの説明と関連ファイル／バックエンドの成果物）と変更（このゴールに固有の、現在編集中および／または未コミット変更のあるファイル）です。現在アクティブなノード、または未コミットの変更があるノードをクリックすると、最初から「変更」タブが開きます。
• VS Code でファイルを開く：関連ファイルまたは変更に表示されるすべてのファイルは、クリック可能なリンク（vscode://file/...）になっており、クリックすると VS Code で直接開きます。VS Code がインストールされていれば、そのまま使え、設定は不要です。未コミット変更のあるファイルには、適切な左右並列の差分（HEAD と作業コピー）を開く差分ボタンも表示されます。macOS では VS Code を直接起動するため、PATH の設定は不要です（VS Code がインストールされていれば動作します）。それ以外の環境では、PATH に code CLI があればそれを使用します。どちらも利用できない場合、ボタンは黙って失敗せず、代わりに必要な操作を明確に伝えます。
• ノードをドラッグして並べ替えます。位置は保持されるため、次回の更新で元に戻ることはありません。「レイアウトをリセット」をクリックすると、グラフが自動的に再配置されます。

利用可能なツール： load_tree、create_tree、add_goal、link_artifacts、list_priorities、set_active_goal、clear_active_goal、open_dashboard、reset_tree。

現在の制限事項：

• ツリーは変更のたびに <project_root>/.goalt/tree.json に自動保存され、次のセッションで自動的に読み込まれます（起動時のベストエフォートによる推測、または Claude が実際のプロジェクトルートを把握した後に load_tree を実行することで確実に読み込まれます。システム指示により、まずプロジェクトルートを確認します）。コミットしたくない場合は、プロジェクトの .gitignore に .goalt/ を追加してください。
• ファイルとゴールの照合（goals_for_file）には、正確なパス解決ではなく、ヒューリスティックなサフィックス照合を使用します。そのため、通常とは異なるプロジェクト構成では、曖昧な相対パスが誤って照合される場合があります。
• 未コミット変更の追跡では、project_root に単一の Git リポジトリがあることを前提とし、一定間隔（数秒ごと）で再ポーリングするため、変更が発生してから表示されるまでにわずかな遅れが生じます。

このリポジトリに実際に含まれているもの

• goaltree/goal_tree.py -- コアエンジンです。グラフの構築、循環の検出、決定論的な値の伝播、プラグイン可能な LLM 再分配フックを担います。オプションの依存関係がなく、goaltree から直接再エクスポートされる唯一のモジュールです。

• goaltree/visualize.py -- demo.ipynb で静的なグラフ画像を描画するために使われる、matplotlib/networkx の薄いラッパーです。[viz] エクストラが必要です。

• demo.ipynb -- インタラクティブに実行できるチュートリアルです（Colab で動作し、ローカル環境のセットアップは不要です）。

• goaltree/mcp_server.py -- MCP サーバーです。ツリーの構築・照会用ツールに加え、ベストエフォートでアクティブな目標を追跡します。読み込み時にダッシュボードを自動で起動します。[mcp] エクストラが必要です。

• goaltree/dashboard.py -- ライブでインタラクティブな Web ダッシュボードです（FastAPI + vis-network、単一ファイルで、ビルド手順は不要）。Claude Code の PreToolUse フックが呼び出すフックエンドポイントも含まれています。[mcp] エクストラが必要です。

• pyproject.toml -- パッケージングのメタデータです。goalt-mcp コンソールスクリプトも定義しており、これは python -m goaltree.mcp_server に短い名前を付けたものです。

• .claude-plugin/plugin.json、.claude-plugin/marketplace.json、.mcp.json、hooks/hooks.json -- 2つのコマンドで全体をインストールできるようにするプラグインのパッケージングです（上記を参照）。

• commands/start.md -- 既存のコードベースに GoalT を導入する /goalt:start スラッシュコマンドです。

• bootstrap.sh -- プラグインの実際のエントリーポイントです（.mcp.json を参照）。実行時に Python 3.10 以降のインタープリターを探すため、マシン固有のパスはどこにもハードコードされていません。サーバーの依存関係をインポートできるか確認し、できない場合はコピーして実行できるインストールコマンドを表示して起動を拒否します。設計上、このスクリプト自体が何かをインストールすることはありません。

• hooks/hooks.json、hooks/pulse.py -- アクティビティパルスです。Claude Code は PreToolUse フックにツールのペイロード全体を渡します。Write の場合は書き込み対象のファイル全体が含まれます。pulse.py は POST する前に、ツール名とファイルパスだけを抽出し、127.0.0.1 のダッシュボードに送信します。コマンドはプレビューも含めて一切送信されないため、シェル呼び出しは「Running: Bash」と表示されます。フックプロセスの外に出るものはほかにありません。

• tests/ -- コアエンジン、ダッシュボードの API／フックのロジック、MCP ツールのエンドツーエンドテスト（実際の MCP クライアントを使用し、Claude Code が接続するのと同じ方法で実行）を網羅する62件のテストです。詳しくは以下の「テストの実行」を参照してください。

CLI はまだありません。要望があれば、次の自然なステップとして追加できます。

テストの実行

python3 -m pip install -e ".[dev]"
pytest

3つのファイルにまたがる62件のテストです。

• tests/test_goal_tree.py -- コアエンジンをテストします（複数親からの値の伝播、循環処理、成果物のリンク、ファイルの照合、保存／読み込みの往復）。I/O は行いません。
• tests/test_dashboard.py -- 純粋なヘルパー関数、未コミットの変更の検出に使う実際の git フィクスチャ、VS Code の差分表示フォールバックチェーン（モックを使用し、GUI は不要）、および TestClient 経由の FastAPI エンドポイントをテストします。
• tests/test_mcp_server.py -- 統合テストです。実際の MCP クライアントが stdio 経由で実際の goaltree.mcp_server サブプロセスと通信し、実際のツール（create_tree、add_goal、link_artifacts、set_active_goal、load_tree／永続化、reset_tree）をテストします。各テストで実際のプロセスを起動するため、全体で約30秒かかり、実行時間は長めですが、Claude Code が呼び出すツールレイヤーを実際にテストできます。

既知の未解決事項

過大に宣伝するのではなく、率直にお伝えします。

• LLM 駆動の重みによる収束。 決定論的なフォールバックは、設計上、常に収束します。一方、大規模なグラフで何度も編集を繰り返したときに、LLM 駆動の再重み付けが安定し続けるかどうかは証明されておらず、小規模な例で確認されているだけです。
• グローバルな値は保存されません。 ノードが複数の親を持てるため、グラフ内のすべてのノード値の合計は全体で 1.0 にはなりません。1.0 になるのは各親のもとでの子ノードの重みの合計だけです。これは意図的な設計です（「実際の依存関係が多いほど引き寄せが強くなる」仕組みを実現しています）が、数値を深読みする前に理解しておく必要があります。
• 大規模運用時のコスト。 実際の LLM を接続した場合、add_goal を呼び出すたびに、影響を受ける親ごとに再分配の呼び出しが発生する可能性があります。大規模で深いグラフでは、編集ごとに多数の API 呼び出しが必要になるかもしれません。キャッシュやバッチ処理はまだ実装されていません。
• ベンチマークはまだありません。 実際のバックログで、従来の優先順位付け手法（AHP、重み付けスコアリング、単純な OKR のカスケード）との比較はまだ行われていません。この比較は自然な次のステップであり、すでに行ったと主張しているわけではありません。
• 循環検出は現在、積極的な保護策ではなく、事後的な安全策です。 公開されている add_goal API だけを通じて循環が発生することは、設計上あり得ません（新しいノードにはまだ出辺がないためです）。このチェックが必要になるのは、既存の 2 つの目標を結び付ける将来の機能を計画しているためです。その機能では、循環が実際に発生し得ます。
• 起動時の自動読み込みは推測に基づくもので、保証されていません。 サーバーの起動時に GoalT は、プロジェクトルートの推測値として自身のプロセスの作業ディレクトリを使い、保存済みのツリーの読み込みを試みます。Claude Code がたまたまプロジェクトをルートとする形で MCP サーバーを起動した場合は機能しますが、保証はありません。確実な方法は明示的な load_tree ツールです。システム指示では、ツリーが存在しないと判断する前に、実際のプロジェクトルートを指定して Claude にこのツールを最初に呼び出すよう伝えています。
• 既存の研究との関係。 値の伝播の仕組みは、DAG 上の PageRank 型アルゴリズムと密接に関連しています。これをより良く解決する先行研究をご存じでしたら、ぜひ issue を作成してください。既存のものを作り直すつもりはなく、本当に関心があります。

貢献

issue や PR を歓迎します。CONTRIBUTING.md をご覧ください。機能を拡張するのと同じくらい、問題を見つけて壊してみることも役に立ちます。グラフが誤った結果や不安定な結果を出すケースを見つけたら、それこそ今まさに必要としているフィードバックです。

ライセンス

Apache 2.0。LICENSE をご覧ください。商用かどうかを問わず、利用、フォーク、構築が可能です。