Pi Coding Agent 사용법 2026 – Claude Code를 진짜 지워도 될까 extension 활용 현실표

Posted on by

Pi Coding Agent는 공식 문서에서 미니멀 터미널 코딩 하네스로 소개되는 AI 코딩 도구다.

처음 보면 질문이 바로 생긴다.

이거 쓰면 Claude Code를 진짜 지워도 될까.

나도 이 질문이 제일 먼저 걸렸다.

영상 제목은 자극적이다.

“지난주에 Claude Code를 삭제했다”는 식의 메시지다.

그런데 내용을 보면 단순한 대체툴 홍보가 아니다.

핵심은 Claude 모델을 버린다는 말이 아니다.

Claude Code라는 하네스를 버릴 수 있느냐는 이야기다.

여기서 한 번 헷갈리면 글 전체가 꼬인다.

Claude는 모델이다.

Claude Code는 그 모델을 코딩 작업에 쓰게 해주는 제품이다.

Pi는 모델이 아니라 하네스다.

그러니까 Pi로 갈아탄다는 말은 “Claude를 안 쓴다”가 아니라 “Claude Code라는 포장지를 빼고 다른 실행 환경을 쓴다”에 가깝다.

이 차이를 모르면 갑자기 AI 도구판에서 이름표만 붙잡고 싸우게 된다.

이름표 싸움은 늘 시끄럽고 별로 남는 게 없다.

내가 확인한 범위

이 글은 “Pi로 실제 프로젝트를 7일 운영했다”는 후기가 아니다.

그렇게 쓰면 안 된다.

그건 아직 안 했으니까.

이번 글에서 확인한 범위는 네 가지다.

첫째, 원본 영상 자막을 확인했다.

둘째, Pi 공식 문서에서 설치, usage, extension, package 구조를 확인했다.

셋째, Claude Code 공식 문서에서 permissions, security, subagents 흐름을 확인했다.

넷째, 내 로컬 환경에서 npx -y @earendil-works/pi-coding-agent --version과 --help를 실행해 현재 npm 패키지와 CLI 옵션을 확인했다.

확인 결과 @earendil-works/pi-coding-agent는 0.74.0으로 실행됐고, help에는 --print, --continue, --resume, --tools, --extension, --no-context-files, --list-models 같은 옵션이 표시됐다.

즉 이 글은 “도입 전 현실 점검 + 첫 사용법 + 삭제 판단표”에 가깝다.

실전 운영 후기는 아니다.

이 선을 먼저 그어야 글이 덜 위험해진다.

AI 도구 글에서 제일 위험한 문장은 “써보니 좋더라”인데, 사실은 설치 화면만 본 경우다.

그건 후기라기보다 예고편 감상문이다.

먼저 답부터

내 판단은 이렇다.

개인 실험가나 워크플로우를 직접 깎는 사람이라면 Pi는 Claude Code를 부분적으로 대체할 수 있다.

하지만 팀 운영, 보안 경계, sub-agent, permission, MCP를 바로 안정적으로 써야 하는 사람이라면 아직 Claude Code를 지우면 안 된다.

적어도 메인 도구를 바로 바꾸는 건 이르다.

Pi는 “더 많은 기본 기능”으로 이기는 도구가 아니다.

오히려 기본 기능을 일부러 덜 넣고, extension과 package로 사용자가 직접 조립하게 만드는 쪽이다.

그래서 대체 가능성은 사람마다 갈린다.

사용자 유형 Claude Code 삭제 가능성 이유
혼자 쓰는 개발자 높음 필요한 기능을 extension으로 직접 붙일 수 있음
Obsidian 자동화 실험가 중간 이상 AGENTS.md, CLI, no-focus workflow와 잘 맞음
팀 개발자 중간 보안, 로그, 승인 흐름을 직접 설계해야 함
초보자 낮음 기본 기능 부족이 장점보다 불편함으로 먼저 옴
보안 민감 조직 낮음 extension과 package의 full system access 검토가 먼저임

정리하면 이렇다.

Claude Code를 “완성형 전동공구”처럼 쓰고 있다면 지우면 불편하다.

Claude Code를 “내 자동화 시스템의 임시 실행기”처럼 쓰고 있었다면 Pi를 검토할 만하다.

이 차이가 글의 중심이다.

읽기 전에 맞춰볼 것

이 글은 Pi를 처음 듣는 사람을 위한 글이지만, 완전 초보 입문서만은 아니다.

터미널에서 npm, npx, 환경변수, 프로젝트 루트, AGENTS.md 같은 단어를 본 적 있는 사람에게 더 잘 맞는다.

특히 아래에 해당하면 끝까지 읽어볼 만하다.

상황 이 글에서 얻을 것
Claude Code가 편하지만 답답한 사람 Pi가 어느 지점에서 더 자유로운지
AI 코딩툴 권한이 걱정되는 사람 extension과 path protection으로 나눌 수 있는 기준
Obsidian 자동화를 굴리는 사람 vault에 바로 붙이기 전 점검할 경계
여러 모델을 섞어 쓰고 싶은 사람 하네스와 모델을 분리해서 보는 법
하네스라는 개념이 헷갈리는 사람 CPU/RAM/OS 비유로 보는 기본 구조

