インストール
npm i -g gentle-piどんな人に向くか
Gentle Shell が向いているのは、すでに Pi というコーディングエージェントを使っており、制御された開発を求め、エージェントが手を加える前にまず探索すること、本当に判断が必要な点だけを質問すること、小さく理解し終えた作業は小さなステップのまま進むことを期待する開発者です。公式はこの日常のワークフローをオーガニック駆動開発（Organic Driven Development、ODD）と呼び、エージェントは何かを変える前に探索し、本当に必要な決定だけを明確にし、小さく理解された作業は小さく保つ、と説明しています。導入後は、いつもの Pi セッションがワークスペースに変わります。エージェントのオーケストレーション、ライブな変更と実行状態、対応プロバイダーアカウントの使用量モニタリング、内蔵 diff ビューが同じ画面に集まり、公式はこのほかにオプションの SDD/OpenSpec、subagents、TDD エビデンス、review guardrails、skills、memory 連携を挙げています。
向かない場合や前提条件：Pi を使っていない場合、他のエージェントの上で動くかどうかは公式に記載がありません。公式の移行が完了するまで、npm パッケージ名もリポジトリ名も gentle-pi のままであり、製品名とパッケージ名は一致していません。どの OS が必要か、Pi はどのバージョンを求めるのか、公式説明には書かれていないので、自分で確認してから導入してください。
3 分で最初の試用を終える
まず、公式がはっきり明言しているインストール時の副作用を一つ受け入れるところから始めます。gentle-pi は Pi 内蔵の codemode 拡張を自分の compact renderer で置き換えるため、以後 Pi を起動するたびに内蔵版が読み込まれなかったという警告が出ます。つまり、この副作用はインストールの時点で起こるのであって、後のタスク実行中に起こるのではありません。入れるか入れないかの決定は、この副作用を受け入れるかの決定そのものです。内蔵 codemode の挙動に依存している人は、まず評価してから導入してください。それ以外の人は、この起動時警告を予期された現象として扱えば構いません。
推奨されるメイン経路は一つだけです。ターミナルで npm i -g gentle-pi を実行してグローバルインストールしてください。インストール後に gentle-shell を起動すると Pi が開き、Gentle Shell パッケージは専用のホーム ~/.gentle-shell/agent から読み込まれます。既存の ~/.pi/agent から読み込みたい場合は、起動時に --link を付けます。これは公式が用意した読み込み場所の切り替えであって、別のインストール方法ではありません。どちらの場所も公式の説明に載っているので、どちらかを選べば十分です。
成功のサインは公式の説明によると二つあります。一つは、起動後に開かれるのが Gentle Shell パッケージを読み込んだ状態の Pi セッションだということ。もう一つは、内蔵 codemode が読み込まれなかったという起動時警告が表示されることで、これは置き換えが効いている証拠そのものです。どちらも起動直後の最初の画面で確認でき、内容を変えるようなタスクを先に実行する必要はありません。最初のタスクには、対象がコードの純粋に分析的な小さなタスクを選びましょう。たとえば、あるモジュールを読ませて構造と呼び出し関係を説明させるもので、この段階ではまだ何も変更させません。ODD の道筋はもともと探索が先なので、この段階で変更は生じません。もっとも、その後タスクを実行するときにファイルを直接書き換える、コマンドを実行する、ネットワークへアクセスする、といったことがあるかどうかは公式説明に明記されておらず、確認済みの事実として扱えません。手を付ける前にセッションの中で確かめてください。
使用例
例 1：見慣れないコードを理解する。セッションで次のようなタスクを出します。まずあるモジュールを読み、その責務と依存関係を説明すること。ファイルは変更しないこと。これは ODD の日常経路そのもので、エージェントはまず探索し、本当に判断が必要な点についてだけ質問し、小さなタスクは小さく保たれます。探索の後に質問が返ってきたなら、公式の ODD の説明に照らせば、それは意思決定に実際に影響する問いであるはずです。期待できる結果は探索に基づく説明で、返答の形式は公式には定義されていないので、セッションの実際の出力を基準にしてください。
例 2：変更しながら照合する。エージェントに小さな変更をさせながら、内蔵 diff ビューで変更箇所を一つずつ確認します。ライブな変更と実行状態のパネルを見れば、エージェントが今何をしているかが分かります。アカウントが対応プロバイダーに属していれば、使用量モニタリングも同じ画面に現れます。この例の価値は、変更の過程が見えることにあります。ビューは公式が提供し、変更そのものはタスクが生み出すので、両者を並べて照らし合わせられます。何を変えるかはセッションの中でエージェントと合意して決めます。公式説明が対象にしているのはこれらのビューと状態表示の機能だけで、書き換えの品質を保証するものではありません。
利用の境界
副作用と確認ポイント：gentle-pi をインストールすれば Pi 内蔵の codemode が置き換わります（compact renderer が引き継ぎます）が、起動時警告は予期された現象であり、故障ではありません。それ以外の、コマンド実行・ファイルの読み書き・ネットワークアクセスの範囲については公式の説明がなく、こうした挙動が起こるかどうかは未知です。読み取り専用だと決め込まないでください。セッション中の変更がどうディスクに書き込まれるのか、一歩ごとに確認が入るのかについても、公式説明は操作の詳細に触れていません。セッションの中でエージェントの実際の挙動を観察してから、続けるかどうかを判断してください。
実行環境の前提：Pi セッション向けで、npm によるグローバルインストールです。他のエージェントで使えるか、どのコードやテキストの言語に対応するかは、公式説明にありません。公式がはっきり示している制限は、移行が完了するまで npm パッケージ名とリポジトリ名は gentle-pi のままであること、そして --link がパッケージの読み込み場所を切り替えるだけであることです。製品名とパッケージ名の不一致は移行の終わりまで続きます。まだ確認できていない重要な情報としては、設定方法とアンインストール方法、アンインストール後に内蔵 codemode が復元されるかどうか、そして SDD/OpenSpec、subagents、TDD エビデンス、review guardrails、skills、memory 連携のそれぞれをどう有効化するかが挙げられます。公式はこれらを能力として列挙しているだけで、手順は示していません。