▲

Pi 코딩 에이전트를 만들며 배운 점

 (mariozechner.at)
5P by GN⁺ 20시간전 | ★ favorite | 댓글 2개
  • pi-coding-agent는 복잡한 기능을 최소화하고, 사용자가 맥락 제어와 투명성을 완전히 확보할 수 있도록 설계된 코딩 에이전트 프레임워크
  • 핵심 구성 요소는 pi-ai, pi-agent-core, pi-tui, pi-coding-agent 네 가지로, 각각 LLM API 통합, 에이전트 루프, 터미널 UI, CLI 통합을 담당
  • 시스템 프롬프트와 도구 세트를 1000토큰 이하로 유지하며, read/write/edit/bash 네 가지 도구만 제공하는 극단적 단순화를 추구
  • 보안 제한이나 하위 에이전트, 계획 모드, MCP 지원을 모두 배제하고, 대신 완전한 관찰 가능성과 제어권을 중시
  • 벤치마크 결과와 실제 사용 경험을 통해, 단순하고 투명한 설계가 복잡한 에이전트보다 충분히 경쟁력 있음을 입증

pi-ai와 pi-agent-core

  • pi-ai는 Anthropic, OpenAI, Google, xAI, Groq 등 다양한 LLM 제공자 통합 API를 제공
    • 스트리밍, 도구 호출, 추론(trace) 지원, 토큰 및 비용 추적, 브라우저 호환성을 포함
    • 주요 API 네 가지(OpenAI Completions/Responses, Anthropic Messages, Google Generative AI)만으로 대부분 모델과 통신 가능
  • 각 제공자별 API 차이를 통합 처리
    • 예: max_tokens 필드명 차이, reasoning 필드 위치, developer 역할 미지원 등
    • 토큰 보고 방식이 제각각이라 정확한 비용 계산은 불가능, pi-ai는 best-effort 방식으로 추적
  • Context handoff 기능으로 세션 중간에 모델 또는 제공자를 교체 가능
    • 예: Anthropic → OpenAI → Google 전환 시, 추론 내용은 `` 태그로 변환되어 유지
  • 모델 레지스트리를 통해 타입 안전한 모델 정의 지원
    • OpenRouter와 models.dev 데이터를 파싱해 모델별 비용·기능 정보를 자동 생성
  • 요청 중단(abort) 과 부분 결과 반환을 완전 지원
    • AbortController로 스트리밍 중단 시, 중간 결과를 그대로 활용 가능
  • 도구 결과 분리 구조를 도입
    • LLM용 텍스트와 UI 표시용 데이터를 분리 반환, TypeBox/AJV로 인자 검증 수행
    • 향후 도구 결과 스트리밍 기능 추가 예정
  • 에이전트 루프는 메시지 처리, 도구 실행, 결과 피드백을 자동 반복
    • 이벤트 기반 구조로 UI 반응형 구현 용이
    • 불필요한 제어 파라미터(최대 단계 등)는 제거하여 단순화

pi-tui

  • pi-tui는 Node.js 기반의 터미널 UI 프레임워크로, 최소한의 flicker로 실시간 업데이트 지원
    • 차등 렌더링(differential rendering) 으로 변경된 라인만 갱신
    • 동기화 출력 시퀀스(CSI ?2026h/l) 로 flicker 최소화
  • 두 가지 TUI 접근법 중, 스크롤백 버퍼를 유지하는 CLI형 출력 방식을 채택
    • 자연 스크롤, 검색 등 터미널 기본 기능을 그대로 활용
    • Claude Code, Codex, Droid와 유사한 구조
  • Retained mode UI를 사용
    • 각 컴포넌트가 자신의 렌더링 결과를 캐시하고, 변경 시에만 다시 그림
    • 전체 화면 재렌더링 없이 효율적 업데이트 가능
  • 성능과 메모리 사용량은 미미하며, 수백 KB 수준으로 대형 세션도 원활히 처리