반대로 이런 사람에게는 아직 추천하지 않는다.

상황 이유
터미널 도구가 낯선 사람 설치보다 운영 개념에서 먼저 막힐 수 있음
회사 보안 정책이 엄격한 사람 package와 extension 검토가 먼저임
오늘 안에 기능을 납품해야 하는 사람 새 도구 실험은 납품일에 하면 안 됨
Claude Code 기본 기능만으로 충분한 사람 굳이 조립 비용을 낼 이유가 적음

Pi는 “누구나 바로 갈아탈 도구”라기보다 “내 워크플로우가 분명한 사람이 조립해볼 도구”에 가깝다.

그래서 이 글도 사용법만 나열하지 않는다.

진짜 판단은 사용법 뒤에 온다.

Pi는 모델이 아니라 하네스다

Pi를 이해하려면 하네스라는 단어부터 잡아야 한다.

영상에서는 컴퓨터 비유를 쓴다.

모델은 CPU다.

컨텍스트 윈도우는 RAM이다.

하네스는 운영체제다.

Claude, GPT, Gemini, Kimi 같은 모델은 실제로 생각하고 문장을 만든다.

하지만 모델 혼자서는 프로젝트 파일을 읽고, bash를 실행하고, 테스트를 돌리고, 긴 대화를 정리하는 운영 흐름을 만들기 어렵다.

그 흐름을 감싸는 층이 하네스다.

Claude Code도 하네스다.

Cursor도 하네스다.

Codex도 하네스다.

OpenCode도 하네스다.

Pi도 하네스다.

같은 모델을 써도 하네스가 달라지면 결과가 달라지는 이유가 여기에 있다.

Claude Opus를 써도 도구 호출이 어색한 하네스에 넣으면 답답할 수 있다.

반대로 더 작은 모델을 잘 설계된 하네스에 넣으면 체감 성능이 좋아질 수 있다.

모델 스펙만 보고 AI 코딩툴을 고르면 빠지는 함정이 여기다.

진짜 실무에서는 모델보다 “어떤 파일을 언제 읽고, 어떤 명령을 허용하고, 언제 멈추고, 어떻게 로그를 남기느냐”가 더 중요할 때가 많다.

이건 프롬프트 문제가 아니다.

운영 문제다.

그래서 Pi는 흥미롭다.

Pi는 하네스를 제품으로 팔기보다 하네스를 바꿀 수 있는 작업대처럼 놓는다.

좀 위험하게 말하면, Pi는 AI 코딩툴이라기보다 AI 코딩툴을 만드는 도구에 가깝다.

이 말이 멋있게 들리면 조심해야 한다.

멋있다는 건 보통 일이 늘어난다는 뜻이다.

기존 하네스와 뭐가 다른가

여기서 중요한 구분이 하나 있다.

내가 기존에 말하던 하네스와 Pi가 말하는 하네스는 같은 단어를 쓰지만 층이 다르다.

이걸 안 나누면 “Pi 쓰면 기존 standard-harness도 지워도 되나” 같은 이상한 질문으로 흐른다.

답은 아니다.

Pi는 기존 프로젝트 하네스를 대체한다기보다, 그 하네스를 부르는 AI 실행 껍데기에 더 가깝다.

기존에 이 vault에서 쓰던 standard-harness나 personal-cfo/harness 같은 구조는 프로젝트 운영용 런타임이다.

관심사는 이런 것이다.

  • harness_ctl.sh status로 현재 상태를 확인한다.
  • harness_ctl.sh once로 한 번 실행 검증을 한다.
  • 실패하면 어디에 기록되는지 본다.
  • runtime_state.json, events.jsonl, tasks.json 같은 상태를 남긴다.
  • baseline/lab/state를 분리해서 실험 iteration을 관리한다.
  • Goal, CPS, SSOT, Output Contract 같은 문서를 채워야 다음 단계로 넘어간다.

한마디로 기존 하네스는 “작업이 죽지 않고 굴러가게 하는 운영 장치”다.

발전기, 점검표, 경보기 쪽이다.

반면 Pi는 “AI 모델을 터미널 코딩 작업에 연결하는 에이전트 하네스”다.

관심사는 이런 것이다.

  • 어떤 모델을 쓸지 고른다.
  • 모델이 어떤 tool을 호출할 수 있는지 정한다.
  • 긴 대화를 어떻게 compaction할지 정한다.
  • 세션을 트리로 저장하고 분기한다.
  • extension으로 permission gate, path protection, custom tool을 만든다.
  • AGENTS.md, CLAUDE.md 같은 context file을 읽어 작업 규칙을 모델에게 전달한다.

비유하면 이렇다.

구분 기존 project/runtime harness Pi Coding Agent
주 관심사 작업 안정성, 상태 저장, 반복 실행 모델 실행, 도구 호출, 세션, extension
대표 파일 runtime_harness.py, harness_ctl.sh, runtime_state.json ~/.pi/agent/, .pi/extensions, session JSONL
하는 일 프로젝트를 start/status/once/loop로 굴림 AI 모델이 파일 읽기, bash, edit, write를 하게 함
실패 대응 로그, state, gate, retry loop 세션 기록, tool result, extension hook
사용 위치 특정 프로젝트 내부 터미널 코딩 세션 전체
대체 관계 Pi가 대체하지 않음 Claude Code/Cursor/Codex 같은 코딩 하네스와 비교

그래서 더 정확히 말하면 Pi는 기존 하네스를 지우는 도구가 아니다.

Pi는 기존 하네스를 실행하거나 고치는 “AI 작업자용 조종석”에 가깝다.

예를 들어 Pi 안에서 이렇게 시킬 수 있다.

./harness/harness_ctl.sh status
./harness/harness_ctl.sh once
./harness/harness_ctl.sh state-status workspace/state/tasks.json

이 경우 기존 하네스는 여전히 프로젝트의 운영 엔진이다.

Pi는 그 엔진을 읽고, 실행하고, 고치고, extension으로 안전장치를 붙이는 코딩 에이전트 층이다.

둘을 합치면 이런 구조가 된다.

모델
  ↓
Pi / Claude Code / Codex 같은 코딩 하네스
  ↓
프로젝트별 runtime harness
  ↓
실제 작업: 블로그, 투자 브리핑, URL 요약, eval, 배포

이 관점이 중요하다.

Claude Code를 지우느냐는 “코딩 하네스” 선택 문제다.

기존 standard-harness를 지우느냐는 “프로젝트 운영 엔진” 문제다.

서로 다른 층이다.

Pi를 도입해도 기존 하네스 문서와 harness_ctl.sh는 계속 가치가 있다.

오히려 Pi가 잘 맞는다면 기존 하네스의 status/once/loop 명령을 더 자주, 더 안정적으로 호출하게 만드는 쪽이 자연스럽다.

내 기준으로는 이게 제일 현실적인 활용이다.

Pi로 기존 하네스를 없애는 게 아니라, Pi로 기존 하네스를 더 잘 굴리는 것.

이렇게 보면 갑자기 머리가 덜 꼬인다.

단어 하나 때문에 시스템이 두 개 싸우는 줄 알았는데, 사실은 2층 침대였던 셈이다.

Pi 설치와 첫 실행

공식 문서 기준으로 Pi는 macOS나 Linux에서 curl로 설치할 수 있다.

curl -fsSL <https://pi.dev/install.sh> | sh

npm을 선호한다면 공식 문서는 다음 명령도 안내한다.

npm install -g @earendil-works/pi-coding-agent

설치 후에는 프로젝트 폴더에서 pi를 실행한다.

cd my-project
pi

첫 실행에서 인증이 필요하다.

Pi 문서는 /login으로 subscription provider에 로그인하거나, ANTHROPIC_API_KEY 같은 환경변수로 API key를 설정할 수 있다고 설명한다.

예를 들면 이런 식이다.

export ANTHROPIC_API_KEY="sk-ant-..."
pi

여기서 중요한 점이 있다.

Pi를 쓴다고 Claude 모델을 못 쓰는 게 아니다.

오히려 Pi 안에서 Anthropic, OpenAI, Google, OpenRouter, Kimi 등 여러 provider와 모델을 바꿔 쓸 수 있다.

그러니까 “Claude Code를 지운다”는 말은 Claude 모델을 지운다는 뜻이 아니다.

Claude Code라는 앱 또는 CLI를 쓰지 않고, Pi라는 하네스에서 Claude 계열 모델을 계속 쓸 수도 있다.

이게 대체 논의의 핵심이다.

첫날에는 이렇게 쓰는 게 낫다

처음부터 메인 프로젝트에서 Pi를 돌리면 마음이 급해진다.

그러면 도구 평가가 아니라 생산성 도박이 된다.

첫날은 테스트 repo를 하나 만들어서 시작하는 편이 좋다.

mkdir pi-lab
cd pi-lab
git init
echo "# pi-lab" > README.md
pi

그다음에는 파일 읽기 중심으로만 써본다.

Pi usage 문서에는 read-only에 가까운 예시로 --tools read,grep,find,ls를 제한하는 방식이 나온다.

pi --tools read,grep,find,ls -p "이 코드베이스 구조를 리뷰해줘"

이 명령은 처음 실험에 좋다.

파일을 고치기 전에 Pi가 프로젝트를 어떻게 읽고 설명하는지 볼 수 있기 때문이다.

AI 코딩툴은 첫인상에서 코드 작성 능력보다 탐색 능력을 먼저 봐야 한다.

탐색을 못하는 에이전트는 수정도 대충 한다.

지도 못 읽는 기사에게 운전대를 맡기면 목적지가 아니라 모험이 시작된다.

Pi의 기본 사용법

Pi는 기본적으로 터미널 TUI에서 돌아간다.

공식 usage 문서에 따르면 인터페이스는 크게 시작 헤더, 메시지 영역, 에디터, footer로 나뉜다.

footer에는 작업 디렉터리, 세션명, 토큰과 비용, 컨텍스트 사용량, 현재 모델 같은 정보가 표시된다.

실전에서 자주 쓰는 흐름은 아래 정도다.

작업 사용법
일반 대화형 실행 pi
한 번만 묻고 종료 pi -p "질문"
파일을 포함해서 질문 pi @README.md "요약해줘"
이전 세션 계속 pi -c
과거 세션 선택 pi -r
세션 저장 없이 실행 pi --no-session
패키지 설치 pi install npm:패키지명
extension 테스트 pi -e ./my-extension.ts

파일 참조는 @로 한다.

예를 들어 특정 파일을 리뷰시키고 싶으면 이렇게 쓸 수 있다.

pi @src/app.ts @src/app.test.ts "이 변경에서 위험한 부분만 짚어줘"

shell 명령도 쓸 수 있다.

Pi usage 문서에 따르면 !command는 명령 결과를 모델에게 보내고, !!command는 모델에게 보내지 않고 실행한다.

이건 은근 중요하다.

모든 shell output을 모델에게 넣으면 컨텍스트와 비용이 늘어난다.

반대로 필요한 로그를 숨겨버리면 모델이 판단을 못 한다.

처음에는 !npm test처럼 짧고 의미 있는 명령만 넘기는 편이 낫다.

세션 트리가 실전에서 중요한 이유

Pi의 마음에 드는 지점 중 하나는 세션을 트리로 저장한다는 점이다.

공식 sessions 문서에 따르면 Pi 세션은 ~/.pi/agent/sessions/ 아래에 저장되고, 작업 디렉터리 기준으로 관리된다.

그리고 /tree로 이전 지점으로 돌아가 새 가지를 만들 수 있다.

이게 왜 중요하냐.

AI 코딩은 보통 한 번에 답이 안 나온다.

처음에는 A 방식으로 고쳐본다.

테스트가 깨진다.

다시 B 방식으로 간다.

그런데 일반 대화형 도구에서는 대화가 길어지면서 A의 실패 맥락과 B의 시도가 한 덩어리로 섞인다.

나중에는 모델도 사람도 “우리가 왜 이 길로 왔지” 상태가 된다.

Pi의 트리 세션은 이 문제를 줄인다.

이전 메시지에서 분기해서 다른 접근을 실험할 수 있다.

아이디어 실험이 많은 사람에게는 이게 꽤 큰 장점이다.

블로그 글 구조를 A안/B안으로 나눠보거나,

자동화 스크립트를 Python 버전과 shell 버전으로 갈라보거나,

라이브러리를 쓰는 접근과 직접 구현하는 접근을 따로 검증할 수 있다.

Claude Code도 강력하지만, Pi의 세션 트리 감각은 “실험 로그를 남기는 도구”에 더 가깝다.

Context file은 이렇게 붙인다

Pi는 AGENTS.md와 CLAUDE.md를 context file로 읽는다.

공식 usage 문서 기준으로 Pi는 글로벌 ~/.pi/agent/AGENTS.md, 부모 디렉터리, 현재 디렉터리의 context file을 읽을 수 있다.

이건 Obsidian이나 장기 프로젝트 운영자에게 중요하다.

이미 프로젝트 루트에 AGENTS.md를 잘 써두었다면 Pi가 그 규칙을 읽을 수 있다.

예를 들어 이런 내용을 둘 수 있다.

# AGENTS.md

- 파일 수정 전 git diff를 확인한다.
- `.env`, `secrets/`, `private/`는 읽지 않는다.
- 문서 작업은 direct write를 우선한다.
- Obsidian 앱은 명시 요청 없이는 열지 않는다.
- 테스트 없는 리팩터링은 작은 범위로만 한다.

이런 context file은 모델에게 말투를 알려주는 파일이 아니다.

작업 계약서에 가깝다.

Pi를 잘 쓰려면 prompt보다 context file을 먼저 정리하는 편이 좋다.

특히 팀에서는 AGENTS.md가 없으면 사람마다 Pi가 다르게 행동한다.

그 순간 “내 컴퓨터에서는 잘 됐는데요”의 AI 버전이 열린다.

별로 반갑지 않은 행사다.

Extension이 Pi의 진짜 활용법이다

Pi를 단순히 터미널 챗봇처럼 쓰면 매력이 반쯤만 보인다.

진짜 핵심은 extension이다.

공식 extensions 문서에 따르면 Pi extension은 TypeScript 모듈이다.

이 extension은 도구를 추가하고, 도구 호출을 가로채고, 사용자 확인 UI를 띄우고, custom command를 등록할 수 있다.

문서의 예시 영역에도 permission gate, git checkpoint, path protection, custom compaction, 외부 integration 같은 사례가 나온다.

이게 Claude Code와 Pi의 가장 큰 갈림길이다.

