pi-go
CI
Go Reference
Go Version
License
Release
codecov
GitHub stars
GitHub issues
Google ADK Go를 기반으로 구축된 터미널 기반 코딩 에이전트입니다. 여러 LLM 제공업체에 연결하고, 샌드박스화된 도구를 실행하며, LSP를 통합하고, 프로세스 기반 서브 에이전트 시스템을 갖추고 있습니다.
pi-go TUI
주요 기능 (Features)
-
다중 제공업체 LLM: 모델용으로 Anthropic의 Claude, OpenAI의 GPT/O 시리즈, Google의 Gemini, Mistral, xAI의 Grok, Azure OpenAI, OpenRouter, OpenCode, 그리고 Ollama(로컬 또는 클라우드)를 지원합니다.
-
샌드박스 도구: 읽기, 쓰기, 편집, 셸(shell), grep, find, tree, git 작업을 수행할 수 있습니다. 모든 도구는 os.Root를 통해 프로젝트 디렉터리로 제한됩니다.
-
대화형 TUI: 마크다운 렌더링(Glamour) 기능과 슬래시 명령어, 테마 기능을 갖춘 Bubble Tea v2를 제공합니다.
-
세션 지속성: 브랜칭, 압축(compaction), 재개 기능을 가진 JSONL 추가 전용 이벤트 로그를 지원합니다.
-
모델 역할: CLI 플래그를 통해 선택 가능한 명명된 구성(default, smol, slow, plan, commit)을 제공합니다.
-
서브 에이전트: 탐색(explore), 계획(plan), 디자이너(designer), 검토자(reviewer), 작업(task), 빠른 작업(quick_task) 유형을 가진 프로세스 기반 다중 에이전트 시스템입니다.
-
LSP: Go, TypeScript/JS, Python, Rust, Java용 JSON-RPC 클라이언트이며, 자동 포맷 및 진단(diagnostics) 후크를 지원합니다.
-
AI Git 도구: 저장소 개요, 파일 차이점(diffs), 덩어리 구문 분석(hunk parsing), 그리고 LLM 생성 컨벤셔널 커밋( /commit) 기능을 제공합니다.
-
RPC 서버: IDE/에디터 통합을 위한 유닉스 소켓 JSON-RPC 2.0을 지원합니다.
-
메모리 궁전 (Memory Palace): SQLite 스토리지를 갖춘 4계층의 문맥적 메모리로, 의미론적 임베딩(semantic embeddings) (all-MiniLM-L6-v2), 시간적 지식 그래프(temporal knowledge graph), 프로젝트/대화 마이너를 포함합니다.
-
확장 기능: 후크(셸 콜백), 기술(.SKILL.md 지침), 그리고 Model Context Protocol (MCP) 서버를 지원합니다.
-
플러그인 마켓플레이스(Plugin marketplaces) — 모든 Claude Code 호환 플러그인 마켓플레이스에서 스킬 번들을 설치할 수 있으며, 버전 추적 및 업데이트 기능이 제공됩니다 (pi plugin)
-
스킬 감사(Skills audit) — 스킬 파일의 숨겨진 유니코드 문자, BiDi 공격, 공급망 위협에 대한 보안 검사 기능을 수행합니다 (pi audit)
아키텍처 (Architecture)
cmd/pi/ 엔트리 포인트 — CLI 파싱, 출력 모드 선택
internal/
├── agent/ ADK 에이전트 설정, 재시도 로직(retry logic), 러너(runner)
...
요청 흐름 (Request flow)
User input → CLI → Agent → LLM provider → Tool calls → Sandbox → Response → TUI
↕ ↕ ↕
Session store Palace LSP servers
...
상세 문서는 ARCHITECTURE.md를 참조하십시오.
설치 (Installation)
빠른 설치 (Quick install, 권장)
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/dimetron/pi-go/main/scripts/install.sh | bash
이 스크립트는 사용자의 OS/아키텍처를 감지하고 최신 릴리스 바이너리를 다운로드하여 /usr/local/bin (필요한 경우 ~/.local/bin)에 설치합니다.
Windows
powershell -NoProfile -Command "iwr https://raw.githubusercontent.com/dimetron/pi-go/main/scripts/install.ps1 -UseBasicParsing | iex"
또는, 체크아웃(checkout)을 통해:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
%LOCALAPPDATA%\Programs에 pi.exe를 설치하고 해당 디렉터리를 사용자 PATH에 추가합니다. 새 PATH가 적용되도록 터미널을 재시작하십시오.
Windows PowerShell 5.1(Windows 10/11에 내장됨) 및 PowerShell 7 이상에서 실행됩니다. windows/amd64 전용입니다. 최신 릴리스를 확인하는 동안 GitHub API 속도 제한에 도달하면 GITHUB_TOKEN을 설정하십시오.
설치 프로그램은 다운로드된 파일을 릴리스의 checksums.txt와 비교하여 불일치할 경우 설치를 거부합니다. 이는 손상되거나 교체된 아카이브는 잡아내지만, 대체된(substituted) 릴리스는 잡아낼 수 없습니다. 왜냐하면 checksums.txt가 아카이브와 같은 경로로 이동하기 때문입니다. 이 질문에 답하는 출처 확인(provenance check)을 수행하려면 나중에 pi verify를 실행하세요 — 릴리스 검증 참조.
PATH에 bash.exe가 없는 Windows 머신(기본 Windows 설치에는 없음)에서는 대신 powershell.exe를 통해 에이전트 명령을 실행해야 합니다. 따라서 프롬프트에서 && 대신 PowerShell 구문인 ; 또는 줄 바꿈을 작성하세요. Git for Windows를 설치하면 bash가 PATH에 추가되어 bash 동작이 복원됩니다.
NixOS / Nix
이 저장소는 pi-go를 재현 가능하게(reproducibly) 빌드하고 NixOS 모듈을 노출하는 flake를 포함합니다. NixOS 구성에 설치하려면 해당 저장소를 입력(input)으로 추가하세요:
# flake.nix
{
inputs.pi-go.url = "github:dimetron/pi-go";
...
}
configuration.nix에서 활성화하세요:
{ programs.pi-go.enable = true; }
그런 다음 sudo nixos-rebuild switch --flake .로 재빌드하세요. 일회성 사용의 경우, nix run github:dimetron/pi-go를 실행하거나 nix profile install github:dimetron/pi-go로 프로필에 설치할 수 있습니다.
go install
go install github.com/dimetron/pi-go/cmd/pi@latest
GOPATH/bin이 PATH에 포함되어 있는지 확인하세요. 바이너리는 pi로 설치됩니다.
소스에서 빌드
git clone https://github.com/dimetron/pi-go.git
cd pi-go
go install ./cmd/pi
사전 빌드된 바이너리
사용 중인 플랫폼의 최신 릴리스는 Releases 페이지에서 다운로드하세요.
릴리스 검증
pi verify는 해당 바이너리에 대해 게시된 증명서(attestations)와 실행 중인 바이너리를 비교하며, 다른 도구는 필요하지 않습니다:
pi verify
pi verify ./pi
pi verify pi-go_1.2.3_linux_amd64.tar.gz
...
/usr/local/bin/pi
sha256:abd70659b49183320320426af4abf34555b031e432aff27afbdbf1be39e1ecff
...
검증은 파일의 SHA-256 해시값만을 기준으로 하며, 바이너리에 컴파일된 버전, 설치된 이름, 출처 URL 등 다른 요소는 모두 공격자가 통제할 수 있습니다. 이 다이제스트(digest)는 GitHub의 attestations API에서 조회되며, 반환되는 Sigstore 번들들은 공개적인 Sigstore 신뢰 루트(trust root)를 기준으로 검증됩니다. 여기에는 인증서 체인(certificate chain), Rekor 투명성 로그 포함 여부(transparency-log inclusion), 서명된 인증서 타임스탬프, 그리고 이 저장소의 릴리스 워크플로우가 태그 위에서 실행되었음을 명시하는 인증서 신원 정보가 포함됩니다. 다른 어떤 워크플로우, 브랜치 또는 저장소에서 온 서명은 거부됩니다.
직접 빌드한 바이너리는 어떠한 증명(attestation)도 없으므로 검증되지 않은 것으로 보고됩니다. 이는 실패가 아니라 예상되는 답변입니다.
검증을 위해서는 네트워크 접근이 필요합니다. Sigstore 신뢰 루트는 첫 실행 후 ~/.pi-go/sigstore에 캐시됩니다.
GitHub CLI를 이용한 검증
만약 바이너리가 스스로 보증하는 것을 믿고 싶지 않다면, 동일한 증명은 gh로 읽을 수 있습니다:
gh attestation verify ./pi --repo dimetron/pi-go
...
무엇이 증명되고, 무엇이 게시되는지
릴리스 아카이브와 그 안에 있는 원시 바이너리 모두가 증명의 대상(attestation subjects)입니다. scripts/install.sh는 바이너리를 추출하여 PATH에 배치하므로, 아카이브 다이제스트가 최종적으로 실행하는 다이제스트가 아닙니다. 아카이브만 증명할 경우 설치된 바이너리가 검증 불가능하게 됩니다. 따라서 바이너리 자체는 릴리스 에셋으로 게시되지 않으며, 모든 검증에 필요한 것은 오직 다이제스트뿐입니다.
각 릴리스는 SPDX JSON 형식으로 SBOM(Software Bill of Materials)을 에셋으로 게시합니다.
pi-go_<version>_<os>_<arch>.tar.gz.sbom.json — 해당 특정 아카이브의 내용을 syft가 카탈로그화한 파일입니다.pi-go_<version>_sbom.spdx.json — 소스 트리에서 집계된 SBOM이며, SBOM 증명서(attestation)가 바인딩되는 대상입니다. 이 파일은 Go 모듈 그래프를 포함하며, 이는 빌드 매트릭스의 모든 플랫폼에 걸쳐 동일하고, 릴리스 자체가 빌드될 때 사용된 고정 GitHub Actions도 포함합니다.
통합 SBOM을 로컬에서 재생성하려면 make sbom을 사용하십시오 (syft 필요).
요구 사항
- Go 1.27 이상
- 최소한 하나의 LLM 제공업체 API 키 또는 실행 중인 Ollama 인스턴스
API 키
제공업체의 API 키를 환경 변수로 설정하십시오. 제공업체는 모델 이름으로부터 추론되므로, 일반적으로 --model만 라우팅하면 됩니다.
| 제공업체 | 모델 접두사 | API 키 환경 변수 | 기본 URL 환경 변수 |
|---|
| Anthropic | claude-* | ANTHROPIC_API_KEY (또는 ANTHROPIC_AUTH_TOKEN) | ANTHROPIC_BASE_URL |
| ... | | | |
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."
...
인식된 접두사가 없는 이름은 추측하는 대신 거부됩니다. Ollama 모델을 명시적으로 지정하려면 ollama/ 접두사나 :cloud 접미사를 사용하십시오.
환경 변수를 직접 내보내는 대신 대화형으로 제공업체를 구성하려면 다음을 사용합니다:
이 마법사는 사용할 제공업체, API 키 및 기본 모델을 묻습니다. 이 정보는 ~/.pi-go/.env에 키를 기록하고, 제공업체와 모델은 ~/.pi-go/config.json의 default 역할에 기록됩니다. 이는 수동으로 환경 변수를 내보내거나 설정 파일을 직접 편집했을 때 저장되는 위치와 동일합니다. 자격 증명이 필요 없는 제공업체(Ollama, agentgateway)는 키 단계를 건너뛰고; pi-go가 오프라인 카탈로그를 가지고 있지 않은 제공업체(Ollama, agentgateway, Azure, OpenCode)는 데몬이나 배포 환경이 무엇을 서비스하는지 사용자만 알기 때문에 모델 이름을 직접 입력해야 합니다.
:cloud 태그는 목적지가 아닌 모델 이름을 지정합니다. OLLAMA_API_KEY가 설정되어 있으면 요청은 바로 api.ollama.com으로 전송되며, 이 키가 없으면 로컬 데몬(local daemon)으로 전송됩니다. 이 로컬 데몬은 Ollama 0.12 버전 이후부터 사용자의 ollama signin ID를 통해 클라우드 모델을 제공해 왔기 때문에, 아무 키 없이도 pi --model deepseek-v3.1:671b-cloud가 작동합니다. 태그와 관계없이 ollama/ 접두사는 항상 로컬 데몬을 의미하며, 명시적인 OLLAMA_HOST는 이 둘 모두를 재정의(override)합니다.
빌드 (Build)
make build
make test
make lint
...
사용법 (Usage)
JSON 모드 (JSON mode)
--mode json은 표준 출력(stdout)에 줄마다 하나의 JSON 객체를 작성합니다. 스트리밍되는 어시스턴트 텍스트는 문장별로 그룹화되므로, 하나의 text_delta가 단일 SSE 청크 대신 전체 문장을 담게 됩니다. 즉, 세 문장으로 된 답변은 76줄이 아닌 5줄이며, delta 필드는 여전히 정확히 해당 답변을 구성하도록 연결됩니다. 텍스트를 재구성하려면 delta를 연결해야 합니다. 이것이 모든 소비자(consumer)가 사용하는 방식입니다.
{"type":"message_start","agent":"pi","role":"model","session_id":"..."}
{"type":"thinking_delta","agent":"pi","delta":"..."}
{"type":"text_delta","agent":"pi","delta":"Go는 컴파일 언어입니다. "}
...
슬래시 명령어 (Slash commands)
| 명령어 | 설명 |
|---|
/help | 사용 가능한 명령어 표시 |
| ... | |
목표 (Goals): 턴을 초월하는 작업
/goal <objective>는 세션 목표를 설정하고 루프(loop)를 시작합니다. 턴이 끝나도 목표가 활성 상태인 경우, 에이전트가 goal_complete 도구를 호출하거나 사이클 예산(cycle budget)이 소진될 때까지 다음 턴이 자동으로 시작됩니다.
/goal keep the tests green after every refactor
목표는 # Current Goal 섹션으로 시스템 프롬프트(system prompt)에 주입되며, 세션의 meta.json에 영구 저장되고, 도달한 사이클과 함께 상태 표시줄에 표시됩니다 (goal 2/8: keep the tests green…).
루프는 경계가 설정되어 있으며(bounded), 모든 경계는 의도적인 선택입니다:
