코딩 에이전트 Pi 1.0, 내 모델로 시작하는 설치·설정 가이드

코딩 에이전트 Pi로 작업 환경을 직접 구성합니다

Pi는 모델을 파일과 명령어에 연결하는 가벼운 에이전트 하네스입니다. 작업대라고 생각하면 이해하기 쉽습니다. 선택한 모델이 할 일을 판단하고, Pi는 그 일을 수행할 도구를 제공합니다.

기본으로 활성화되는 내장 툴 네 가지가 핵심 작업 흐름을 담당합니다.

모델이 툴 실행을 요청하면 Pi가 실행하고, 결과를 다시 대화에 전달합니다. 작업이 끝날 때까지 이 과정이 반복될 수 있습니다. 여기서 소개한 네 가지는 기본으로 활성화되는 툴이며, 1.0에서 제공하는 모든 내장 툴을 나열한 것은 아닙니다. Pi 툴 문서, 에이전트 실행 흐름.

이미 Claude Code나 Codex를 사용한다면, 직접 구성하고 싶은 작업 흐름을 기준으로 Pi를 평가하는 편이 좋습니다. 저장소 리뷰 명령이나 반복해서 쓸 마이그레이션 스킬처럼 구체적으로 바꾸고 싶은 부분이 있을 때 사용해 보기를 권합니다. 다른 후보도 함께 살펴보려면 모델에 종속되지 않는 코딩 에이전트를 참고합니다.

Pi 1.0에서 달라진 터미널 화면과 툴 실행 방식

1.0.0 릴리스에서는 전체 화면이 기본값이 되었고, codemode와 로그인 방식도 개선되었습니다. TUI는 터미널 안에 표시되는 사용자 인터페이스입니다. 초기 설정에서 알아둘 변화는 다음과 같습니다.

MCP는 에이전트를 외부 툴에 연결합니다. OAuth는 툴에 비밀번호를 넘기지 않고 접근 권한을 부여하는 로그인 방식입니다. codemode에서는 모델이 JavaScript로 툴 호출을 구성하고, 선택한 결과를 대화에 반환할 수 있습니다. 프롬프트 감소는 이 구성에 적용되는 것으로, 모든 작업의 요금이 40% 줄어든다는 뜻은 아닙니다. Pi 1.0.0 릴리스 노트, codemode 문서.

같은 릴리스에서 codemode 스크립트를 통한 이미지 생성, /login의 Radius 항목, quietStartup: "header"도 추가되었습니다. 첫 코딩 작업에서는 이 기능들을 사용하지 않아도 됩니다. 릴리스 노트.

28분 안에 Pi 설치부터 첫 작업까지 진행하기

익숙한 저장소, 정상적으로 실행되는 테스트 명령, 지원되는 모델의 접속 수단을 준비합니다. 아래 시간은 권장 배분일 뿐입니다. 다운로드, 로그인, 테스트에 걸리는 시간은 환경마다 다릅니다. 세션이 끝나기 전에 직접 검토할 수 있을 만큼 작은 작업을 고릅니다.

0~5분: 설치하고 프로젝트 열기

프로젝트의 npm 설치 방식에는 Node.js 22.19 이상이 필요합니다. 다음 명령은 Pi 버전을 1.0.0으로 고정하므로, 이 글에서 다루는 릴리스와 동일한 환경으로 따라갈 수 있습니다.

node --version
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.0.0
pi --version
cd /path/to/project
pi --tui-mode regular

/path/to/project를 작업 폴더 경로로 바꿉니다. pi --version의 출력은 1.0.0이어야 합니다. pi만 실행하면 새 기본값인 전체 화면 모드로 시작합니다. macOS/Linux에서 사용할 수 있는 공식 대안은 curl -fsSL https://pi.dev/install.sh | sh이며, 현재 릴리스를 설치합니다. 프로젝트 설치 문서, 빠른 시작 가이드.

5~10분: 기존 계정 연결하기

Pi 안에서 /login을 실행하고 제공업체를 선택한 뒤, 안내되는 인증 절차를 완료합니다. 이어서 /model을 실행해 사용할 수 있는 모델을 고릅니다. 제공업체는 모델에 접근하는 경로이며, 모델은 응답을 생성하는 시스템입니다.

Pi의 인증 문서에는 Anthropic 구독 계정과 OpenAI Sign in with ChatGPT 연결 방식이 명시되어 있습니다. OpenAI는 계정 자격을 충족할 경우 이용 조건에 맞는 요청에 요금제 사용량을 적용할 수 있다고 설명합니다. API 키를 선택하면 별도의 과금 경로를 사용하게 됩니다. Pi OAuth 제공업체 문서, OpenAI 로그인 문서.

