PotpieのコンテキストグラフをCLIで使う

Potpieのコンテキストグラフは何を扱うか

potpie-ai/potpieのREADMEと基線を読み、Context Graph for AI Native SDLC. Potpie turns your codebase and software development lifecycle into a living context graph for AI agents.という位置づけを日本語で整理します。ここで扱うのはリポジトリが明示する機能、導入条件、利用例、ライセンスです。メタデータのスター数は利用規模や品質を保証しないため、判断材料から切り離します。

README は Potpie を、コードベースとソフトウェア開発ライフサイクルを AI エージェントのための生きたコンテキストグラフに変えるツールとして説明しています。グラフはコード、構造、決定、ソース履歴、チーム知識、エンジニアリングワークフローをインデックス化します。意図された効果は、エージェントがプロジェクト固有のコンテキストで質問に答え、変更を計画し、障害をデバッグし、コードを書けるようになることです。リポジトリの説明「Context Graph for AI Native SDLC」はこの枠組みと一致し、ホームページは potpie.ai です。

PyPIから導入するCLIとローカル構成

インストールは PyPI 経由です。README は uv tool install potpie と python3 -m pip install --user potpie の2つのコマンドを示し、Python パッケージのグローバルな変更は一般的に推奨されないため uv 形式を推奨しています。インストール後、potpie setup がウィザードを実行し、ローカル設定、ストレージ、デーモン、デフォルトの pot、エージェントスキルをプロビジョニングし、統合と Potpie が設定すべきコーディングハーネスを選択できます。README は別途手動のインジェスト手順がないことを明示しています。CLI がソースを登録し、設定されたエージェントがタスクに必要なときにプロジェクトコンテキストを取り込むか更新します。potpie ui はブラウザでグラフエクスプローラを開きます。

resolveとsearchで作業前の情報を絞る

主要な CLI コマンドは表にまとめられています。potpie setup は初回のローカル設定を実行します。potpie login はアカウント連携および管理機能にサインインします。potpie github login と potpie linear login はソース統合を接続します。potpie status はアクティブな pot のコンテキスト準備状態を表示し、デーモン、グラフ、スキルチェックをカバーします。potpie auth status と potpie auth status --verify は統合資格情報を確認します。potpie doctor はデーモン、バックエンド機能、スキルドリフトのローカル診断を実行します。potpie source add repo . は現在のリポジトリをソースとして登録します。potpie pot list と potpie pot use はアクティブなワークスペースを選択します。potpie resolve はタスク前にエージェントが読むべきコンテキストを取得します。potpie search はファイル、ワークフロー、バグ、決定、慣習を検索します。potpie record は永続的なプロジェクト学習を書き込みます。potpie graph は低レベルのグラフ読み取り、品質チェック、提案、コミットを扱います。potpie ui はローカルのグラフエクスプローラを開きます。potpie skills install はエージェントハーネスのガイダンスをインストールまたは更新します。例としては potpie resolve "what should I know before working in this repository?" や potpie record --type decision --summary "Prefer the Potpie CLI for graph work" があります。

GitHub系データとエージェントハーネス

README は4つのソース統合を挙げています。GitHub（リポジトリ、プルリクエスト、イシュー、レビュー、ソース履歴）、Linear（チーム、イシュー、プロジェクト、ドキュメント）、Jira（プロジェクト、イシュー、ステータス、チェンジログ）、Confluence（スペース、ページ、ランブック、決定）です。また4つのコーディングハーネスを挙げています。Claude Code、OpenAI Codex、Cursor、OpenCode で、Potpie は最初の3つには指示とスキルをインストールし、OpenCode にはスキルをインストールします。README は加えて多くの統合とハーネスが予定されており、リクエストはイシュートラッカーで受け付けるとしています。

CLIファーストの境界と確認できない保証

README は現在のアーキテクチャが CLI ファーストであり、CLI は人間とエージェントの両方が使うように設計されていると述べ、詳細は docs/context-graph/architecture.md にあります。リポジトリメタデータは言語を Python、執筆時点で 5,531 スター、642 フォーク、101 のオープンイシューと記録しており、プロジェクトはアーカイブされていません。README はセットアップウィザードとステータス出力で言及されるデーモン、pot、スキル以外の内部コンポーネントを説明していません。

Apache 2.0での利用判断

Potpie は Apache 2.0 でライセンスされています。ライセンス抜粋は、複製、二次的著作物の作成、公開表示・上演、サブライセンス、配布のための永続的、世界的、非独占的、無償、ロイヤルティフリー、取消不能の著作権ライセンスを付与します。また、貢献によって必然的に侵害される特許請求項のための特許ライセンスも付与します。抜粋は部分的であるため、再配布の完全な条件、保証の免責、責任の制限を確立していません。README はパフォーマンスベンチマーク、本番結果、セキュリティ保証、サポート約束を述べていません。コミュニティチャネルは、バグとリポジトリ範囲のリクエストには GitHub Issues、議論には Discord、セットアップと製品ガイドには docs.potpie.ai です。

Potpieの確認では、まずuv tool install potpieでCLIを分離して入れ、potpie setupが作成したローカル設定、ストレージ、デーモン、既定のpotを確認します。次にpotpie source add repo .で対象リポジトリを登録し、potpie statusでデーモン、グラフ、スキルの状態を読みます。作業前の質問はpotpie resolve、特定の規約や履歴はpotpie searchに分けると、何を根拠にエージェントが回答したかを追いやすくなります。potpie uiのグラフ表示と実ファイルの対応も照合対象です。GitHubやLinearを接続する場合は、auth statusとauth status --verifyの結果を保存し、権限範囲を確認します。

potpie-ai/potpieについて記録を残すときは、READMEに書かれた版、入力、出力、実行環境を一組にします。たとえばCLIなら実行したコマンドと標準出力、サーバー連携なら接続先の種類と応答、配布物ならファイル形式と端末を対応づけます。機能名だけを転記すると、同名の機能でも対象サービスやOSが違う場合に結果を取り違えます。READMEが説明していない既定値は推測で埋めず、設定ファイル、ログ、リリースノートのどこで確認できたかを作業記録に書きます。更新時は変更前後の差分を同じ入力で比較し、失敗した条件も残します。対象プロジェクトの実行結果とREADMEの表現が食い違った場合は、成功例だけを採用せず、再現条件と失敗理由を分けて保存します。

編集部の結論

PotpieのコンテキストグラフをCLIで使うは、READMEに記載された対象環境と作業目的が一致するチームに向きます。向かないのは、未記載の性能、対応範囲、運用保証を前提に短時間で本番採用を決めるケースです。先にREADMEにある導入コマンドと、対象データを入力したときの具体的な出力を確認してください。記載のない性能や安全性は、このJSONからは判断できません。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes