TL;DR

Pi Web은 로컬의 pi 에이전트 JSONL 세션 파일을 직접 파싱해 브라우저에서 세션 트리, 실시간 채팅, 포크 및 브랜치 관리를 제공하는 경량 웹 인터페이스이다. 서버는 AgentSession을 인프로세스로 실행하고 Server-Sent Events로 브라우저에 출력을 스트리밍하므로 별도 중계 서비스 없이 실시간 상호작용이 가능하다. models.json을 통해 웹에서 모델 인증과 기본 설정을 제어할 수 있고 Git 워크트리 전환을 통합해 브랜치별 코드 컨텍스트에 맞춘 세션 관리를 지원한다. 이 설계는 터미널 기반 탐색의 비효율을 줄이고 파일 컨텍스트를 함께 보면서 에이전트와 실험을 반복하려는 워크플로우에 적합하지만 원본 세션 파일과 서버에 대한 로컬 접근 권한이 전제 조건이다. 사용 시작은 npx 한 줄 실행 또는 글로벌 설치 후 pi-web 명령으로 가능하며 개발 모드는 npm run dev로 띄운다.

주요 기능

• 프로젝트별로 이전 pi 대화를 세션 트리 형태로 열람하고 특정 시점에서 포크를 생성해 별도 라우트로 분기할 수 있다. 이 기능은 터미널 히스토리를 뒤지지 않고 과거 작업을 이어가거나 안전하게 실험 방향을 분리하는 데 용이하다. 파일 경로 기반의 인코딩을 이용해 동일 경로 내 여러 세션을 관리한다.
• 브라우저 사이드에서 파일 트리와 문서·이미지·오디오·PDF 미리보기를 동시에 제공하며 에이전트가 동작하는 동안 옆에서 코드를 확인하고 보조 정보를 참조할 수 있다. 파일 읽기 권한과 탐색 범위는 선택한 프로젝트 디렉토리로 한정되어 안전성을 유지한다. 마크다운과 Mermaid, KaTeX 렌더링을 포함한 문서 플러그인이 통합되어 있다.
• 서버에서 AgentSession을 인프로세스로 실행하고 SSE를 통해 클라이언트에 이벤트 스트림을 전송해 메시지, 툴콜, 사고 상태를 실시간으로 동기화한다. 이 구조는 브라우저가 지속적으로 에이전트 출력을 수신하며 인터랙티브 제어를 가능하게 한다. RPC형 관리 레이어가 세션 라이프사이클과 명령 디스패치를 조율한다.
• models.json 파일을 통해 모델 목록과 기본 설정을 읽고 쓰며 웹 UI에서 모델 인증, 시험 호출, thinking 레벨 설정을 조정할 수 있다. 모델 설정 변경은 서버 측 구성 파일에 반영되어 이후 세션 생성에 영향을 준다. HTTP 프록시 환경 변수를 지원해 외부 API 호출을 프록시 경로로 라우팅할 수 있다.

어떻게 동작하는가

Pi Web은 사용자 홈의 pi 세션 JSONL 파일을 직접 파싱해 세션 트리와 분기 컨텍스트를 구성하고 브라우저에 표시한다. 서버는 AgentSession을 인프로세스로 생성해 에이전트 명령 처리와 툴 호출을 실행하며 이벤트를 Server-Sent Events로 클라이언트에 스트리밍해 UI가 점진적으로 결과를 반영하도록 한다. 파일 접근과 경로 인코딩, models.json 읽기·쓰기 같은 유틸리티는 서버 측 라이브러리에서 안전 경계와 함께 처리된다.

해결 문제

터미널 기반 pi 세션은 긴 대화와 툴 호출을 사람이 읽기 쉬운 형태로 탐색하기 어렵고 프로젝트 파일 컨텍스트와 함께 보기 힘들다는 문제가 존재했다. Pi Web은 로컬 세션 파일을 구조화해 브라우저에서 세션 트리, 분기, 포크를 직관적으로 탐색하게 함으로써 세션 재개와 실험 분리를 용이하게 만든다. 또한 모델 구성, 스킬 관리, 파일 미리보기, 실시간 SSE 스트리밍을 통합해 단일 인터페이스로 개발 흐름을 통합한다.

차별점

• 세션 데이터를 직접 JSONL 파일에서 읽어오는 구조로 외부 데이터 동기화가 필요 없고 로컬 저장소 상태를 그대로 반영한다.
• AgentSession을 서버 프로세스 내에서 실행하고 SSE로 브라우저에 스트리밍하는 방식은 별도 중간 서비스 없이 실시간 상호작용을 제공한다.
• Git 워크트리 전환을 사이드바에 통합해 브랜치별 코드 컨텍스트에 따라 새로운 세션과 탐색 상태가 자동으로 맞춰지게 한다.
• 웹 UI에서 models.json을 편집하고 모델 인증을 테스트할 수 있어 터미널 기반 설정보다 더 쉬운 모델 관리 경로를 제공한다.

사용 사례

• 로컬에서 에이전트와 상호작용하며 코드 변경을 시도하는 개발자가 IDE나 터미널을 오가며 세션 컨텍스트를 유지할 필요가 있을 때 유용하다. Pi Web은 파일 탐색기와 채팅 창을 나란히 제공해 에이전트 출력을 보면서 소스와 문서를 바로 확인할 수 있다. 이로 인해 빠른 반복 실험과 디버깅이 가능해진다.
• 연구나 프로토타이핑 단계에서 이전 세션을 포크하고 다른 방향으로 실험을 분리해야 할 때 포크 기능을 통해 별도의 JSONL 파일을 생성해 실험을 격리할 수 있다. 동일 세션 파일 내부의 브랜치 기능을 이용하면 중간 상태를 보존한 채 다른 시도를 이어갈 수 있다. 파일 기반 분기는 협업 시점의 재현성과 비교를 단순화한다.
• 오프라인 환경이나 프라이빗 네트워크에서 로컬 모델이나 에이전트를 운용할 때 웹 UI를 통해 사용자 인증 정보와 모델 설정을 로컬에서 관리할 수 있다. HTTP 프록시와 환경 변수 지원으로 사내 프록시 환경에 맞춰 외부 API 호출 루트를 지정할 수 있다. models.json 연동으로 인증 키와 기본 모델 구성을 중앙에서 제어할 수 있다.

시작하기

즉시 실행이 필요할 경우 npx @agegr/pi-web@latest 한 줄로 서버를 기동하면 로컬에서 http://localhost:30141 주소로 접근할 수 있다. 글로벌 설치를 원하면 npm install -g @agegr/pi-web 후 pi-web 명령으로 서버를 시작할 수 있으며 실행 옵션으로 포트와 호스트, 자동 브라우저 오픈 여부를 제어할 수 있다. 개발용으로는 npm install 및 npm run dev로 로컬 개발 서버를 띄우고 node_modules/.bin/tsc --noEmit 및 npm run lint로 기본 검사를 수행하면 된다.

요구사항

• Node.js와 npm이 시스템에 설치되어 있어야 하며 TypeScript 빌드와 실행을 위해 표준 Node 개발 환경이 필요하다.
• pi 에이전트 세션 파일이 기본 경로 ~/.pi/agent/sessions 에 있어야 브라우저에서 세션을 바로 읽어올 수 있으며 다른 경로를 사용하려면 PI_CODING_AGENT_DIR 환경 변수를 지정해야 한다.
• 서버 측에서 외부 API 호출이 필요한 경우 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 환경 변수를 설정해 프록시 라우팅을 구성할 수 있다.

이미지 분석