smallnest/pigo

pigo – A Go‑based CLI coding assistant (pi‑style AI Agent)

What it is – pigo is an open‑source command‑line AI agent written in Go that mimics the functionality of the pi coding assistant. It can read/write files, run shell commands, fetch web pages, and invoke large language models (LLMs) to understand a request, modify code, and return the result. The tool works in two modes:

Headless (-p …) – a one‑shot prompt that prints the final answer (or streams JSON events).
Interactive REPL – a terminal UI where you can iteratively ask questions, run tools, and see the agent’s reasoning.

Key Features (as described in the README)

Feature	What it does
Two run modes	`-p` for single‑shot scripts/CI, or REPL for interactive use.
Multiple LLM providers	OpenRouter (default), local Ollama, NVIDIA NIM, Anthropic, any OpenAI‑compatible endpoint, etc.
Built‑in toolset	`read`, `write`, `edit`, `grep`, `find`, `bash` (with background execution), `todo`, `webfetch`, `websearch`, `memory_search`, `task` and more.
Session management	List, resume, or continue previous sessions; each session streams JSON with a `session_id`.
Tool‑level allow/deny	`--allowed-tools` (whitelist) and `--disallowed-tools` (blacklist) – blacklists win, and the lists are enforced before any tool is offered to the model.
Project trust	Filesystem directories start untrusted; side‑effect tools (`bash`, `write`, `edit`) require confirmation unless `--approve` is used.
Skills & plugins	Slash‑style commands (`/skill-name`) loaded from `~/.agents/skills`; external plugins can add more tools.
Prompt templates	Reusable Markdown prompt snippets (`/name` expands them) with positional‑parameter syntax (`$1`, `${1:-default}`, `$@`, etc.).
Context compression	Automatic summarisation when the token window is near its limit; manual `/compact` also available.
Self‑update	`pigo update` upgrades the binary to the latest GitHub release.
SDK	The core agent can be imported as `github.com/smallnest/pigo/agent` for embedding in other Go programs.
Hooks	Nine lifecycle hook points (e.g., `PreToolUse`, `UserPromptSubmit`) that run shell commands and can block or modify execution.
GitHub PR review webhook	Optional mode that creates a read‑only review session when a PR becomes ready for review.

Installation & Quick Start (from the README)

# Build from source (requires Go 1.27+)
git clone https://github.com/smallnest/pigo.git
cd pigo
go build ./cmd/pigo   # produces ./pigo
# or install to $GOPATH/bin
go install ./cmd/pigo

Or use the one‑liner script (Linux/macOS) to fetch a pre‑compiled binary:

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

Set your LLM credentials, then run:

export OPENROUTER_API_KEY=sk-…   # or any other provider key
pigo -p "读取 README 并用三句话总结"   # headless mode
pigo                                   # start REPL
pigo -m ollama/qwen2.5-coder -u http://localhost:11434/v1 -p "解释 main.go 做了什么"

How it works (high‑level architecture)

CLI → Agent loop – The command line parses flags and starts the agent runtime.
Two‑level turn loop – An inner loop streams LLM replies, decides whether a tool should be called, runs the tool, and feeds the result back. The outer loop checks for follow‑up messages and may restart the inner loop.
Provider abstraction – The model ID is mapped to a concrete provider (OpenRouter, Ollama, etc.) using heuristics; the provider handles the HTTP request to the LLM gateway.
Tool execution & trust gate – Before a tool runs, the trust system checks whether the current directory is trusted and whether the tool is allowed by the whitelist/blacklist.
Session & context handling – All turns are stored; when the token window approaches the model limit the context is automatically summarised.
Prompt assembly – System prompts are built from a base prompt, environment info, optional AGENTS.md files, and any --append-system-prompt arguments.

When to use pigo

Automated code fixes in CI – headless mode (-p) can be scripted to lint, run tests, and let the LLM edit failing files.
Local development assistance – REPL gives an interactive “pair‑programmer” that can read your repository, run commands, and suggest changes.
Self‑hosted LLMs – works with Ollama or any OpenAI‑compatible endpoint, so you don’t need a cloud API.
Extensible workflow – add custom tools via plugins or define reusable prompts/skills for domain‑specific tasks.

Limitations / safety notes (from the README)

Side‑effect tools require directory trust or explicit --approve; they will not run in untrusted locations.
Tool blacklists have priority over whitelists; a tool blocked by a blacklist cannot be overridden by --approve.
Hooks run as the current user and receive no credentials, but they can still block execution.
The agent is not concurrency‑safe – a Session should be used by a single goroutine.

Quick reference of common flags

Flag	Meaning
`-p, --print`	Prompt for headless mode (or use positional argument).
`-m, --model`	Model identifier (default `openrouter/free`).
`-u, --base-url`	Override provider URL (e.g., local Ollama).
`-k, --api-key`	Directly supply an API key, overriding env/config.
`-P, --protocol`	Force `openai` or `anthropic` protocol.
`-o, --output-format`	`text` (default) or `stream-json`.
`-n, --no-tools`	Disable all built‑in tools and plugin discovery.
`--allowed-tools` / `--disallowed-tools`	Whitelist / blacklist for tool usage.
`-a, --approve`	Trust the current working directory for this run.
`--prompt-template`	Load additional prompt‑template files or directories.
`--system-prompt`	Replace the default system prompt entirely.
`--append-system-prompt`	Append extra text or file contents to the system prompt.

SDK example (from the 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)
}

The SDK mirrors the CLI defaults (tools enabled, no skills/memory unless requested) and can be configured with WithTools, WithoutTools, WithSkills, etc.

Where to find more

Documentation – The repository’s docs/ folder contains architecture diagrams and the REPL flowchart.
Electronic book – “用 Go 编写 pi Agent” (write_pi_agent_in_go.pdf) is bundled in the ebooks repo.
Releases – Pre‑compiled binaries for Linux/macOS/Windows are on the GitHub Releases page.
Issues & community – The README links to issue #554 for SDK usage; the project is actively CI‑tested.

TL;DR

pigo is a Go‑native, command‑line AI coding assistant that can run locally or against cloud LLMs, offers a rich set of file‑system and shell tools, supports scripting and interactive REPL, and is extensible via plugins, prompt templates, and a Go SDK.