smallnest/pigo

pigo – Go 기반 CLI 코드 어시스턴트 (pi 스타일 AI 에이전트)

무엇인가요 – pigo는 pi 코드 어시스턴트의 기능을 모방한 오픈소스 명령줄 AI 에이전트로, Go로 작성되었습니다. 파일 읽기/쓰기, 쉘 명령 실행, 웹 페이지 가져오기, 대규모 언어 모델(LLM) 호출을 통해 요청을 이해하고 코드를 수정한 후 결과를 반환할 수 있습니다. 이 도구는 두 가지 모드에서 작동합니다:

헤드리스 (-p …) – 단일 프롬프트로 최종 답변을 출력하거나 JSON 이벤트를 스트리밍합니다.
인터랙티브 REPL – 터미널 UI에서 질문을 반복적으로 제출하고 도구를 실행하며 에이전트의 추론 과정을 확인할 수 있습니다.

주요 기능 (README에 설명됨)

기능	설명
두 가지 실행 모드	`-p`는 단일 스크립트/CI용, REPL은 인터랙티브 사용용입니다.
다수의 LLM 제공자	OpenRouter(기본), 로컬 Ollama, NVIDIA NIM, Anthropic, OpenAI 호환 엔드포인트 등
내장 도구 세트	`read`, `write`, `edit`, `grep`, `find`, `bash` (백그라운드 실행 가능), `todo`, `webfetch`, `websearch`, `memory_search`, `task` 등
세션 관리	이전 세션 목록, 재개, 계속 가능; 각 세션은 `session_id`를 포함한 JSON을 스트리밍합니다.
도구 수준 허용/차단	`--allowed-tools` (화이트리스트) 및 `--disallowed-tools` (블랙리스트) – 블랙리스트가 우선하며, 도구가 모델에 제시되기 전에 강제 적용됩니다.
프로젝트 신뢰	파일시스템 디렉터리는 기본적으로 신뢰되지 않으며, 부작용 도구(`bash`, `write`, `edit`)는 `--approve`를 사용하지 않으면 확인이 필요합니다.
스킬 및 플러그인	슬래시 스타일 명령(`/skill-name`)은 `~/.agents/skills`에서 로드되며, 외부 플러그인으로 더 많은 도구를 추가할 수 있습니다.
프롬프트 템플릿	재사용 가능한 Markdown 프롬프트 스니펫(`/name`로 확장)을 위치 매개변수 구문(`$1`, `${1:-default}`, `$@` 등)으로 사용 가능합니다.
컨텍스트 압축	토큰 창이 한계에 가까워지면 자동 요약되며, 수동으로 `/compact` 명령도 사용 가능합니다.
자기 업데이트	`pigo update`로 최신 GitHub 릴리스로 바이너리 업그레이드 가능합니다.
SDK	핵심 에이전트는 `github.com/smallnest/pigo/agent`로 가져와 다른 Go 프로그램에 임베딩할 수 있습니다.
훅	`PreToolUse`, `UserPromptSubmit` 등 9개의 라이프사이클 훅 포인트가 있으며, 쉘 명령을 실행하고 실행을 차단하거나 수정할 수 있습니다.
GitHub PR 리뷰 웹훅	선택적 모드로, PR이 리뷰 대기 상태가 되면 읽기 전용 리뷰 세션을 생성합니다.

설치 및 빠른 시작 (README에서)

# 소스에서 빌드 (Go 1.27+ 필요)
git clone https://github.com/smallnest/pigo.git
cd pigo
go build ./cmd/pigo   # ./pigo 생성
# 또는 $GOPATH/bin에 설치
go install ./cmd/pigo

또는 Linux/macOS용 원라인 스크립트로 사전 컴파일된 바이너리 가져오기:

curl -fsSL https://raw.githubusercontent.com/smallnest/pigo/master/install.sh | sh

LLM 인증 정보를 설정한 후 실행:

export OPENROUTER_API_KEY=sk-…   # 또는 다른 제공자 키
pigo -p "README를 읽고 3문장으로 요약해"   # 헤드리스 모드
pigo                                   # REPL 시작
pigo -m ollama/qwen2.5-coder -u http://localhost:11434/v1 -p "main.go가 무엇을 하는지 설명해"

작동 방식 (고수준 아키텍처)

