Claude Code나 Codex처럼 기능이 풍부한 코딩 에이전트가 넘쳐나는 시대에 Pi는 반대 방향을 택했다. 서브에이전트도 없고, 계획 모드도 없고, 권한 팝업도 없다. 시작점은 read, write, edit, bash 네 가지 도구뿐이다. 그 위에 필요한 것을 자신이 직접 올린다. “There are many agent harnesses, but this one is yours.” Pi의 철학이 이 한 문장에 담겨 있다.
최소주의가 단순히 기능 부족을 의미하지는 않는다. Pi는 15개 이상의 AI 제공자, 수백 개의 모델을 지원하고, 2,700개가 넘는 커뮤니티 패키지를 npm 방식으로 설치해 확장할 수 있다. 대화형 TUI, 스크립트용 출력 모드, JSON 이벤트 스트림, RPC, SDK까지 실행 방식도 다양하다. 필요한 것만 올려서 자신의 워크플로우에 맞게 조립하는 방식이다.
설치
네 가지 방법 중 하나로 설치한다.
# curl (권장 — 가장 빠름)
curl -fsSL https://pi.dev/install.sh | sh
# npm
npm install -g @earendil-works/pi-coding-agent
# pnpm
pnpm add -g @earendil-works/pi-coding-agent
# bun
bun add -g @earendil-works/pi-coding-agent
설치 후 프로젝트 디렉토리에서 pi를 실행하면 대화형 TUI가 시작된다. API 키는 환경 변수로 넘기거나(ANTHROPIC_API_KEY 등), Pi 구독을 쓰는 경우 /login으로 인증한다. 로컬 모델을 쓴다면 models.json으로 연결한다(뒤에서 다룬다).
기본 실행 방법
pi # 대화형 TUI 시작
pi "src 폴더의 .ts 파일 목록을 알려줘" # 초기 프롬프트로 바로 시작
pi -p "이 코드베이스를 요약해줘" # 응답 출력 후 종료
cat README.md | pi -p "이 텍스트 요약" # 파이프 입력
pi -c # 가장 최근 세션 이어서 시작
pi -r # 세션 선택 인터페이스 열기
파일을 직접 첨부할 때는 @ 문법을 쓴다.
pi @prompt.md "이 지침에 따라 작업해줘"
pi -p @screenshot.png "이 이미지에 뭐가 있어?"
pi @src/api.ts @src/api.test.ts "이 파일들 리뷰해줘"
CLI 주요 옵션
모델 옵션
--provider <이름> — 사용할 AI 제공자를 지정한다. openai, google, anthropic, lmstudio 등 15개 이상을 지원한다.
--model <패턴> — 모델 ID나 패턴으로 모델을 선택한다. provider/model-id 형식으로 제공자를 함께 지정할 수 있다.
--thinking <레벨> — 사고(thinking) 수준을 설정한다. off, minimal, low, medium, high, xhigh 중 선택한다. 지원하는 모델에서만 동작한다.
--models <패턴들> — Ctrl+P로 순환할 모델 목록을 쉼표로 구분해 지정한다. claude-*,gpt-4o처럼 와일드카드도 된다.
--list-models [검색어] — 현재 제공자에서 사용 가능한 모델 목록을 출력한다.
--api-key <키> — API 키를 직접 지정한다.
세션 옵션
-c, --continue — 가장 최근 세션을 이어서 시작한다.
-r, --resume — 저장된 세션 목록에서 선택해 재개한다.
--session <경로|ID> — 특정 세션 파일이나 ID로 직접 진입한다.
--fork <경로|ID> — 기존 세션을 새 파일로 복제해 독립적으로 계속한다.
--no-session — 세션을 저장하지 않는 임시 모드로 실행한다.
--session-dir <디렉토리> — 세션 저장 위치를 커스텀 디렉토리로 변경한다.
도구 옵션
--tools <목록>, -t <목록> — 허용할 도구를 명시적으로 지정한다. 읽기 전용 검토 모드를 만들 때 유용하다. 내장 도구: read, bash, edit, write, grep, find, ls.
--no-builtin-tools, -nbt — 내장 도구를 모두 비활성화한다. 익스텐션 도구만 쓰고 싶을 때 쓴다.
--no-tools, -nt — 모든 도구를 비활성화한다.
리소스 옵션
-e, --extension <소스> — 익스텐션을 단발성으로 로드한다. 전역 설치 없이 특정 세션에서만 쓸 때 유용하다.
--skill <경로> — 스킬 파일을 직접 지정해 로드한다.
--system-prompt <텍스트> — 기본 시스템 프롬프트를 대체한다.
--append-system-prompt <텍스트> — 기존 시스템 프롬프트에 내용을 추가한다.
--no-extensions — 익스텐션 검색을 비활성화한다.
--no-context-files, -nc — AGENTS.md 등 컨텍스트 파일 로드를 비활성화한다.
기타 옵션
--mode json — JSON 라인 형식으로 이벤트 스트림을 출력한다. 스크립트나 파이프라인에서 Pi를 호출할 때 쓴다.
--mode rpc — stdin/stdout 위의 JSON 프로토콜로 실행한다. Node에 종속되지 않아 어떤 언어에서도 Pi를 제어할 수 있다.
--verbose — 시작 시 상세한 디버그 정보를 출력한다.
슬래시 명령어
TUI 안에서 /로 시작하는 내장 명령어들이다.
/model — 현재 세션의 모델을 변경한다. Ctrl+L 단축키와 동일하다.
/scoped-models — Ctrl+P 순환에 포함할 모델을 활성화하거나 제외한다.
/settings — 사고 수준, 테마, 메시지 전송 방식 등 세션 설정을 조정한다.
/new — 새 세션을 시작한다.
/resume — 저장된 이전 세션 목록에서 선택해 재개한다.
/name <이름> — 현재 세션에 이름을 붙인다. 여러 세션을 관리할 때 구분하기 편하다.
/session — 현재 세션 정보(ID, 경로, 메시지 수 등)를 표시한다.
/tree — 세션 내 분기 구조를 보여준다. 원하는 지점을 선택해 그 시점부터 다시 시작할 수 있다.
/fork — 특정 이전 메시지에서 새 세션을 분기한다. 방향을 바꿔보고 싶을 때 원본을 건드리지 않고 실험할 수 있다.
/clone — 현재 분기를 통째로 새 세션으로 복제한다.
/compact [프롬프트] — 컨텍스트를 수동으로 압축한다. 프롬프트를 함께 넘기면 압축 방향을 지정할 수 있다.
/copy — 마지막 응답을 클립보드에 복사한다.
/export [파일] — 세션 전체를 HTML 파일로 내보낸다. 파일명을 지정하지 않으면 자동 생성된다.
/share — 세션을 GitHub Gist에 업로드하고 URL을 생성한다.
/reload — 설정 파일과 리소스를 다시 로드한다. 익스텐션 코드를 수정하고 바로 반영할 때 쓴다.
/hotkeys — 현재 활성화된 모든 키보드 단축키 목록을 표시한다.
/changelog — Pi 버전 히스토리를 표시한다.
/login / /logout — Pi 구독 자격증명을 관리한다.
/quit — Pi를 종료한다.
키보드 단축키
@ 입력 — 파일 참조를 시작한다. 퍼지 검색으로 파일이나 폴더를 찾아 대화에 첨부할 수 있다.
Tab — 경로를 자동완성한다.
Shift+Enter — 여러 줄 입력을 위해 줄 바꿈한다. Windows Terminal에서는 Ctrl+Enter.
Ctrl+V / Alt+V (Windows) — 이미지를 클립보드에서 붙여넣는다. 드래그 앤 드롭도 된다.
!command — 셸 명령을 Pi 안에서 직접 실행한다. 결과가 TUI에 바로 표시된다.
!!command — 셸 명령을 숨겨서 실행한다. 출력이 TUI에 표시되지 않는다.
Ctrl+G — 외부 편집기를 열어 입력 내용을 편집한다. VISUAL 또는 EDITOR 환경 변수에 설정된 편집기가 열린다.
Ctrl+L — 모델 선택 화면을 연다. /model과 동일.
Ctrl+P — --models나 /scoped-models로 지정한 모델을 순환한다.
Enter (에이전트 실행 중) — 현재 도구 실행이 끝난 직후 전달되는 조종 메시지를 전송한다. 방향을 틀거나 추가 지시를 줄 때 쓴다.
Alt+Enter (에이전트 실행 중) — 모든 작업이 완료된 후 실행되는 팔로우업 메시지를 전송한다.
Escape (에이전트 실행 중) — 실행을 중단하고 큐에 있던 메시지를 복구한다.
Alt+Up — 큐에 등록해둔 메시지를 편집기로 되돌린다.
모델 설정 — models.json
~/.pi/agent/models.json에 AI 제공자와 모델 정보를 정의한다. LM Studio처럼 로컬 OpenAI 호환 API를 쓰는 경우 다음과 같이 설정한다.
{
"providers": {
"lmstudio": {
"baseUrl": "http://localhost:1234/v1",
"api": "openai-completions",
"apiKey": "local",
"compat": {
"supportsDeveloperRole": false,
"supportsReasoningEffort": false,
"supportsUsageInStreaming": false
},
"models": [
{
"id": "lmstudio-community/gemma-4-26b-a4b-it-mlx",
"name": "Gemma 4 26B A4B (MLX)",
"input": ["text", "image"],
"contextWindow": 131072,
"maxTokens": 8192
}
]
}
}
}
compat 블록은 로컬 모델이 지원하지 않는 기능을 끄는 설정이다. developer 롤, reasoning effort, 스트리밍 중 사용량 집계를 지원하지 않는 모델에서는 이 세 항목을 false로 설정해야 오류가 생기지 않는다. settings.json의 defaultProvider와 defaultModel에 제공자 이름과 모델 ID를 지정해두면 Pi 시작 시 자동으로 적용된다.
컨텍스트 파일
Pi는 시작할 때 여러 위치에서 컨텍스트 파일을 자동으로 읽어 시스템 프롬프트에 포함한다.
~/.pi/agent/AGENTS.md (또는 CLAUDE.md) — 전역 지침이다. 개인 코딩 스타일, 언어 선호, 자주 쓰는 패턴 등을 여기에 쓴다. 모든 프로젝트에 공통으로 적용된다.
프로젝트 디렉토리의 AGENTS.md — 프로젝트별 지침이다. 현재 디렉토리와 상위 디렉토리를 탐색하며 찾는다. 빌드 명령어, 코드 컨벤션, 주의사항을 적어두면 Pi가 매번 물어보지 않아도 알아서 참조한다.
SYSTEM.md — 기본 시스템 프롬프트를 완전히 대체한다. 프로젝트 수준(.pi/SYSTEM.md)과 전역 수준(~/.pi/agent/SYSTEM.md) 모두 지원한다.
APPEND_SYSTEM.md — 기존 시스템 프롬프트에 내용을 추가한다. 대체하지 않고 붙이기만 할 때 쓴다.
이미지 출처: Unsplash
패키지 시스템
패키지는 npm이나 Git 레포지토리에서 설치한다. pi.dev/packages에서 2,700개 이상의 커뮤니티 패키지를 검색할 수 있다.
pi install npm:<패키지명> # npm에서 설치
pi install git:github.com/user/repo # Git 레포에서 설치
pi install npm:<패키지명> -l # 현재 프로젝트에만 로컬 설치
pi remove npm:<패키지명> # 제거
pi update # 모든 패키지 업데이트
pi update --self # Pi 자체만 업데이트
pi list # 설치된 패키지 목록
pi config # 패키지 리소스 활성/비활성화
패키지는 네 종류로 나뉜다. 익스텐션(CLI 도구·명령어·단축키 추가), 스킬(README 기반 온디맨드 기능), 프롬프트 템플릿(재사용 가능한 Markdown 프롬프트), 테마(UI 커스터마이징)다.
익스텐션
pi-web-access — 웹 검색, URL 가져오기, GitHub 레포 클론을 Pi 안에서 바로 할 수 있게 해준다. 외부 정보를 참조해야 하는 작업에서 가장 먼저 설치하게 되는 익스텐션이다.
pi-hermes-memory — 세션 간 지속적인 메모리를 제공한다. 세션 검색과 비밀(secret) 스캔 기능도 포함한다. Pi는 기본적으로 세션 간 컨텍스트를 유지하지 않는데, 이 익스텐션이 그 공백을 채운다.
pi-btw — /btw 슬래시 명령어로 병렬 측면 대화를 시작한다. 현재 작업 흐름을 멈추지 않고 “그런데 이 부분은 어떻게 생각해?”처럼 빠르게 확인하고 돌아오는 데 쓴다.
pi-subagents — 서브에이전트에게 작업을 위임하는 기능을 추가한다. 체인 실행과 병렬 실행을 모두 지원한다. Pi 기본에 없는 서브에이전트 기능을 가장 직접적으로 추가하는 방법이다.
context-mode — 컨텍스트 창을 최대 98%까지 절약하는 MCP 플러그인이다. 월간 다운로드 86,000건으로 Pi 패키지 중 가장 인기 있다. 샌드박스 코드 실행과 지식 베이스 기능도 포함한다.
pi-simplify — 최근 변경된 코드를 자동으로 리뷰한다. 작업 후 빠른 품질 점검에 쓴다.
pi-lens — LSP와 린터를 통해 실시간 코드 피드백을 제공한다. 에이전트가 코드를 작성하는 동안 타입 오류나 린트 오류를 즉시 감지한다.
pi-powerline-footer — Powerline 스타일의 상태 표시줄을 하단에 추가한다. 현재 모델, 컨텍스트 사용량, Git 브랜치 등을 시각적으로 확인할 수 있다.
@gotgenes/pi-permission-system — 파일 접근과 명령 실행에 대한 권한 체계를 추가한다. Pi 기본에는 권한 팝업이 없는데, 이 익스텐션이 그 역할을 한다. 중요한 작업에서 에이전트의 행동 범위를 제한하고 싶을 때 쓴다.
스킬
스킬은 익스텐션과 달리 상시 실행되지 않는다. README 기반으로 작성되며, 필요할 때 /스킬명으로 호출하면 그 시점에 컨텍스트로 로드된다.
@ifi/pi-plan — 계획 수립 스킬이다. 복잡한 작업을 시작하기 전에 단계별 계획을 잡는 워크플로우를 제공한다.
@catdaemon/pi-code-intelligence — 코드 인텔리전스 스킬이다. 코드베이스 분석, 패턴 인식, 심층 리뷰 등 코드 이해 관련 기능을 제공한다.
그 외 눈에 띄는 스킬로는 pi-hermes-memory(메모리 관련 스킬 포함), @juicesharp/rpiv-pi(연구→설계→계획→구현→검증 5단계 개발 워크플로우) 등이 있다.
프롬프트 템플릿
Markdown 파일로 만든 재사용 가능한 프롬프트다. .pi/prompts/ 디렉토리에 넣어두면 /파일명으로 바로 호출한다. 자주 반복하는 작업 지시를 템플릿으로 만들어두면 매번 길게 타이핑하지 않아도 된다.
pi-schedule-prompt — Cron 형식으로 프롬프트를 반복 실행하는 패키지다. 정기적인 자동화 작업이 필요할 때 유용하다.
환경 변수
PI_CODING_AGENT_DIR — Pi 설정 디렉토리를 변경한다. 기본값은 ~/.pi/agent.
PI_CODING_AGENT_SESSION_DIR — 세션 저장 위치를 별도로 지정한다.
PI_OFFLINE — 오프라인 모드로 실행한다. 인터넷 없이 로컬 모델만 쓸 때 쓴다.
PI_SKIP_VERSION_CHECK — 버전 확인을 건너뛴다.
PI_TELEMETRY — 원격 분석 수집을 제어한다. 0으로 비활성화.
PI_CACHE_RETENTION — 캐시 유지 정책을 설정한다.
VISUAL / EDITOR — Ctrl+G로 열리는 외부 편집기를 지정한다.
Pi가 일부러 넣지 않은 것들
Pi 문서에는 “What we didn’t build”라는 섹션이 따로 있다. MCP, 서브에이전트, 권한 팝업, 계획 모드, 내장 TODO, 백그라운드 Bash가 기본에서 빠져 있다. 각각 스킬이나 익스텐션으로 추가하거나, tmux처럼 외부 도구를 조합해 구현하는 것이 Pi의 방식이다.
결과적으로 Pi는 쓸수록 자신의 에이전트가 된다. 처음엔 텅 빈 것처럼 느껴지지만, 패키지를 하나씩 더하고 AGENTS.md를 채워나가다 보면 자신의 워크플로우에 정확히 맞는 도구가 만들어진다. 비용도 자신이 선택한 모델과 제공자에 따라 결정된다. 로컬 모델로 구독료 없이 돌리는 것도, 프로덕션 수준의 클라우드 모델을 붙이는 것도 모두 가능하다. 에이전트 시장의 표준이 어디로 수렴하든, Pi는 그 흐름에 맞게 패키지 하나를 더 설치하면 된다.
출처