pi-grok-agent가 Grok Build를 Pi 코딩 에이전트의 추가 모델 제공자로 연결함

TL;DR

• pi-grok-agent는 Grok Build를 Pi 코딩 에이전트의 추가 모델 제공자로 연결하며, Grok의 기본 환경과 도구를 유지하면서 Pi가 세션 제어와 권한 관리를 담당하는 패키지임.
• Pi는 WebSocket 기반 Agent Client Protocol(ACP)로 세션을 제어하고, MCP 루프백 콜백으로 Grok의 도구 요청을 처리함.
• 로컬 게이트웨이는 기본적으로 127.0.0.1:2419에서 실행되며, 같은 머신의 모든 Pi 프로세스가 게이트웨이에 연결됨.
• Grok 4.5~4.7 및 Grok 4.7 Build Fast를 지원하며, 각 모델은 500,000토큰 문맥 창과 네 가지 추론 강도를 제공함.
• 이 구성은 운영체제 샌드박스가 아니며 Grok은 사용자 권한으로 실행됨; Grok 계정이 필요하고 API 키 접근은 지원하지 않음.

설치 및 개요

• 패키지 이름은 pi-grok-agent이며, 다음 명령으로 설치함.
• pi install npm:pi-grok-agent
• Grok Build를 Pi 코딩 에이전트의 추가 모델 제공자로 실행함. Grok은 기본 환경, 도구, 세션 기록을 유지하고, Pi는 직접 구성할 수 있는 하네스, 턴 제어, 권한 요청, 확장 기능을 제공함.

연결 방식

• Pi는 턴, 대화 기록, 권한 경계, 대화상자를 제어함.
• 게이트웨이는 머신당 하나씩 실행되며, 기본 주소는 127.0.0.1:2419임. 게이트웨이는 가드와 MCP를 제공함.
• Grok Build는 자체 도구와 에이전트, 기록을 사용하며 ~/.grok 로그인을 이용함.
• Pi는 WebSocket을 통한 Agent Client Protocol(ACP)로 세션을 제어함. Grok은 스트리밍 응답, 사고 블록, 이미지 및 동영상 요청을 반환함.
• Grok의 모든 도구 요청은 MCP 루프백 콜백을 통해 Pi로 전달됨.
• 첫 Grok 턴에서 로컬 게이트웨이가 자동 실행되며, 머신의 모든 Pi 프로세스가 해당 게이트웨이에 연결됨.
• 자세한 내용은 docs/architecture-diagram.md 및 docs/usage.md에 있음.

기능

• Pi가 권한과 경계를 설정함. 읽기 전용, 확인 요청, 자동, YOLO 권한 모드를 지원함.
• Pi가 의사결정을 담당함. Grok의 도구 호출 요청, 턴 순서, user_ask_question 프롬프트가 Pi로 위임됨.
• Grok은 Pi의 확장 도구를 MCP를 통해 pi__<name> 형식으로 사용할 수 있으며, 결과는 동일한 Grok 턴에서 이어짐.
• Grok은 자체 도구와 확장 기능을 모두 유지함. 기본 도구 세트로 실행할 때 Grok의 성능이 더 좋다는 자체 관찰에 따라, 이 프로젝트는 Grok의 도구를 유지하면서 별도의 도구 묶음을 구매하지 않는 데 목적이 있음.

모델

• grok/grok-4.7 — Grok 4.7; 추론 강도 low, medium, high, xhigh; 문맥 창 500,000토큰.
• grok/grok-4.7-build-fast — Grok 4.7 Build Fast; 추론 강도 low, medium, high, xhigh; 문맥 창 500,000토큰.
• grok/grok-4.6 — Grok 4.6; 추론 강도 low, medium, high, xhigh; 문맥 창 500,000토큰.
• grok/grok-4.5 — Grok 4.5; 추론 강도 low, medium, high, xhigh; 문맥 창 500,000토큰.
• Pi에서 이용할 수 있는 모델은 계정 접근 권한에 따라 결정됨.

안전성

• 이 패키지는 xAI 채팅 완성 API가 아니라 ACP를 통해 Grok Build 에이전트에 연결됨. ACP 프로토콜은 에이전트에 대한 완전한 가시성이나 제어 기능을 제공하지 않으며, 이 구성에서 Grok Build의 모든 기능과 확장 기능이 안전성 검증을 거친 것은 아님.
• 도구 권한 게이트는 운영체제 샌드박스가 아니며 Grok은 사용자 권한으로 실행됨.
• 게이트웨이는 루프백에서만 수신하고 베어러 비밀 값을 요구하며, Grok을 --always-approve 옵션으로 실행하지 않음.
• 헤드리스 사용이 승인을 뜻하지는 않음. 기본적으로 헤드리스 Pi는 Grok의 권한 프롬프트를 취소함.
• postEditCheck 및 stopCheck 설정은 셸 명령으로 실행되므로 실행 가능한 코드로 취급해야 함.

참고 사항

• API 키 접근과 호환되지 않음. 멤버십 등급과 관계없이 Grok 계정이 필요함.
• OAuth 토큰이 만료되면 Grok Build에서 /login을 실행하거나 Pi에서 /grok login을 실행해 자격 증명을 갱신할 수 있음.
• Pi에 표시되는 토큰 읽기, 토큰 쓰기, 캐시 읽기, 캐시 적중률은 Grok Build에서 가져옴.
• 긴 다단계 도구 호출 중 Pi가 부정확한 데이터를 보고할 때가 있으나 다음 턴에 수정됨.

문서

• docs/usage.md — 설정, 대여 도구, 권한, 게이트웨이 가드, 훅, /grok 명령, 문제 해결.
• docs/architecture-diagram.md — Mermaid 및 ASCII 다이어그램.
• docs/first-class-model.md — 설계와 턴 매핑.
• docs/launch-verification.md — 검증된 주장을 뒷받침하는 실제 실행 기록.

피드백

• 이슈를 열 때 node --version, pi --version, grok --version 출력, 모델 ID, /grok debug의 짧은 비식별 발췌 내용을 포함함.

라이선스

• Apache License 2.0.