CLI → 에이전트 루프 – 명령줄이 플래그를 파싱하고 에이전트 런타임을 시작합니다.
이중 루프 구조 – 내부 루프는 LLM 응답을 스트리밍하고, 도구 호출 여부를 결정하며, 도구를 실행하고 결과를 피드백합니다. 외부 루프는 후속 메시지를 확인하고 내부 루프를 재시작할 수 있습니다.
제공자 추상화 – 모델 ID는 히ュ리스틱을 사용해 구체적인 제공자(OpenRouter, Ollama 등)로 매핑되며, 제공자가 LLM 게이트웨이로의 HTTP 요청을 처리합니다.
도구 실행 및 신뢰 게이트 – 도구 실행 전 신뢰 시스템이 현재 디렉터리가 신뢰되는지, 도구가 화이트리스트/블랙리스트에 허용되는지 확인합니다.
세션 및 컨텍스트 처리 – 모든 턴이 저장되며, 토큰 창이 모델 제한에 가까워지면 컨텍스트가 자동 요약됩니다.
프롬프트 조립 – 시스템 프롬프트는 기본 프롬프트, 환경 정보, 선택적 AGENTS.md 파일, --append-system-prompt 인수로 구성됩니다.

pigo를 사용할 때

CI에서 자동 코드 수정 – 헤드리스 모드(-p)는 lint, 테스트 실행, 실패한 파일의 LLM 수정을 스크립트로 자동화할 수 있습니다.
로컬 개발 지원 – REPL은 리포지토리 읽기, 명령 실행, 변경 제안이 가능한 인터랙티브한 "파트너 프로그래머"를 제공합니다.
자체 호스팅 LLM – Ollama 또는 OpenAI 호환 엔드포인트와 함께 작동하므로 클라우드 API가 필요하지 않습니다.
확장 가능한 워크플로우 – 플러그인을 통해 커스텀 도구를 추가하거나 도메인 전용 작업용 재사용 가능한 프롬프트/스킬을 정의할 수 있습니다.

제한 사항 / 안전성 주의사항 (README에서)

부작용 도구는 디렉터리 신뢰 또는 명시적 --approve가 필요하며, 신뢰되지 않은 위치에서는 실행되지 않습니다.
도구 블랙리스트는 화이트리스트보다 우선하며, 블랙리스트로 차단된 도구는 --approve로 재정의할 수 없습니다.
훅은 현재 사용자로 실행되며 자격 증명을 받지 않지만, 실행을 차단할 수 있습니다.
에이전트는 병렬 안전하지 않음 – Session은 단일 고루틴에서 사용해야 합니다.

일반적인 플래그 요약

플래그	의미
`-p, --print`	헤드리스 모드용 프롬프트 (또는 위치 인수 사용).
`-m, --model`	모델 식별자 (기본값 `openrouter/free`).
`-u, --base-url`	제공자 URL 재정의 (예: 로컬 Ollama).
`-k, --api-key`	API 키를 직접 제공하여 환경/설정을 무시.
`-P, --protocol`	`openai` 또는 `anthropic` 프로토콜 강제.
`-o, --output-format`	`text` (기본값) 또는 `stream-json`.
`-n, --no-tools`	내장 도구 및 플러그인 탐색 비활성화.
`--allowed-tools` / `--disallowed-tools`	도구 사용용 화이트리스트/블랙리스트.
`-a, --approve`	이번 실행에서 현재 작업 디렉터리를 신뢰.
`--prompt-template`	추가 프롬프트 템플릿 파일 또는 디렉터리 로드.
`--system-prompt`	기본 시스템 프롬프트 완전 교체.
`--append-system-prompt`	시스템 프롬프트에 추가 텍스트 또는 파일 내용 추가.

SDK 예제 (README에서)

import (
    "log"
    "os"
    "github.com/smallnest/pigo/agent"
)

func main() {
    sess, err := agent.New(
        agent.WithModel("claude-opus-4-8"),
        agent.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
    )
    if err != nil { log.Fatal(err) }
    defer sess.Close()

    reply, err := sess.Prompt(context.Background(), "코딩 에이전트란 무엇인지 한 문장으로 설명해")
    if err != nil { log.Fatal(err) }
    fmt.Println(reply)
}

SDK는 CLI 기본값(도구 활성화, 요청 시 스킬/메모리 제외)을 반영하며, WithTools, WithoutTools, WithSkills 등으로 구성 가능합니다.

더 알아보기

문서 – 리포지토리의 docs/ 폴더에는 아키텍처 다이어그램과 REPL 흐름도가 포함되어 있습니다.
전자책 – "Go로 pi 에이전트 만들기" (write_pi_agent_in_go.pdf)는 ebooks 리포지토리에 포함되어 있습니다.
릴리스 – Linux/macOS/Windows용 사전 컴파일된 바이너리는 GitHub 릴리스 페이지에 있습니다.
이슈 및 커뮤니티 – README는 SDK 사용 이슈 #554에 링크되어 있으며, 프로젝트는 활발히 CI 테스트되고 있습니다.

TL;DR

pigo는 로컬 또는 클라우드 LLM에서 작동하는 Go 네이티브 명령줄 AI 코드 어시스턴트로, 풍부한 파일 시스템 및 쉘 도구를 제공하며, 스크립팅과 인터랙티브 REPL을 지원하며, 플러그인, 프롬프트 템플릿, Go SDK를 통해 확장 가능합니다.