Pi 웹사이트는 Anthropic, OpenAI, Google, OpenRouter, Ollama 등을 지원 대상으로 소개합니다. 제공업체를 지원한다고 해서 모든 계정에 모든 모델이 표시되는 것은 아닙니다. 원하는 모델이 보이지 않으면 인증부터 확인합니다. /model에는 사용할 수 있는 인증 정보가 있는 모델이 표시됩니다. 선택 화면에서 Ctrl+S를 누르면 기본 모델을 저장할 수 있습니다. 모델 선택 문서.

Ollama를 사용하려면 프로젝트의 호환 엔드포인트 설정 예시에 따라 ~/.pi/agent/models.json을 구성합니다. 이 예시는 http://localhost:11434/v1, API 유형 openai-completions, 더미 키 ollama, 그리고 설치된 Ollama에서 제공하는 모델 ID를 사용합니다. /model을 열면 이 파일을 다시 읽습니다. 유료 모델 계정 없이 Pi를 사용해 보고 싶다면 이 로컬 연결 방식을 선택할 수 있습니다.

10~13분: 저장소 작업 지침 작성하기

저장소 루트에 짧은 AGENTS.md를 추가하거나, 이미 관리 중인 파일을 보완합니다. Pi는 ~/.pi/agent/, 상위 디렉터리, 현재 디렉터리에서 지침을 찾아 읽습니다. 세션 도중 지침을 바꾸었다면 /reload를 실행합니다. 설정 문서.

실제 저장소에 맞는 지침을 작성합니다. 예시는 다음과 같습니다.

Use the existing test runner and neighboring test conventions.
Keep this task within the function and tests I name.
Do not add dependencies or change the public API.
Run the focused tests and report the exact command and result.
Leave commits and publishing to me.

해당 부분만 테스트하는 실제 명령을 알고 있다면 함께 적습니다. AGENTS.md는 모델에 작업 방향을 알려주는 지침이며, 권한 경계를 강제로 적용하지는 않습니다.

13~23분: 실용적인 변경 하나 만들기

빈 입력에 대한 동작이 정의되어 있지만 회귀 테스트는 없는 기존 헬퍼를 고릅니다. Pi의 파일 선택기 @를 사용해 해당 헬퍼와 인접한 테스트를 첨부한 뒤, 다음 작업을 요청합니다.

회귀 테스트는 기대한 동작이 이후 변경으로 깨지는 것을 방지합니다. 이 작업은 Pi에게 애플리케이션을 다시 설계하도록 맡기지 않고도 구체적인 변경 내역을 얻을 수 있습니다. 빠른 시작 가이드에는 @를 이용한 파일 선택과 작업 후 변경 파일 검토 방법이 나와 있습니다. 첫 작업 가이드.

23~28분: 변경 내역과 테스트 결과 검토하기

변경한 테스트를 읽고 파일 변경 내역인 git diff를 확인합니다. 검증 구문이 기대한 동작을 확인하는지 살핀 뒤, 해당 부분의 테스트 명령을 직접 실행합니다. 테스트 통과는 변경을 뒷받침하는 근거입니다. 다만 검증 구문이 유용한지, 변경 범위가 적절한지는 직접 판단해야 합니다.

첫 실행의 완료 기준은 간단합니다. 선택한 제공업체에 연결되었고, Pi가 의도한 변경을 수행했으며, 그 변경 내역을 설명할 수 있으면 됩니다. 작업 환경을 더 세밀하게 구성하는 일은 다음 세션으로 넘깁니다.

Pi 자체는 무료이며, 실제 비용은 모델 사용량에 따라 달라집니다

Pi는 MIT 라이선스를 사용하며, 사용자별 소프트웨어 이용료를 추가로 부과하지 않습니다. 구독 계정으로 연결하면 해당 요금제에서 제공하는 사용량을 소비하고, API 키를 사용하면 제공업체의 사용량 요금이 발생합니다. 로컬 모델을 쓰는 경우에는 하드웨어와 운영에 비용이 듭니다.

API 요금 계산 예시로, OpenAI의 GPT-6.1 Sol 표준 단문맥 요금은 입력 토큰 100만 개당 $2, 출력 토큰 100만 개당 $10입니다. 토큰은 요금 계산에 사용되는 콘텐츠의 단위입니다. OpenAI 공식 요금.

작은 작업 하나를 수행하면서 여러 요청에 걸쳐 다음 사용량이 누적되었다고 가정합니다.

