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.
- Source repo
- smallnest/pigo
- Stars
- ★ 482
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Go
- FA score
- 68/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Go developers using
pigo -pheadless mode in CI/scripts to summarize repos, run tests, and fix failing cases - Not a fit if
- Environments still on Go 1.26 or earlier: source builds require Go 1.27+
- Users needing argument-level tool rules like Bash(git log:*): that syntax errors as an unknown tool
- Source review
- 68/100 · Some gaps
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-json (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.json (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
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/.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| pigo This agent | 68 · Some gaps | CLIFree + model costs | ★ 482 | 1mo ago | Go | OpenAI API · Claude API |
| Cersei — Rust SDK for Coding Agents | 60 · Some gaps | Library / SDKFree + model costs | ★ 461 | 2mo ago | Rust | OpenAI API · Claude API |
| zot Coding Agent | 59 · Major gaps | CLIFree + model costs | ★ 351 | 1d ago | Go | OpenAI API · Claude API |
| OpenClaude — Universal Terminal AI Coding Agent | 42 · Major gaps | CLIFree + model costs | ★ 34k | today | TypeScript | Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Changelog Features * 59ce2e9e03aab18ba9b41852e64aa3b23c92e381: feat: GitHub ready-for-review webhook creates read-only review sessions (#567) (#575) (@smallnest) * 4a0994dd6a14c0954b8cbdd02da498f439a09157: feat: credential reference mode and child-process env scrubbing (#568) (#576) (@smallnest) * c11a675e2c12cd6d225a1591b8b7ea05038bc550: feat: online model discovery via /models fetch (#566) (#574) (@smallnest) * 3a5808c21980471827602734213b61361c0c2444: feat: session export and sharing (pigo session export) (#570) (#578) (@smallnest) …View on GitHub ↗ -
Release notes excerpt
Changelog Features * 9554dcbd7d580bb70cce787607adb2e7e78249e3: feat(agent): add public SDK package + examples (#554) ( <>) * 662dd2fe2334e4323ca40fd8c5d437f1f628d757: feat(agent): expose structured events and custom tools (#563) (@zyhdf5) * d496ce91df6cd470bea91304e52e51cec1f79382: feat(edit): render colored diff for edit tool results (#560) (@smallnest) * e5b6cd19f416b148937e40f936dcece4144f87a9: feat(provider): add Fable 5 / GLM-5.3 / DeepSeek Flash presets (@smallnest) * 3df6a9cdbb71d23d30605f127b998041c06049a2: feat(provider): add Google Gemini preset section (@smallnest) …View on GitHub ↗ -
Release notes excerpt
Changelog Features * d9b7dc9022212d86dafad5262a34cd1d925f0755: feat(bash): add run_in_background with bash_output/kill_bash (@smallnest) * 7aab29011f7fd8aede31b7acb98412b1978477d0: feat(rewind): add /rewind edit checkpoint (files + conversation) (@smallnest) * 5be6400980c98367cf976d82e5bbf1d8dc1714e0: feat(thinking): add "max" reasoning level above xhigh (@smallnest) * 84c9c507cb92f0fbf4a59d6b0930332ddedb0399: feat(tools): add websearch tool with auto-detected backend (@smallnest)View on GitHub ↗
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.