smallnest/pigo

pigo – GoベースのCLIコードアシスタント（piスタイルAIエージェント）

何であるか – pigo は pi コードアシスタントの機能を模倣した、Goで書かれたオープンソースのコマンドラインAIエージェントです。ファイルの読み書き、シェルコマンドの実行、ウェブページの取得、大規模言語モデル（LLM）の呼び出しにより、リクエストの理解、コードの修正、結果の返却が可能です。このツールは2つのモードで動作します：

ヘッドレス (-p …) – 1回きりのプロンプトで最終的な回答を出力する（またはJSONイベントをストリーミング）。
インタラクティブREPL – ターミナルUIで、質問を繰り返し投げ、ツールを実行し、エージェントの推論を確認できます。

主な機能（READMEに記載）

機能	機能の説明
2つの実行モード	`-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レビューWebhook	オプションモードで、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 → エージェントループ – コマンドラインがフラグを解析し、エージェントランタイムを起動。
2段階のターンループ – 内側のループは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 は単一のgoroutineで使用すべき。

一般的なフラグのクイックリファレンス

フラグ	意味
`-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(), "1文でコーディングエージェントとは何かを説明して")
    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による拡張性も備える。