Claude Code는 제품이 정한 permission, hooks, subagent, MCP, plugin 흐름을 쓴다.

Pi는 그런 것을 core에 많이 넣지 않고 extension으로 만들게 한다.

그래서 Pi를 제대로 쓰려면 이런 질문을 해야 한다.

“이 도구에 기능이 있나?”

보다

“이 기능을 내 방식으로 붙일 수 있나?”

이 질문이 더 맞다.

예시 1: 위험 명령 확인 extension

처음 만들 extension은 화려하면 안 된다.

가장 먼저 만들 것은 위험 명령 확인이다.

예를 들어 rm -rf, sudo, git push --force 같은 명령을 실행하기 전에 확인창을 띄우는 식이다.

아래 코드는 개념 예시다.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName !== "bash") return;

    const command = String(event.input?.command ?? "");
    const dangerous =
      /\brm\s+-rf\b/.test(command) ||
      command.includes("git push --force") ||
      command.startsWith("sudo ");

    if (!dangerous) return;

    const ok = await ctx.ui.confirm(
      "위험 명령 확인",
      `이 명령을 실행할까?\n\n${command}`
    );

    if (!ok) {
      return {
        block: true,
        reason: "사용자가 위험 명령을 차단함",
      };
    }
  });
}

이 파일을 프로젝트 로컬 extension으로 둘 수 있다.

mkdir -p .pi/extensions
touch .pi/extensions/danger-guard.ts

그리고 Pi를 재시작하거나 /reload를 실행한다.

이 extension이 철벽 보안 장치는 아니다.

문자열 탐지라 우회 가능성이 있다.

하지만 첫 번째 실험으로는 좋다.

이걸 만들면서 Pi가 어떤 이벤트를 제공하고, tool call을 어디서 막을 수 있는지 감이 잡힌다.

Pi를 쓰는 목적은 처음부터 무결한 방화벽을 만드는 게 아니다.

내 워크플로우에서 반복되는 위험한 순간을 잡아내는 것이다.

예시 2: path protection으로 메인 vault 보호하기

Obsidian vault나 실서비스 repo에서 AI 에이전트를 쓸 때 가장 무서운 건 파일 수정이다.

특히 .env, secrets/, 인증 토큰, 개인 메모, 배포 설정은 실수로 읽거나 고치면 안 된다.

Claude Code는 settings에서 permissions.deny로 민감 파일 접근을 막는 흐름을 제공한다.

Pi는 이런 정책을 extension으로 만들거나, 외부 sandbox와 함께 운영해야 한다.

예를 들어 이런 기준을 둘 수 있다.