pi-coding-agent

  • pi-coding-agent는 CLI 기반 코딩 에이전트로, 다음 기능을 제공
    • Windows/Linux/macOS 지원, 세션 관리(재개·분기), 모델 전환, 프로젝트별 AGENTS.md 로드
    • OAuth 인증, 테마 실시간 변경, HTML 세션 내보내기, 헤드리스 모드(JSON/RPC) 지원
  • 시스템 프롬프트는 1000토큰 이하의 간결한 형태
    • read/write/edit/bash 네 가지 도구만 명시
    • 불필요한 설명이나 복잡한 규칙 제거, 사용자는 AGENTS.md로 자유롭게 확장 가능
  • 도구 세트는 최소 4개로 구성
    • read, write, edit, bash만 사용하며, 대부분의 코딩 작업에 충분
    • 추가 도구는 선택적으로 활성화 가능 (예: grep, find, ls)
  • YOLO 모드 기본 적용
    • 파일 시스템 전체 접근 및 명령 실행에 제한 없음
    • 보안 프롬프트나 사전 검증 절차 제거, 대신 컨테이너 환경 사용 권장
  • 내장 To-do, Plan 모드, MCP, Background bash, Sub-agent 모두 제거
    • To-do/Plan은 단순히 파일 기반 관리(TODO.md, PLAN.md) 로 대체
    • MCP는 토큰 낭비와 복잡성 때문에 배제, 대신 CLI+README 방식으로 대체
    • Background bash는 tmux 사용 권장
    • Sub-agent는 가시성 부족으로 비활성화, 필요 시 bash로 자기 자신을 호출
  • 관찰 가능성(Observability) 을 중시
    • 모든 명령, 파일 접근, 출력이 투명하게 표시
    • Claude Code 등 타 에이전트의 “블랙박스” 구조와 대비

Benchmarks

  • Terminal-Bench 2.0에서 Claude Opus 4.5 모델과 함께 테스트 수행
    • Codex, Cursor, Windsurf 등과 비교 시 경쟁력 있는 성능 확보
    • 결과 파일(results.json)은 공개 저장소에 제출
  • Terminus 2와 같은 단순형 에이전트도 유사한 성능을 보여, 미니멀 접근의 유효성을 입증

결론

  • pi는 복잡한 기능보다 맥락 제어, 단순성, 투명성을 우선시한 코딩 에이전트
  • 실제 사용과 벤치마크 모두에서 대형 에이전트와 동등한 효율을 보임
  • 향후 추가 예정 기능은 컨텍스트 압축(compaction) 과 도구 결과 스트리밍 정도
  • 프로젝트는 오픈소스로 공개되어 있으며, 포크 및 확장 자유 보장
  • 핵심 교훈은 “단순함이 곧 통제력이며, 통제력이 곧 생산성”임