이는 실제 작업에서 측정한 사용량이 아니라 계산 방법을 보여주는 예시입니다. 표준 처리 방식, 요청당 입력 토큰 272,000개 이하, 캐시 쓰기나 별도 요금이 부과되는 툴 사용이 없는 조건을 가정합니다. 캐시된 입력, 캐시 쓰기, 더 긴 요청, 다른 처리 등급에는 별도 요율이 적용됩니다. 사용량이 정확히 이 가정과 같은 작업을 백 번 수행하면 기본 모델 요금은 $30입니다. GPT-6.1 Sol 상세 요금.

예산을 판단할 때는 원하는 작업 환경을 구성하고 유지하는 데 드는 노력이 그만한 가치가 있는지 따져야 합니다. Pi에는 하네스 라이선스 비용이 없지만, 모델 사용료와 사람의 검토, 작업 흐름을 지원하기 위한 개발 시간은 여전히 필요합니다.

작업 흐름 확장에는 목적에 맞는 최소한의 수단을 선택합니다

작업 규칙은 지침에, 반복 절차는 스킬에, 실행 가능한 동작은 확장 기능에 담습니다.

스킬의 SKILL.md는 이름과 설명으로 시작합니다. 특정 스킬을 명시적으로 불러오려면 /skill:name으로 호출합니다. 확장 기능은 Pi 프로세스 안에서 실행되므로 불러오기 전에 코드를 검토합니다. 스킬 문서, 확장 기능 문서.

pi install ./local-package는 로컬에서 준비한 패키지를 설치합니다. 이미 배포된 패키지는 실제 이름과 버전을 넣어 pi install npm:@scope/package@version으로 설치합니다. --local을 추가하면 .pi/settings.json에 프로젝트 수준의 패키지 선언을 기록합니다. 세션 도중 리소스를 바꾼 뒤에는 /reload를 실행합니다. 패키지 문서.

외부 MCP 서비스를 사용하려면 서버를 설정하고, OAuth가 필요한 경우 /mcp login <server>로 로그인합니다. 먼저 기본 설정으로 정상 작동하는 것을 확인한 다음 추가하는 편이 좋습니다. MCP 문서.

실무 효과를 기준으로 고른 여섯 가지 활용법

가장 좋은 출발점은 잘 아는 저장소에서 반복적으로 발생하는 작업입니다. 아래는 활용 방안이며, 실제 효과는 코드베이스와 검토 방식에 따라 달라집니다.

1. 보고된 버그를 회귀 테스트로 남기기. 구독형 웹 앱을 직접 유지하는 창업자라면 버그 재현 방법, 구현 코드, 테스트를 첨부하고 Pi에 실패하는 테스트와 필요한 부분만 수정하는 작업을 요청한 뒤 관련 검사를 다시 실행할 수 있습니다. 확인한 실패 사례를 지속적으로 검증하는 테스트로 남긴다는 데 가치가 있습니다.
2. 풀 리퀘스트를 열기 전에 변경 사항 검토하기. 개발자는 로컬 변경 내역과 저장소 리뷰 스킬을 Pi에 제공하고, 파일 위치와 설명을 포함해 잠재적인 결함을 찾아달라고 요청할 수 있습니다. 리뷰 전에 구체적인 문제를 찾으면 의견을 주고받는 횟수를 줄일 수 있습니다.
3. 애플리케이션의 한정된 부분을 마이그레이션하기. 유지보수 담당자는 마이그레이션 절차를 스킬로 정리하고 한 모듈에 적용한 뒤 관련 검사를 실행할 수 있습니다. 각 변경을 검토하면서 유사한 모듈에 같은 절차를 재사용하면 작업 시간을 줄일 여지가 있습니다.
4. 낯선 저장소의 구조 파악하기. 새로 합류한 엔지니어는 Pi에 요청 하나가 진입점부터 데이터 저장까지 어떻게 처리되는지 추적하도록 요청하고, 파일 위치와 관련 검사 명령을 포함한 메모를 남길 수 있습니다. 이런 메모는 반복되는 초기 설정 질문을 줄이는 데 도움이 될 수 있습니다.
5. 작은 유지보수 스크립트 작성하기. 오래된 테스트 픽스처를 관리하는 담당자는 Pi에 스크립트 초안을 작성하게 하고, 샘플 입력으로 실행한 뒤 사용법을 문서화할 수 있습니다. 검토를 마친 스크립트로 반복적인 수작업 수정을 대신할 수 있습니다.
6. 내부 개발 작업 흐름 구축하기. 기술 리드는 사용자 정의 명령어와 스킬을 패키지로 묶을 수 있습니다. 일회성 명령에는 출력 모드, 별도 프로세스 제어에는 RPC, 애플리케이션 안에 세션을 넣는 데는 SDK 라이브러리를 사용해 Pi를 통합할 수도 있습니다. 반복되는 업무에 맞게 에이전트를 구성하는 것이 목적이며, 통합과 지원은 기술 리드가 책임집니다. 통합 인터페이스 문서.

