pi-go
A terminal-based coding agent built on Google ADK Go. It connects to multiple LLM providers, runs sandboxed tools, integrates LSP, and ships with a process-based subagent system.
Features
- Multi-provider LLM — Claude (Anthropic), GPT/O-series (OpenAI), Gemini (Google), Mistral, Grok (xAI), Azure OpenAI, OpenRouter, OpenCode, and Ollama (local or cloud) for models
- Sandboxed tools — read, write, edit, shell, grep, find, tree, and git operations. All tools are restricted to the project directory via
os.Root. - Interactive TUI — Bubble Tea v2 with Markdown rendering (Glamour), slash commands, and theming
- Session persistence — JSONL append-only event logs with branching, compaction, and resume
- Model roles — Named configurations (default, smol, slow, plan, commit) selectable via CLI flags
- Subagents — Process-based multi-agent system with types: explore, plan, designer, reviewer, task, quick_task
- LSP — JSON-RPC client for Go, TypeScript/JS, Python, and Rust, with auto-format and diagnostics hooks
- AI Git tools — Repository overview, file diffs, hunk parsing, and LLM-generated conventional commits (
/commit) - RPC server — Unix socket JSON-RPC 2.0 for IDE/editor integration
- Memory Palace — 4-layer contextual memory with SQLite storage, semantic embeddings (all-MiniLM-L6-v2), temporal knowledge graph, and project/conversation miners
- Extensions — Hooks (shell callbacks), skills (
.SKILL.mdinstructions), and Model Context Protocol (MCP) servers - Skills audit — Security scanning for hidden Unicode characters, BiDi attacks, and supply-chain threats in skill files (
pi audit)
Architecture
cmd/pi/ Entry point — CLI parsing, output mode selection
internal/
├── agent/ ADK agent setup, retry logic, runner
├── cli/ Cobra CLI flags, output modes (interactive, print, json, rpc)
├── config/ Global and project config (roles, hooks, MCP, themes)
├── audit/ Security scanner for skills (hidden Unicode, supply-chain threats)
├── extension/ Hooks, skills, MCP server integration
├── lsp/ LSP JSON-RPC client, language registry, manager, hooks
├── palace/ Memory Palace — drawers, layers, KG, miners, embedder, search
├── provider/ LLM providers implementing genai model interface
├── rpc/ Unix socket JSON-RPC 2.0 server
├── session/ JSONL persistence, branching, compaction
├── subagent/ Process spawner, orchestrator, concurrency pool
├── tools/ Sandboxed tools (read, write, edit, bash, grep, find, git, lsp)
└── tui/ Bubble Tea v2 UI, slash commands, commit workflow
Request flow
User input → CLI → Agent → LLM provider → Tool calls → Sandbox → Response → TUI
↕ ↕ ↕
Session store Palace LSP servers
(JSONL events) (memory, (format, diagnostics)
KG, search)
See ARCHITECTURE.md for detailed documentation.
Installation
Quick install (recommended)
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/dimetron/pi-go/main/scripts/install.sh | bash
This script detects your OS/arch, downloads the latest release binary, and installs it to /usr/local/bin (or ~/.local/bin if needed).
Windows
powershell -NoProfile -Command "iwr https://raw.githubusercontent.com/dimetron/pi-go/main/scripts/install.ps1 -UseBasicParsing | iex"
Or, from a checkout:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
Installs pi.exe to %LOCALAPPDATA%\Programs and adds that directory to your
user PATH. Restart the terminal afterwards so the new PATH is picked up.
Runs on Windows PowerShell 5.1 (built into Windows 10/11) and PowerShell 7+;
windows/amd64 only. Set GITHUB_TOKEN if you hit the GitHub API rate limit
while it resolves the latest release.
The installer checks the download against the release's checksums.txt and
refuses to install on a mismatch. That catches a corrupted or swapped archive,
but not a substituted release — checksums.txt travels the same path as the
archive. Run pi verify afterwards for the provenance check that does answer
that question — see Verifying a release.
Windows machines without bash.exe on PATH — a stock Windows install has
none — run agent commands through powershell.exe instead, so write PowerShell
syntax in prompts: ; or a newline rather than &&. Installing
Git for Windows puts a bash on PATH and
restores the bash behaviour.
NixOS / Nix
The repository includes a flake that builds pi-go reproducibly and exposes a
NixOS module. To install it in a NixOS configuration, add the repository as an
input:
# flake.nix
{
inputs.pi-go.url = "github:dimetron/pi-go";
outputs = { self, nixpkgs, pi-go, ... }: {
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
pi-go.nixosModules.default
];
};
};
}
Enable it in configuration.nix:
{ programs.pi-go.enable = true; }
Then rebuild with sudo nixos-rebuild switch --flake .. For a one-off use,
run nix run github:dimetron/pi-go or install it into a profile with
nix profile install github:dimetron/pi-go.
go install
go install github.com/dimetron/pi-go/cmd/pi@latest
Make sure your GOPATH/bin is in your PATH. The binary will be installed as pi.
Build from source
git clone https://github.com/dimetron/pi-go.git
cd pi-go
go install ./cmd/pi
Pre-built binaries
Download the latest release for your platform from the Releases page.
Verifying a release
pi verify checks the running binary against the attestations published for
it, with no other tooling required:
pi verify # the running binary
pi verify ./pi # a specific file
pi verify pi-go_1.2.3_linux_amd64.tar.gz # a downloaded archive, before extracting
pi verify --json # machine-readable
pi verify --sbom > sbom.spdx.json # print the attested SBOM document
/usr/local/bin/pi
sha256:abd70659b49183320320426af4abf34555b031e432aff27afbdbf1be39e1ecff
✓ build provenance
repository github.com/dimetron/pi-go
workflow .github/workflows/release.yml@refs/tags/v1.2.3
commit 4086645aa1f2c3d4e5f60718293a4b5c6d7e8f90
run https://github.com/dimetron/pi-go/actions/runs/1234/attempts/1
signer https://github.com/dimetron/pi-go/.github/workflows/release.yml@refs/tags/v1.2.3
signed 2026-08-21T12:00:00Z
✓ SBOM
format SPDX 2.3
packages 192
ecosystems golang 180, github 12
signer https://github.com/dimetron/pi-go/.github/workflows/release.yml@refs/tags/v1.2.3
signed 2026-08-21T12:00:00Z
The check starts from the file's SHA-256 and nothing else — the version compiled into the binary, the name it was installed under and the URL it came from are all attacker-controlled. That digest is looked up in GitHub's attestations API and the returned Sigstore bundles are verified against the public-good Sigstore trust root: certificate chain, Rekor transparency-log inclusion, signed certificate timestamp, and a certificate identity that must name this repository's release workflow, running on a tag. A signature from any other workflow, branch or repository is rejected.
A binary you built yourself has no attestation and reports as unverified. That is the expected answer, not a failure.
Verification needs network access. The Sigstore trust root is cached in
~/.pi-go/sigstore after the first run.
Verifying with the GitHub CLI
The same attestations are readable by gh, if you would rather not trust the
binary to vouch for itself:
gh attestation verify ./pi --repo dimetron/pi-go
# SBOM attestation. The predicate type carries the SPDX version syft emitted.
gh attestation verify ./pi --repo dimetron/pi-go \
--predicate-type https://spdx.dev/Document/v2.3
What is attested, and what is published
Both the release archives and the raw binaries inside them are attestation
subjects. scripts/install.sh extracts the binary and puts it on your PATH, so
the archive digest is not the digest you end up running; attesting only the
archive would leave the installed binary unverifiable. The binaries themselves
are not published as release assets — the digest is all verification needs.
Each release publishes SBOMs as assets, in SPDX JSON:
pi-go_<version>_<os>_<arch>.tar.gz.sbom.json— cataloged by syft from the contents of that specific archive.- `pi-go__sbom