경로 기본 정책
.env 읽기/쓰기 차단
.env.* 읽기/쓰기 차단
secrets/** 읽기/쓰기 차단
private/** 읽기/쓰기 차단
00.Inbox/** 쓰기 허용, 이동은 확인
.claude/** 수정 전 확인
02.Areas/blog/** 초안 작성 허용

이 표는 단순한 문서가 아니다.

Pi에서는 extension으로 내릴 수 있는 운영 정책이다.

여기서 차이가 난다.

Claude Code는 기본 permission UX가 준비되어 있다.

Pi는 네가 원하는 permission UX를 직접 만든다.

개발자에게는 자유고,

초보자에게는 숙제다.

둘 다 맞다.

예시 3: Plan mode를 직접 흉내 내기

Pi는 공식 design principle에서 built-in plan mode를 넣지 않는다고 설명한다.

그러면 계획 없이 바로 수정하라는 뜻일까.

그건 아니다.

Plan mode를 파일 기반으로 만들면 된다.

예를 들어 프로젝트에 PLAN.md를 만들고, 모든 큰 작업 전에 Pi에게 이 파일부터 쓰게 할 수 있다.

# PLAN.md

## 목표

## 수정 범위

## 건드리지 않을 파일

## 검증 명령

## 롤백 기준

그리고 Pi에게 이렇게 지시한다.

먼저 PLAN.md만 작성해줘.
코드 수정은 하지 마.
수정 범위와 검증 명령을 확정한 뒤 다음 메시지에서 실행할게.

이 방식은 Claude Code의 plan mode처럼 제품 기능으로 잠겨 있지는 않다.

하지만 장점도 있다.

계획이 파일로 남는다.

다음 세션에서 다시 읽을 수 있다.

팀원이 리뷰할 수 있다.

나중에 블로그나 회고로 바꾸기도 쉽다.

우리 같은 Obsidian 기반 워크플로우에는 오히려 이쪽이 더 자연스러울 수 있다.

예시 4: MCP는 바로 붙이지 말고 CLI부터 본다

Pi는 기본 MCP를 핵심 기능으로 밀지 않는다.

공식 문서도 core를 작게 유지하고 workflow-specific behavior는 extension, skill, prompt template, package로 보내는 방향을 설명한다.

그럼 MCP를 못 쓰는 걸까.

그렇게 단순하지 않다.

영상에서도 MCP support를 extension으로 대체하거나 붙일 수 있다는 이야기가 나온다.

하지만 나는 처음부터 MCP를 붙이는 것보다 CLI 도구부터 붙이는 쪽을 추천한다.

이유는 단순하다.

CLI는 관찰하기 쉽다.

입력과 출력이 파일이나 stdout으로 남는다.

권한도 shell, path, env 기준으로 나누기 쉽다.

MCP는 편하지만, 서버가 어떤 도구를 노출하고 어떤 데이터를 가져가는지 더 세밀하게 봐야 한다.

특히 개인 vault에서는 MCP를 늘리는 것보다 “작은 CLI + README + AGENTS.md”가 더 안전할 때가 많다.

Pi의 철학도 이 방향과 꽤 맞다.

큰 플랫폼에 붙이기 전에 작은 원시 도구를 잘 만들자.

멋은 덜한데 사고는 덜 난다.

개발에서는 이 조합이 생각보다 자주 이긴다.

Claude Code와 Pi를 기능별로 비교하면

이제 진짜 질문으로 가보자.

Claude Code를 지워도 될까.

기능별로 보면 답이 조금 더 선명해진다.

항목 Claude Code Pi
설치 후 즉시 생산성 높음 중간
기본 permission UX 강함 직접 설계 필요
subagent 기본 제공 extension/package 또는 외부 방식
plan mode 기본 제공 파일/extension으로 구성
MCP 공식 흐름 제공 core 기본값은 아님, extension 가능
세션 트리 제품 흐름에 의존 핵심 강점
context file CLAUDE.md 중심 AGENTS.md/CLAUDE.md 지원
커스터마이즈 깊이 제한적 높음
초보자 친화성 높음 낮음
해킹 가능성 낮음 높음
운영 부담 낮음 높음

이 표에서 “해킹 가능성”은 보안 해킹이 아니라 도구를 자기 방식으로 뜯어고칠 수 있는 가능성이다.

Pi는 이 점이 강하다.

하지만 운영 부담도 같이 온다.

Claude Code는 좋은 기본값을 제공한다.

Pi는 기본값보다 조립 가능성을 준다.

이 둘은 우열이라기보다 제품 철학 차이다.

내가 Claude Code를 지우지 않는 경우

나는 아래 상황이면 Claude Code를 아직 지우지 않을 것이다.

첫째, 팀 저장소를 다룬다.

팀에서는 도구보다 규칙 일관성이 중요하다.

Claude Code는 permissions, settings, subagents, hooks, MCP 같은 흐름이 문서화되어 있고 팀 공유 설정도 잡기 쉽다.

둘째, 보안 승인 흐름이 중요하다.

Claude Code 보안 문서는 기본 read-only 권한, 추가 행동 시 승인, sandboxed bash, write access restriction 같은 보호 장치를 설명한다.

Pi도 extension으로 만들 수 있지만, 만들었다고 바로 검증된 건 아니다.

셋째, subagent를 많이 쓴다.

Claude Code의 subagent는 독립 context window, 도구 제한, 재사용 가능한 설정이 핵심이다.

Pi에서도 비슷한 구조를 만들 수 있지만, 그 자체가 프로젝트가 된다.

넷째, 지금 당장 납품해야 한다.

새 하네스를 평가하는 날에는 납품을 하면 안 된다.

새 운동화 신고 마라톤 뛰는 느낌이다.

가능은 한데 발이 먼저 항의한다.

내가 Pi로 갈아탈 수 있는 경우

반대로 아래 상황이면 Pi를 메인 후보로 올릴 수 있다.

첫째, 개인 자동화가 많다.

Obsidian 정리, 블로그 초안, URL 요약, 간단한 스크립트 수정처럼 반복 흐름이 많다면 Pi extension이 잘 맞을 수 있다.

둘째, 기존 도구의 기본 UX가 답답하다.

Claude Code가 정한 도구 흐름보다 내가 원하는 흐름이 더 분명하다면 Pi가 맞을 수 있다.

셋째, session branch가 중요하다.

여러 접근을 실험하고, 과정을 공유하고, 비용과 토큰을 확인하는 습관이 있다면 Pi의 세션 구조가 장점이다.

넷째, 작은 모델을 적극적으로 섞어 쓰고 싶다.

평소에는 저렴하고 빠른 모델을 쓰고, 어려운 작업에서만 Opus급 모델로 바꾸는 운영이 가능하다.

다섯째, 내 하네스를 직접 만들고 싶다.

이게 제일 중요하다.

Pi는 “나 대신 다 해줘”보다 “내가 쓰는 도구를 나답게 바꾸자”에 가깝다.

이 문장이 피곤하게 느껴지면 Claude Code가 낫다.

이 문장이 설레면 Pi를 볼 만하다.

내 기준의 7일 테스트 방법

Claude Code를 진짜 지울지 판단하려면 감으로 보면 안 된다.

7일만 테스트표를 만들어보면 된다.

테스트는 메인 프로젝트가 아니라 별도 repo에서 한다.

날짜 테스트 통과 기준
1일차 설치와 인증 pi, pi -p, pi -c가 문제 없이 동작
2일차 read-only 코드리뷰 파일 수정 없이 구조 설명 가능
3일차 작은 문서 수정 diff가 작고 의도를 설명함
4일차 위험 명령 guard rm -rf, git push --force 확인 또는 차단
5일차 PLAN.md 흐름 계획 작성과 실행을 분리
6일차 세션 트리 A/B 접근을 분기하고 돌아올 수 있음
7일차 실제 작업 1개 Claude Code 없이 끝까지 처리

점수는 이렇게 준다.

항목 점수
설치와 인증이 막히지 않음 1
read-only 분석이 만족스러움 1
파일 수정 diff가 작음 1
위험 명령 차단 흐름이 있음 1
context file을 제대로 읽음 1
세션 재개와 분기가 편함 1
Claude Code보다 덜 피곤함 2
비용/모델 전환 이점이 있음 1
메인 작업 1개를 끝냄 1

총 10점이다.

8점 이상이면 Claude Code 사용량을 줄여볼 만하다.

6점에서 7점이면 병행이 맞다.

5점 이하라면 아직 Claude Code를 지우면 안 된다.

특히 마지막 항목이 중요하다.

기능표에서 이긴 도구가 실제 하루 작업에서 지는 경우가 많다.

생산성 도구는 스펙이 아니라 피로도로 판단해야 한다.

Pi를 Obsidian 자동화에 붙일 때

내가 Pi를 진짜로 관심 있게 보는 이유는 Obsidian 자동화다.

이 vault에는 이미 AGENTS.md, .claude/skills, .claude/agents, no-focus 운영 규칙, URL 요약, 블로그 원장 handoff 같은 구조가 있다.

Pi는 이런 구조를 잘 읽고, 작은 extension으로 붙이기 좋다.

가능한 활용은 이런 식이다.

작업 Pi 활용
URL 요약 기존 script를 custom tool로 감싸기
블로그 초안 02.Areas/blog/TECHTAEK/만 쓰기 허용
Inbox 정리 00.Inbox/ 읽기, 이동 전 확인
LLM Wiki 반영 lint 명령을 extension command로 등록
위험 경로 보호 .env, private, secrets 차단
긴 작업 회고 session export와 Obsidian note 연결

다만 주의할 점이 있다.

Obsidian vault는 개인 지식과 자동화 코드가 섞여 있다.

그래서 Pi를 붙일 때는 기본값을 넓게 열면 안 된다.

처음에는 read-only로 시작한다.

그다음 쓰기 허용 경로를 좁힌다.

예를 들어 블로그 초안만 허용한다.

허용:
- 02.Areas/blog/TECHTAEK/**
- 00.Inbox/**

확인 필요:
- .claude/**
- 03.Resources/**

차단:
- .env
- secrets/**
- private/**
- credentials/**

이런 규칙을 AGENTS.md에 쓰는 것만으로는 부족할 수 있다.

실제로 막는 extension이나 sandbox가 있어야 한다.

말로만 금지된 냉장고 야식은 대체로 사라진다.

파일도 비슷하다.

실수 TOP 7

Pi를 처음 쓸 때 가장 쉬운 실수는 “Claude Code보다 기능이 없네”라고 바로 접는 것이다.

그건 Pi를 잘못 본 것이다.

Pi의 강점은 기능 목록이 아니라 조립성이다.

두 번째 실수는 반대로 “다 만들 수 있네” 하고 메인 프로젝트에 바로 넣는 것이다.

이것도 위험하다.

만들 수 있다는 말은 검증됐다는 말이 아니다.

세 번째 실수는 permission을 프롬프트로만 처리하는 것이다.

절대 .env 읽지 마라고 말하는 것보다 실제 차단 규칙이 필요하다.

네 번째 실수는 package를 무심코 설치하는 것이다.

Pi packages 문서는 extension이 arbitrary code를 실행할 수 있고, package가 full system access를 가질 수 있다고 경고한다.

서드파티 package는 편하지만, 출처와 코드를 봐야 한다.

다섯 번째 실수는 모든 모델을 같은 용도로 쓰는 것이다.

작은 모델은 빠른 탐색과 정리에 좋고, 큰 모델은 설계와 복잡한 디버깅에 좋다.

Pi의 장점은 모델 전환이다.

이걸 안 쓰면 반쯤만 쓰는 것이다.

여섯 번째 실수는 세션을 버리는 것이다.

Pi는 세션 트리가 강점인데, 매번 새로 시작하면 이 장점이 줄어든다.

실험할수록 /tree, pi -c, pi -r를 써야 한다.

일곱 번째 실수는 Claude Code와 싸움 붙이는 것이다.

둘은 당분간 같이 쓰는 게 맞다.

Claude Code는 안정적인 메인 도구,

Pi는 커스텀 하네스 실험장.

이렇게 나누면 판단이 편하다.

진짜 삭제 기준

그럼 언제 Claude Code를 지워도 될까.

내 기준은 꽤 엄격하다.

아래 다섯 가지가 통과되면 삭제를 고민한다.

기준 질문
반복 작업 내가 매주 하는 작업 3개를 Pi로 끝냈나
보안 민감 파일 차단이 실제로 동작하나
복구 잘못된 수정 후 git diff와 rollback이 쉬운가
비용 모델 전환으로 체감 비용이나 속도가 좋아졌나
피로도 Claude Code보다 덜 설명해도 원하는 결과가 나오나

여기서 하나라도 약하면 삭제보다 병행이 맞다.

특히 보안 기준은 타협하면 안 된다.

Pi는 extension으로 강해지는 도구다.

그 말은 extension이 약하면 운영도 약하다는 뜻이다.

Claude Code를 지우는 건 마지막 단계다.

처음 목표는 삭제가 아니다.

Claude Code가 맡던 작업 중 어떤 것을 Pi로 옮기면 더 좋은지 찾는 것이다.

도구 갈아타기는 이사와 비슷하다.

처음부터 집을 팔면 안 된다.

박스 하나씩 옮겨보고, 물 새는지 보고, 밤에 소음 있는지 보고 결정해야 한다.

내가 추천하는 병행 구조

당장 현실적인 구조는 이렇다.

Claude Code는 큰 작업과 팀 기준 작업에 둔다.

Pi는 개인 자동화와 실험 workflow에 둔다.

작업 추천 도구
팀 저장소 기능 개발 Claude Code
보안 정책 있는 코드리뷰 Claude Code
subagent 기반 큰 조사 Claude Code
개인 CLI 자동화 Pi
Obsidian 블로그 초안 Pi
context file 실험 Pi
커스텀 permission gate 실험 Pi
session branch 비교 Pi

이렇게 병행하면 도구 평가가 훨씬 정확해진다.

Claude Code를 억지로 이기게 할 필요도 없고,

Pi를 억지로 메인으로 올릴 필요도 없다.

각자 잘하는 일을 주면 된다.

AI 도구도 사람처럼 역할을 잘못 주면 갑자기 이상해진다.

능력 문제가 아니라 배치 문제인 경우가 많다.

FAQ

Pi를 쓰면 Claude 구독이 필요 없나?

꼭 그렇지는 않다.

Pi는 하네스이고, 실제 모델은 별도 provider를 쓴다.

Claude 모델을 쓰려면 Anthropic 계정, API key, 또는 지원되는 인증 방식이 필요할 수 있다.

즉 Pi는 Claude Code 대체 후보이지 Claude 모델 대체 후보가 아니다.

Pi는 무료인가?

Pi 자체는 오픈소스 도구로 소개되어 있지만, 모델 사용 비용은 별도다.

OpenAI, Anthropic, Kimi, OpenRouter 등 어떤 provider를 쓰느냐에 따라 비용이 달라진다.

도구 가격과 모델 사용료를 분리해서 봐야 한다.

Pi가 Claude Code보다 더 안전한가?

기본값만 보면 그렇게 단정하기 어렵다.

Claude Code는 공식적으로 permission, settings, sandbox, subagent 권한 같은 흐름을 제공한다.

Pi는 extension으로 비슷한 구조를 만들 수 있지만, 사용자가 직접 설계하고 검증해야 한다.

안전성은 Pi 자체보다 네가 만든 운영 경계에 더 크게 달려 있다.

Pi가 더 똑똑한가?

Pi가 모델은 아니다.

따라서 “Pi가 더 똑똑하다”는 표현은 정확하지 않다.

같은 모델을 쓰더라도 Pi의 하네스 구조, context 관리, extension, 세션 트리 때문에 작업 결과가 더 좋아질 수는 있다.

똑똑함보다 운영성이 달라진다고 보는 편이 맞다.

MCP가 없으면 불편하지 않나?

처음에는 불편할 수 있다.

하지만 모든 작업에 MCP가 필요한 것은 아니다.

작은 CLI 도구, README, AGENTS.md, extension만으로 충분한 작업도 많다.

MCP가 필요한 순간에는 extension이나 package를 검토하되, 민감 권한부터 나눠야 한다.

초보자도 Pi를 써도 되나?

써볼 수는 있다.

다만 첫 도구로는 Claude Code나 Cursor 쪽이 편할 수 있다.

Pi는 “기능이 없다”가 아니라 “기능을 만들 수 있다”에 가까운 도구다.

이 문장이 귀찮게 느껴지면 아직은 완성형 도구가 낫다.

지금 내 결론은?

나는 지금 당장 Claude Code를 지우지는 않는다.

대신 Pi를 별도 실험 repo에서 7일 테스트해볼 후보로 본다.

특히 Obsidian 자동화, 블로그 초안, path protection, 작은 CLI 도구 연결에는 가능성이 크다.

하지만 팀 작업과 보안 민감 작업에서는 Claude Code를 유지한다.

대체가 아니라 역할 분담부터 시작하는 게 현실적이다.

관련 글

출처