가장 유망한 개발 아이템은 저장소에 특화된 AI 코드 리뷰입니다

머지 전 리뷰 패키지가 가장 분명한 기회입니다. 반복해서 필요한 업무이고, 구매 대상인 팀도 리뷰 지연에 드는 비용을 이미 알고 있기 때문입니다. 소규모 개발팀은 자체 규칙을 확인하고 리뷰어에게 판단 근거를 제공하는 패키지의 유지보수에 비용을 지불할 수 있습니다.

수요 조사에서 “ai code review”의 미국 Google 월간 검색량은 추정 1,300회로 나타났습니다. 가격을 비교할 기준으로는 CodeRabbit Essentials가 있습니다. 연간 결제 시 개발자당 월 $24, 월간 결제 시 $30입니다. 이 수치는 해당 업무에 대한 관심과 유료 제품군이 존재한다는 점을 보여주지만, Pi 패키지 자체의 수요를 입증하지는 않습니다. 검색량은 DataForSEO 키워드 개요로 2026년 10월 3일 확인했습니다. CodeRabbit 요금.

판매 가능한 최소 구성에는 리뷰 스킬, 로컬 변경 내역을 수집하는 명령어, 저장소별 검사, 파일 위치를 담은 보고서가 들어갈 수 있습니다. 초기에는 로컬 실행 방식으로 제공합니다. 관건은 차별화입니다. 범용 프롬프트는 쉽게 복제할 수 있고, Pi 패키지에는 별도의 유지보수와 접근 제어, 지원이 필요합니다. 저장소 검사 품질과 그 품질을 유지하는 서비스를 판매해야 합니다.

두 번째 기회는 팀용 초기 설정 패키지입니다. 개발 리드는 일관된 제공업체 설정, AGENTS.md, 공유 스킬, 승인된 소수의 확장 기능을 도입하고 유지하는 서비스를 구매할 수 있습니다. 같은 날짜의 DataForSEO 조사에서 “open source ai coding assistant”의 미국 월간 검색량은 추정 1,600회였습니다. 첫 버전은 한 팀의 저장소를 위한 패키지 하나와 온보딩 절차로 구성할 수 있습니다. 다만 검색 관심도가 설치 대행에 돈을 낼 의향까지 입증하지는 않습니다. 지속적인 가치는 팀의 작업 흐름을 유지하는 데서 나와야 합니다.

기본 동작을 직접 관리할 사람이 없다면 Pi는 맞지 않습니다

팀이 권한 승인 절차, 격리, 표준 작업 흐름을 제품의 기본 기능과 지원 범위로 기대한다면 관리형 툴을 선택하는 편이 좋습니다. Pi의 툴은 Pi를 시작한 프로세스의 권한으로 실행됩니다. 프로젝트 신뢰 설정은 어떤 프로젝트 리소스를 불러올지 제어하지만, 툴 호출을 샌드박스로 격리하지는 않습니다. 작업 폴더를 지정해도 명령어가 접근 가능한 다른 경로까지 닿는 것을 막지는 못합니다. Pi 보안 모델.

확장 기능으로 확인 절차나 경로 보호를 추가할 수 있고, 컨테이너로 운영체제 수준의 경계를 만들 수도 있습니다. 다만 이를 구현하고 유지하는 일은 팀의 몫입니다. codemode의 JavaScript 샌드박스 역시 호출되는 툴의 권한을 제한하지 않습니다. 확장 기능으로 가능한 작업, codemode 문서.

Pi의 핵심 구성에는 내장 서브 에이전트와 계획 모드도 포함되지 않습니다. 제 판단으로는 작은 기반을 직접 다듬고 싶은 개발자에게는 적절한 선택이지만, 그런 결정을 다른 쪽에서 책임져 주기를 원하는 팀에는 적합하지 않습니다. 프로젝트 설계 방향.

월요일에는 직접 관리하는 저장소에서 범위를 정한 버그 수정이나 테스트 작업 하나를 Pi에 맡겨 봅니다. 변경 내역과 테스트 결과를 보관한 뒤, 어떤 반복 절차를 스킬로 만들지 판단합니다. 팀에 맞는 작업 흐름을 구축하고 싶다면 AI 에이전트 개발에서 시작할 수 있습니다.