pigo
A Go implementation of the pi coding agent that reads and edits code, runs commands, and closes the loop from requirement to fixed code via LLMs.
Credits: side-effect tools (bash/write/edit) require per-action confirmation, three-state project trust persistence, --approve does not amplify privileges, fail-closed blacklist precedence, sub-agents inherit boundaries, hook payloads exclude credentials, project-level hooks load only for trusted dirs (fail-closed against clone-and-run). Deductions: all claims are README self-description with no code/test evidence shown in this review; SDK mode defaults to --approve-equivalent auto-execution of tools, weakening least-privilege defaults; no checksum/signing story for self-update or the curl|sh installer (dependency_security 1); attribution rests solely on an unverified publisher (source_attribution 1); bash grants arbitrary shell access and /rewind does not roll back bash changes.
Credits: two-layer loop with a single finish() exit path, exit code 2 for misspelled tool names, well-specified hook exit-code semantics with fail-open/fail-closed distinction. Deductions: no executed verification possible statically; go.mod pins Go 1.27rc1 (a release candidate) and a future-dated dependency (charmbracelet/ultraviolet, 2026-07), an availability/reproducibility risk (dependency_availability 1).
Credits: serves terminal users, headless/CI scripts, and SDK embedding; multiple providers incl. local Ollama; tool boundary docs are thorough including explicitly unsupported syntax. Deductions: heuristic model-id inference may misroute; Windows handling is only a manual-download note.
Credits: complete table of contents, three install paths, abundant examples, full MIT LICENSE text, consistent naming with pi/Claude Code semantics called out. Deductions: no CHANGELOG file in evidence; concrete released versions not shown (v0.2.0 appears only as example); maintenance responsibility evidenced only by CI/release workflows, no governance statement.
Credits: stream- for programmatic consumption, precise tool gating, ebook plus SDK examples ease onboarding. Deductions: npm-based package path and pi-ecosystem coupling raise learning cost; real utility requires execution to confirm.
Credits: README names concrete implementation files (internal/runtime/loop.go, prompt.go, registry.go), explicitly separates supported from unsupported behavior, and states fail-open/fail-closed semantics precisely. Deductions: no third-party corroboration and self-described runtime behavior cannot be cross-verified in static review (cross_source_corroboration 1).
- Trust gates, fail-closed blacklist, and other security claims are README self-descriptions, unverified against source/tests in this review; audit code before adoption.
- SDK embedding defaults to --approve-equivalent auto-execution of tools; embedders must narrow scope explicitly via WithDisallowedTools/WithoutTools.
- Installer is a curl|sh pattern and self-update replaces the binary in place with no documented signature/checksum verification — supply-chain risk is on the user.
- /rewind does not restore files changed by bash; destructive shell edits may be unrecoverable.
- go.mod pins Go 1.27rc1 (a release candidate) and a future-dated indirect dependency, questioning build reproducibility.
- Hooks run arbitrary shell commands with the user's full privileges; project-level hooks are trust-gated, but global/environment configs still warrant manual review.
What does this agent do, and when should you use it?
pigo (github.com/smallnest/pigo) is a Go reimplementation of the pi AI Agent, offering both a headless `-p` script mode and an interactive TUI/REPL. Its runtime core is the two-layer agent loop in `internal/runtime/loop.go`: the inner turn loop repeatedly streams replies and executes tools, the outer layer consumes follow-up messages, and all termination paths converge on a single `finish()` exit. It ships built-in tools such as read/write/edit/grep/find/bash/todo/webfetch/websearch/memory_search/task, with side-effect tools gated by a project-trust mechanism and `--allowed-tools`/`--disallowed-tools` tool-level admission. The provider layer supports OpenRouter (default), Anthropic, local Ollama, NVIDIA NIM, and 40+ built-in providers, with inference from model-name prefixes. Beyond the CLI, it exposes a `github.com/smallnest/pigo/agent` SDK for embedding in Go programs, accompanied by an ebook, "Write a pi Agent in Go".
pigo runs rooted at the current working directory: given a prompt it enters the agent loop, calls the LLM through the selected provider, and lets the model invoke built-in tools (read for line-numbered file reads, write/edit for file changes returning diffs, grep/find for code search, bash with background execution plus bash_output/kill_bash, webfetch for URLs, task for sub-agents). The system prompt is layered: base instructions + environment block + AGENTS.md files (general to specific) + --append-system-prompt. Output is plain text or line-delimited JSON events via --output-format stream- (the first event carries session_id). It supports session resumption (--resume/--continue), /slash skills from ~/.agents/skills, external plugins in ~/.pigo/plugins, nine lifecycle hook types in config. (e.g., PreToolUse blocking, UserPromptSubmit context injection), pigo install npm:<pkg> package management, and self-updating via bare pigo update.
- Go developers using
pigo -pheadless mode in CI/scripts to summarize repos, run tests, and fix failing cases - Users preferring local inference running offline code explanation with
-m ollama/qwen2.5-coder -u http://localhost:11434/v1 - Teams embedding a coding agent in their own Go services via the
agent.New(...)SDK andsess.Prompt - Risk-conscious developers restricting to read-only analysis with
--allowed-tools read,grepor blocking shell with--disallowed-tools bash - Teams codifying reusable prompts as Skills (
/skill-name) and automating behavior with Hooks (e.g., gofmt after writes, blockingrm -rf) - Users of Anthropic, DeepSeek, DashScope, Volcengine, and other providers switching via the
<PROVIDER>_API_KEYconvention
What are this agent's strengths and limitations?
- Single Go binary with no Node/Python runtime dependency; deployable via install.sh or prebuilt Release archives
- Very broad provider coverage: OpenRouter by default plus a 40+ provider registry (Anthropic, DeepSeek, DashScope, Volcengine, local Ollama), with model-name prefix inference
- Fine-grained safety boundaries: three-state persistent project trust, tool allow/deny lists (deny-list wins, sub-agents inherit,
--approvecannot bypass), and Hooks for blocking dangerous commands - Works as CLI/REPL and as an importable Go SDK (the
pigo/agentpackage uses only basic types), with a companion ebook explaining the implementation - Full extensibility: Skills, prompt templates with argument syntax, external plugins, nine lifecycle hook types, npm ecosystem package management, and self-update
- Source builds require Go 1.27+, a relatively new toolchain threshold
- Side-effect tools (bash/write/edit) rely on project trust;
--approveskips per-action confirmations, which is risky in untrusted directories - Tool admission does not support argument-level matching (Claude Code syntax like
Bash(git log:*)errors as unknown tools) pigo installrequires npm on PATH, and the package ecosystem only supports npm: sources- Compared to mature products like Claude Code,
/rewinddoes not yet restore files changed by bash, so parity gaps remain
How do you install or deploy this agent?
Requires Go 1.27+. Build from source:
git clone https://github.com/smallnest/pigo.git
cd pigo
go build ./cmd/pigo # or: go install ./cmd/pigoOne-line install script (Linux/macOS):
curl -fsSL https://raw.githubusercontent.com/smallnest/pigo/master/install.sh | shOverride defaults with PIGO_VERSION and PIGO_INSTALL_DIR. Prebuilt archives for Linux/macOS/Windows on amd64/arm64 are available on GitHub Releases (built with goreleaser). On Windows, download and extract the .zip manually.
How do you use this agent?
- Set a provider key:
export OPENROUTER_API_KEY=sk-or-...(orANTHROPIC_API_KEY, etc.). - Headless mode:
pigo -p "Summarize the README in three sentences"; a positional argument is equivalent to-p. - Interactive REPL: run
pigo(auto-enters when stdout is a terminal), with slash commands like/model,/compact,/rewind,/status. - Pick a model:
pigo -m anthropic/claude-3.5-sonnet -p "Review foo.go for concurrency safety"; local model:pigo -m ollama/qwen2.5-coder -u http://localhost:11434/v1 -p "...". - Tool boundaries:
pigo --allowed-tools read,grep -p "..."; grant one-shot trust:pigo -a -p "Run go test ./... and fix failures". - SDK embedding:
import "github.com/smallnest/pigo/agent", thensess, _ := agent.New(agent.WithModel("claude-opus-4-8"), agent.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")))andsess.Prompt(ctx, "..."). Runnable examples are inexamples/sdk/.
How does this agent compare with similar options?
The README positions pigo explicitly as a Go reimplementation of pi (pi.dev), and it benchmarks features against Claude Code in tool admission, /rewind, prompt templates, and Hooks; if you are already invested in Claude Code, its argument-level tool permissions (e.g., `Bash(git log:*)) are a capability pigo currently lacks.
FAQ
Do I need a paid model service?
<PROVIDER>_API_KEY.How do I stop it from running dangerous shell commands?
--disallowed-tools bash removes it from the model's toolset entirely (deny-list wins, sub-agents inherit, --approve cannot bypass); and PreToolUse hooks can block specific commands via exit code 2.Can I embed it in my own Go program?
github.com/smallnest/pigo/agent is the officially supported SDK layer with only basic exported types; by default all tools are enabled and auto-executed (equivalent to --approve), constrained via WithTools/WithDisallowedTools/WithoutTools. Seven runnable examples live in examples/sdk/.Can sessions be resumed after interruption?
~/.pigo/sessions; pigo --list-sessions lists them, and pigo --resume <id> or pigo --continue resumes, in both headless and REPL modes. Context is auto-compacted near the window limit, or manually via /compact.How do I upgrade to a new version?
pigo update with no arguments to self-update the binary to the latest GitHub Release; entering the TUI also checks asynchronously (24h cache) and shows a banner when a new version exists. Note that pigo update <pkg> with a package name updates installed npm packages instead; routing is argument-based.