Install
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는 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 뷰로 변경을 한 군데씩 확인합니다. 실시간 변경과 실행 상태 패널에서 에이전트가 지금 무엇을 하는지 볼 수 있고, 계정이 지원되는 provider에 속해 있다면 사용량 모니터링도 같은 화면에 나타납니다. 이 사례의 가치는 변경 과정이 보인다는 점입니다. 뷰는 공식이 제공하고 변경 자체는 작업이 만들어내므로, 양쪽을 나란히 대조할 수 있습니다. 무엇을 바꿀지는 세션 안에서 에이전트와 함께 정하고, 공식 설명은 이 뷰와 상태 기능까지만 다루며 수정 품질을 보증하지 않습니다.
사용 경계
부작용과 확인 지점: gentle-pi를 설치하면 Pi 내장 codemode가 대체됩니다(compact renderer가 이어받음). 시작 경고는 예상된 현상이지 고장이 아닙니다. 그 밖의 명령 실행, 파일 읽기·쓰기, 네트워크 접근 범위에 대해서는 공식 설명이 없으며, 이런 동작이 일어나는지는 미지수이므로 읽기 전용이라고 단정하지 마세요. 세션에서 생긴 변경이 디스크에 어떻게 기록되는지, 단계마다 확인하는지에 대해서도 공식 설명은 절차를 다루지 않습니다. 세션에서 에이전트의 실제 행동을 관찰한 뒤 계속할지 결정하세요.
실행 환경 전제: Pi 세션 대상이며 npm으로 전역 설치합니다. 다른 에이전트에서 쓸 수 있는지, 어떤 코드나 텍스트 언어를 지원하는지는 공식 설명에 없습니다. 공식이 분명히 밝힌 제한은 두 가지입니다. 마이그레이션이 끝날 때까지 npm 패키지명과 저장소명은 gentle-pi 그대로이며, --link는 패키지의 로드 위치만 바꿉니다. 제품명과 패키지명의 불일치는 마이그레이션이 끝날 때까지 이어집니다. 아직 확인되지 않은 핵심 정보로는 설정 방법과 제거 방법, 제거 후 내장 codemode가 복원되는지, 그리고 SDD/OpenSpec, subagents, TDD 증거, review guardrails, skills, memory 연동을 각각 어떻게 활성화하는지가 있습니다. 공식은 이것들을 기능으로 나열할 뿐 절차는 제시하지 않습니다.