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), 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.md instructions), 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)

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).

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.

Requirements

• Go 1.25+
• At least one LLM provider API key or a running Ollama instance

API keys

Set the API key for your provider as an environment variable. The provider is inferred from the model name, so --model is usually the only routing you need.

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."
export OPENCODE_API_KEY="..."
export OLLAMA_API_KEY="..."   # only for Ollama Cloud (:cloud suffix)

A name with no recognized prefix is rejected rather than guessed at — reach for the ollama/ prefix or the :cloud suffix to name an Ollama model explicitly.

Build

make build      # build the pi binary
make test       # run unit tests
make lint       # golangci-lint (vet, staticcheck, errcheck, …)
make e2e        # run E2E integration tests
make clean      # remove binary

Usage

# Default interactive mode
pi

# Select a model by prefix
pi --model claude:sonnet
pi --model openai:gpt-4o
pi --model gemini:gemini-2.5-pro
pi --model ollama/gemma4:12b-mlx
pi --model opencode/kimi-k3
pi --model minimax-m3:cloud # automatically detect ollama if :cloud

# Use model roles
pi --smol          # fast, cheap model
pi --slow          # most capable model
pi --plan          # planning-oriented model

# Additional options
pi --continue      # continue last session
pi --session <id>  # resume specific session
pi --system "..." # custom system instructions
pi --url "..."    # custom API endpoint URL

# Non-interactive modes
pi --mode print "explain this codebase"
pi --mode json "list all TODO comments"
pi --mode socket --socket /tmp/pi-go.sock  # JSON-RPC 2.0 over a Unix socket
pi --mode rpc                              # pi-compatible NDJSON over stdio (for pi-acp)

Slash commands

Memory Palace

A 4-layer contextual memory system that gives the agent persistent awareness across sessions.

Layers:

CLI commands:

# Setup
pi memory model download         # download all-MiniLM-L6-v2 embedding model
pi memory model status           # check model path and status
pi memory init [dir]             # create palace.db + generate mempalace.yaml

# Ingest
pi memory mine <dir>             # mine source files into drawers
pi memory mine --convos <dir>    # mine conversation files (JSONL/text)

# Query
pi memory status                 # palace overview (drawers, wings, rooms, KG)
pi memory search <query>         # semantic or keyword search
pi memory wake-up                # print L0+L1 context for system prompt
pi memory recent [project]       # recent memory observations

# Knowledge Graph
pi memory