pi-go

Go libraries and a CLI for calling language models and building single-agent applications. pi-go reimplements the core semantics of Pi AI, with a shared model/message API, streaming, tool calls, reasoning content, and cross-provider replay.

The provider layer (pkg/pigo) and agent runtime (agent) are separate. MCP connections, JavaScript tools, persistent sessions, and skill catalogs are optional packages.

Install · Quick start · CLI · Packages · Examples · Documentation

Install

Requires Go 1.26.2 or newer.

Add the library to an existing Go module:

go get github.com/Icatme/pi-go@latest

Install the CLI:

go install github.com/Icatme/pi-go/cmd/pigo@latest
pigo --help

agent and the optional packages ship in the same module; no separate installation is needed.

Quick start

Set a provider credential, then save the following as main.go in your Go module:

$env:KIMI_API_KEY = "your-api-key"

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/Icatme/pi-go/pkg/pigo"
)

func main() {
	apiKey := os.Getenv("KIMI_API_KEY")
	if apiKey == "" {
		log.Fatal("set KIMI_API_KEY")
	}
	model := pigo.GetModel("kimi-coding", "kimi-k2-thinking")
	if model == nil {
		log.Fatal("model not found")
	}

	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	result := pigo.CompleteSimple(*model, pigo.Context{
		SystemPrompt: "You are a concise coding assistant.",
		Messages: []pigo.Message{
			pigo.UserMessage{Content: "Explain Go interfaces in three sentences."},
		},
	}, pigo.SimpleStreamOptions{
		APIKey:         apiKey,
		RequestContext: ctx,
	})
	if result.StopReason == pigo.StopReasonError || result.StopReason == pigo.StopReasonAborted {
		log.Fatal(result.ErrorMessage)
	}
	for _, block := range result.Content {
		if text, ok := block.(pigo.TextContent); ok {
			fmt.Println(text.Text)
		}
	}
}

Build and run it from PowerShell:

go build -o hello-pigo.exe .
.\hello-pigo.exe

For incremental output, use StreamSimple. See model calls and streaming for event handling, sampling options, and error diagnostics. To add a tool-execution loop, start with the agent guide.

CLI

The CLI supports login, model discovery, prompts, and account quota queries:

pigo login openai-codex
pigo models openai-codex
pigo ask --provider openai-codex --model gpt-5.5 "Explain this error message"

pigo login commandcode
pigo models commandcode
pigo quota commandcode
pigo quota --json commandcode

pigo list lists available login providers. CLI credentials are stored in .pigo/auth.json; library applications supply their own credentials through request options or auth configuration.

Primary providers are openai-codex, opencode-go, kimi-coding, commandcode, anthropic, deepseek, google, and mistral. See providers and authentication for routing, credential lookup, model discovery, and provider-specific behavior. See account quota queries for balance and usage-window semantics.

Packages

Package	Use it for
pkg/pigo	Model metadata, provider protocols, completions, streams, and message replay
agent	Single-agent loops, tool execution, steering, follow-ups, and snapshots
agent/session	Persistent conversation branches, replay, and compaction
mcp	Managed HTTP/stdio MCP connections, catalogs, and explicit OAuth
agent/toolset	Dynamic tool exposure, discovery, and trusted session restoration
codemode / agent/codemodetool	Bounded JavaScript execution with QuickJS WASM and an explicit tool allowlist
agent/skills	Trusted directory or embedded skill catalogs and bounded resource reads
agent/strictschema	Required/nullable tool declarations and optional-null normalization

agent depends on pkg/pigo; provider protocol code stays outside the agent loop. Applications own graph and multi-agent orchestration. The documentation index also covers checkpoints, runtime contracts, MCP tools, and resources.

Examples

Examples live in a separate Go module under examples/. Each guide includes its build and run commands.

Example	Demonstrates
switch-chat	Agent presets, session persistence, and reflection
mattermost-chatbot	A Mattermost application with built-in tools
mcp-codemode	A caller-owned MCP session and deterministic model using bounded JavaScript tools
mcp-managed	Managed MCP connections, JSONL sessions, compaction, and process restart

Development

From the repository root:

$env:GOWORK = "off"
$env:PIGO_LIVE_TEST = "0"
$env:PI_GO_AGENT_LIVE_TEST = "0"
$env:PI_GO_AGENT_EXAMPLE_LIVE = "0"
.\scripts\test.ps1
.\scripts\build.ps1 -SkipTest

The test script checks the root and examples modules independently. The build script creates bin/pigo.exe on Windows. See the development guide for focused tests, race checks, coverage, cross-builds, and live-test controls.

Documentation

• Documentation index — guides and package references
• Model calls and streaming — completion APIs, events, options, and diagnostics
• Providers and authentication — credentials, routing, and catalog behavior
• Account quota queries — balances, usage windows, and CLI output
• Release notes · Source tags · GitHub releases

License

MIT. The license retains the copyright notice for the original Pi AI code by Mario Zechner. Bundled QuickJS components retain their upstream license notices.