安裝
npm i -g gentle-pi適合誰
Gentle Shell 適合這樣的開發者：已經在用 Pi 這個編碼代理，想要受控開發，希望代理在動手改程式之前先探索、只就真正的決策點提問，並把小任務保持在理解範圍內、小步推進。官方把這條日常工作流稱為有機驅動開發（Organic Driven Development，ODD），並描述為：代理先探索再改動，只澄清真正的決策，小而已被理解的工作就保持在小步裡。安裝完成後，一個普通的 Pi 工作階段會變成工作檯：代理編排、即時變更與執行狀態、受支援 provider 帳號的用量監控、內建 diff 檢視集中在同一個介面；官方還列出可選的 SDD/OpenSpec，以及 subagents、TDD 證據、review guardrails、skills 與 memory 整合。
不適合或需要前提的情況：如果不使用 Pi，官方沒有說明它能在其他代理裡執行；在官方遷移完成之前，npm 套件名稱與儲存庫名稱都仍是 gentle-pi，產品名稱與套件名稱並不一致。它需要哪些作業系統、Pi 需要什麼版本，官方說明沒有提到，需要自行確認後再安裝。
3 分鐘完成第一次嘗試
先接受一個安裝期的副作用，這是官方明說的：gentle-pi 會用它自帶的 compact renderer 取代 Pi 內建的 codemode 擴充功能，之後每次啟動 Pi 都會提示內建版沒有載入。換句話說，這個副作用發生在安裝這一步，而不是某次任務執行中；裝與不裝的決定，就是接不接受它的決定。依賴內建 codemode 行為的人應先評估再裝；其他人可以把這條啟動警告當作預期現象。
推薦的主路徑只有一條：在終端機全域安裝 npm i -g gentle-pi。安裝後啟動 gentle-shell，它會開啟 Pi，並從自己的主目錄 ~/.gentle-shell/agent 載入 Gentle Shell 套件；如果想改成從既有的 ~/.pi/agent 載入，啟動時加 --link 參數。這只是官方提供的載入位置切換，不是另一條安裝方式，兩個位置都在官方說明裡，選一個即可。
成功訊號按官方說明有兩處：一是啟動後開啟的是載入了 Gentle Shell 套件的 Pi 工作階段；二是出現內建 codemode 未載入的啟動警告，這恰恰說明取代已經生效。這兩處都能在啟動後的第一個畫面觀察到，不需要先跑任何會更動內容的任務。第一次任務建議選純分析型的小任務，對象是程式碼，例如讓代理讀完某個模組並解釋它的結構與呼叫關係，暫時不讓它改任何東西。ODD 的路徑本來就是先探索再動手，這個階段不會產生變更；至於它後續執行任務時會不會直接寫檔、執行指令或存取網路，官方說明沒有寫明，不能當成已確認的事實，動手前先在工作階段裡確認。
使用案例
案例一：理解一段陌生程式碼。在工作階段裡發起這樣的任務：先讀某個模組，說明它的職責與相依關係，不要改檔案。走的是 ODD 日常路徑——代理先探索，只就真正的決策點提問，小任務保持小步。如果代理在探索後提問，按官方對 ODD 的描述，這些應當是真正影響決策的問題。可期待的結果是一份基於探索的解釋；具體回覆格式官方未定義，以工作階段實際輸出為準。
案例二：邊改邊核對。讓代理做一個小更動，同時用內建 diff 檢視逐處檢查變更，即時變更與執行狀態面板能讓你看到代理正在做什麼；如果你的帳號屬於受支援的 provider，用量監控也會出現在同一個介面。這個案例的價值在於改動過程可見：檢視由官方提供，改動本身由任務產生，兩邊可以對照著看。改什麼由你與代理在工作階段裡商定，官方說明只涵蓋這些檢視與狀態能力，不擔保改寫品質。
使用邊界
副作用與確認點：安裝 gentle-pi 即取代 Pi 內建的 codemode（由 compact renderer 接手），啟動警告是預期現象而非故障；除此之外，它的指令執行、檔案讀寫與網路存取範圍官方沒有說明，是否產生這些行為屬於未知，不要預設它唯讀。關於工作階段中產生的變更如何寫入磁碟、是否逐步確認，官方說明沒有提到操作細節，只能在工作階段裡觀察代理的實際行為後，再決定是否繼續。
執行環境前提：面向 Pi 工作階段，經 npm 全域安裝；能否在其他代理中使用、支援哪些程式碼或文字語言，官方說明未提到。官方明確的限制：npm 套件與儲存庫名稱在遷移完成前維持 gentle-pi，產品名稱與套件名稱不一致的狀態會持續到遷移結束；--link 只切換套件的載入位置。尚未確認的關鍵資訊還包括：如何設定與解除安裝、解除安裝後內建 codemode 是否恢復，以及 SDD/OpenSpec、subagents、TDD 證據、review guardrails、skills、memory 整合各自怎麼啟用——官方只把它們列為能力，沒有給出操作步驟。