▲
GN⁺ 20시간전  [-]
Hacker News 의견들

  • 정말 멋지고 사려 깊은 프로젝트를 만든 것 같음
    나도 context engineering과 트리 기반 대화 구조의 중요성에 완전히 공감함
    기존의 선형 대화 흐름은 너무 제한적이어서, 연구나 아이디어 발상 시 LLM과 협업할 때 불편했음
    나도 비슷한 철학으로 개인용 도구를 만들었는데, 컨텍스트를 잘 구축해두고 재활용하거나, 사이드 퀘스트를 실행해 좋은 결과만 가져오는 식이었음
    네가 만든 버전이 훨씬 가치 있는 구현임. 덕분에 Pi를 알게 되어 기쁨

    • 나도 비슷한 시도를 했음. MIND_MAP.md라는 마크다운 파일을 그래프 형태로 관리하면서 인용을 인라인으로 기록함
      세션 간 메모리를 유지하고, 서브에이전트를 생성할 때 컨텍스트 낭비를 줄이는 방식임
      내 예시 코드 참고 가능함

  • OpenClaw와 Pi-agent의 관계가 ollama/llama-cpp 관계와 비슷하다고 느낌
    전자가 주목받지만, 실제로는 후자가 더 인상적임
    Claude Code는 구독 혜택 덕분에 현재는 괜찮지만, 시장이 안정되고 API 단가와 비슷해지면 토큰 단위 결제형 프리미엄 경험이 더 나은 선택이 될 것 같음
    결국 커스터마이즈 가능한 에이전트 프레임워크가 폐쇄형 앱보다 우위에 설 것이라 생각함

    • 오히려 API 가격이 더 내려가고, Claude Code의 구독 혜택은 더 커질 가능성이 높다고 봄
      추론 비용 구조가 생각보다 효율적이고, R&D 자금도 충분함
      모든 도구가 점점 개선되고 있으며, 경쟁 제품들도 완벽하지 않음
    • Pi도 구독 연동이 가능함. OpenAI가 GPT 구독을 Pi에서 사용할 수 있도록 허용했음
      개인적으로는 Peter의 프로젝트가 주목받는 게 기쁨
      OpenClaw 쪽 PR은 여전히 많지만, Pi는 그 1/100 수준이라 관리가 훨씬 수월함
    • ChatGPT와 GPT-3의 관계와 거의 동일한 상황임
      OpenAI도 “왜 ChatGPT가 그렇게 인기인지 모르겠다, GPT는 이미 API로 있었는데”라고 말했었음
    • ollama처럼 결국 enshittification(품질 저하)될 가능성도 있다고 봄
    • 이름이 “pi”인 건 좀 혼란스러움. 이미 유명한 다른 “Pi”가 있는데 왜 그 이름을 썼는지 의문임

  • Google이 아직도 tool call streaming을 지원하지 않는 게 놀라움
    로컬 토크나이저조차 제공하지 않아, AI Studio가 매번 API 호출로 토큰을 세는 비효율적인 구조임

    • AI Studio는 입력 중이 아니어도 계속 토큰을 세는 버그가 있음
      CPU 사용률이 100%까지 올라가서, 내 노트북이 TPU 클러스터보다 전력 많이 쓰는 느낌임
    • 사실 Anthropic도 토크나이저를 제공하지 않음

  • 다른 코딩 에이전트들의 보안 조치는 대부분 security theater에 불과함
    Codex는 OS 샌드박스(예: macOS Seatbelt) 안에서 명령을 실행하므로 완전히 무용하지는 않음

    • 읽기 외의 모든 tool call은 수동 승인 절차가 필요하다고 생각함
      귀찮더라도, 잘못된 명령 복구보다 낫다고 봄
    • 내 Codex는 샌드박스 밖의 SDK를 패치하라고 하면 파이썬으로 파일을 수정함
    • 에이전트를 컨테이너 밖에서 실행하는 건 위험함. 기본 중의 기본임
    • 나는 Codex를 GitHub 리포에 연결해 PR을 자동 생성하도록 설정했음
      DB는 건드리지 않고, UI와 미들레이어 코드만 수정하게 함
    • Codex가 Claude Code처럼 임의로 샌드박스를 비활성화하는지 궁금함
    • YOLO 모드는 컨테이너 안에서만 써야 함. 필요한 리소스만 접근하도록 제한해야 함

  • 이미 몇몇 파워 유저들이 Pi로 전환하는 걸 봤고, 나도 고려 중임
    Pi의 장점은 컨텍스트 완전 제어와 확장 가능한 툴 구조임
    시스템 프롬프트, todo 확장, MCP 어댑터 등 다양한 예시가 있음
    컨텍스트 성능 한계나 context rot, contextual drift 같은 문제를 이해한다면 Pi의 가치가 명확함
    관련 링크 모음

    • Pi는 moltXYZ에서 가장 주목받아야 할 부분임
      Armin이 확실히 시대를 앞서감
      Claude Code는 여전히 훅과 컨텍스트 관리가 얕음

  • 나는 아직 Cursor를 쓰고 있음
    Claude Code로 넘어가려 했지만, 내 작은 코드베이스에서는 Cursor가 훨씬 빠름
    다만 diff-review UI가 Git과 통합되지 않아 불편함
    AI가 만든 변경과 내가 만든 변경을 구분하기 어렵고, Git 통합 리뷰가 더 중요하다고 느낌

    • Cursor는 짧은 피드백 루프가 강점임
      Claude Code는 결과를 믿고 맡기는 느낌이라 불안함
      모델을 자유롭게 바꿀 수 있는 게 핵심임. 언어나 작업 종류에 따라 모델 성능이 다름
    • VS Code용 Claude Code 확장을 설치하면, 대규모 코드베이스 탐색과 CC 통합을 동시에 누릴 수 있음
    • Claude Code는 기본적으로 프로젝트 인덱스가 없어 파일을 일일이 탐색함
      나는 시작 시 파일 목록을 컨텍스트에 넣는 훅을 만들어 속도를 개선했음
      여러 파일을 동시에 수정하는 커스텀 툴도 만들어 약 3배 빨라졌지만, 일부 예외 케이스로 비활성화함
    • 나도 부트스트랩 솔로 개발자로, Claude를 작은 작업 자동화에 활용함
      예를 들어 프론트엔드 테스트 자동화나 랜딩 페이지 수정 등
      메인 기능은 별도의 Claude 인스턴스에서 긴밀히 피드백 루프로 관리함
    • Cursor도 개선 중임. 곧 AI 작성 라인 추적(blame) 기능이 추가되어, 어떤 모델이 어떤 프롬프트로 작성했는지 확인 가능함

  • 미니멀한 에이전트 아키텍처에 대한 글이 인상적이었음
    “필요하지 않으면 만들지 않는다”는 철학이 마음에 듦
    나는 OpenClaw를 사용해 여러 워크플로를 병렬로 관리함 — 고객 지원, 배포 모니터링, 코드 리뷰 등
    핵심은 컨텍스트 엔지니어링임
    OpenClaw의 workspace-first 모델은 AGENTS.md, TOOLS.md, memory/ 디렉토리로 세션 간 학습을 지속함
    에이전트가 스스로 학습하는 과정을 로그로 관찰할 수 있음
    보안 연극보다는 현실적인 위협 모델을 인정하는 접근이 좋음
    여러 전문 에이전트를 병렬로 두는 게 범용형보다 낫다는 점도 공감함
    Pi와 OpenClaw를 Terminal-Bench에서 비교해보면 흥미로울 듯함

  • Armin Ronacher가 왜 Pi를 쓰는지에 대한 글이 좋았음
    Armin의 포스트를 보고 Pi가 OpenClaw의 에이전트 하네스라는 걸 처음 알았음

  • Pi는 JavaScript 기반 구조라 브라우저 샌드박스 아키텍처와 잘 맞음
    AI 에이전트의 미래 방향에 적합하다고 생각함
    다만 저자가 vendor extensions에 대해 더 유연했으면 좋겠음
    관련 토론

    • “교집합을 표준화하고, 합집합을 노출하라”는 표현이 인상적이었음

  • 나는 아직 YOLO 모드를 쓰지 않고 있음
    툴링이 완비되려면 6개월은 더 걸릴 듯함
    에이전트가 임의 명령을 실행할 필요는 거의 없음
    lint, 검색, 수정, 웹 접근 정도만 권한 시스템에 통합하면 충분함
    Deno나 Workerd처럼 샌드박싱과 권한 제어가 있는 런타임이면 1차 방어선이 됨
    그래서 Anthropic이 Bun을 선택한 건 이해하기 어려움 — 보안 아키텍처가 거의 없음

답변달기