pi-go

module

v0.78.0-go Latest Latest Go to latest Published: Jun 3, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/guanshan/pi-go

Links

Open Source Insights

README ¶

pi-go

Go implementation of the Pi coding agent CLI — a port of badlogic/pi-mono (TypeScript). Compatibility with the upstream project — behavior, on-disk session format, and tool semantics — is an explicit goal that is still being worked toward, not a finished guarantee; tracked parity status lives in docs/TS_COMPATIBILITY.md.

⚠️ Alpha — porting in progress. This is not yet a 1:1 replacement for the TypeScript CLI. Core agent loop, providers, tools, and non-interactive modes work, but several areas are still being ported (full interactive-UI parity, running .ts/.js extensions, some OAuth/transport edges). See docs/TS_COMPATIBILITY.md for the current gaps before relying on it as a drop-in replacement.

This port now mirrors the TypeScript monorepo package layout:

packages/ai: shared LLM types, model registry, env API keys, provider registry, text/image APIs
packages/agent: generic agent state, loop, events, queues, tools, and harness helpers
packages/tui: terminal primitives, input/key parsers, leaf components, fuzzy matching, autocomplete (no main renderer — the interactive UI uses Bubble Tea; see docs/TUI_DESIGN.md)
packages/coding-agent: CLI, session/runtime wrappers, coding tools, RPC/print helpers
examples/extensions: upstream-compatible extension examples and fixtures

The CLI keeps the TypeScript session format and command surface where practical:

CLI argument parsing compatible with pi [options] [@files...] [messages...]
print, JSON event stream, RPC, and lightweight interactive modes
JSONL session files with v3 tree entries
built-in tools: read, write, edit, bash, grep, find, ls
resource loading for AGENTS.md/CLAUDE.md, SYSTEM.md, prompt templates, skills, themes, and package metadata
OpenAI-compatible, Anthropic, Google, and faux test providers
package commands: install, remove, uninstall, list, update, config
HTML session export

Install

Pre-built binaries for Linux / macOS / Windows on amd64 + arm64 are attached to each GitHub Release.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/guanshan/pi-go/main/scripts/install.sh | bash

# Or with Go
go install github.com/guanshan/pi-go/cmd/pi@latest

Windows users: download the matching pi_*_Windows_*.zip from the Releases page and put pi.exe somewhere on your PATH.

Build

make build           # -> ./bin/pi with version metadata stamped in
# or:
go build -o pi ./cmd/pi

Run

go run ./cmd/pi --help
go run ./cmd/pi --model faux/faux -p "hello"
go run ./cmd/pi --mode json --model faux/faux "hello"
go run ./cmd/pi --mode rpc --model faux/faux --no-session

Package Imports

import (
    codingagent "github.com/guanshan/pi-go/packages/coding-agent"
    "github.com/guanshan/pi-go/packages/agent"
    "github.com/guanshan/pi-go/packages/ai"
    "github.com/guanshan/pi-go/packages/tui"
)

Test

make test               # go test -race ./... with coverage
./scripts/test.sh       # the full pre-PR gate
make check              # tidy + fmt-check + vet + lint + test
make arch-check         # verify package dependency boundaries

Contributing

See CONTRIBUTING.md for the development workflow, PR checklist, and parity guidelines.

License

MIT — see LICENSE. The upstream TypeScript work it ports from is also MIT; both copyright lines are preserved. Attribution to the upstream project is in NOTICE.

Compatibility Tracking

See docs/TS_COMPATIBILITY.md for the current package-by-package audit against the TypeScript source. See docs/ARCHITECTURE.md for the Go package boundaries.

Configuration

The Go port uses the same default config locations as the TypeScript CLI:

global: ~/.pi/agent/settings.json
project: .pi/settings.json
sessions: ~/.pi/agent/sessions/, or PI_CODING_AGENT_SESSION_DIR
agent dir: PI_CODING_AGENT_DIR, or ~/.pi/agent

API keys are read from provider environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, and the OpenAI-compatible provider variables listed in pi --help.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
pi command Command pi runs the Earendil coding agent CLI.	Command pi runs the Earendil coding agent CLI.
packages
agent Package agent contains the reusable agent loop kernel, event model, stream adapters, and stateful Agent wrapper.	Package agent contains the reusable agent loop kernel, event model, stream adapters, and stateful Agent wrapper.
agent/gitignore Package gitignore implements a small subset of git's ignore matching, shared by skill discovery and the find/grep tools so both honour .gitignore/.ignore rules consistently.	Package gitignore implements a small subset of git's ignore matching, shared by skill discovery and the find/grep tools so both honour .gitignore/.ignore rules consistently.
agent/harness Package harness provides persistent-session and resource helpers for the agent runtime.	Package harness provides persistent-session and resource helpers for the agent runtime.
agent/harness/compaction Package compaction prepares and summarizes session history for AgentHarness.	Package compaction prepares and summarizes session history for AgentHarness.
agent/harness/env Package harnessenv provides filesystem and shell abstractions for agent harnesses.	Package harnessenv provides filesystem and shell abstractions for agent harnesses.
agent/harness/session Package session provides session-tree storage for agent harnesses.	Package session provides session-tree storage for agent harnesses.
agent/harness/utils Package harnessutils provides shell-output and truncation helpers for agent harnesses.	Package harnessutils provides shell-output and truncation helpers for agent harnesses.
agent/messagequeue Package messagequeue implements the steering and follow-up message queues used by the agent loop.	Package messagequeue implements the steering and follow-up message queues used by the agent loop.
ai Package ai provides shared model metadata, provider registries, auth helpers, message types, completion helpers, image generation, and validation utilities.	Package ai provides shared model metadata, provider registries, auth helpers, message types, completion helpers, image generation, and validation utilities.
ai/filelock Package filelock provides a small cross-process advisory lock used to serialize writes to shared on-disk state (notably auth.json).	Package filelock provides a small cross-process advisory lock used to serialize writes to shared on-disk state (notably auth.json).
ai/imageresize Package imageresize shrinks inline images to fit the provider request-size limits, mirroring the upstream coding-agent image-resize behaviour with a stdlib-only implementation (PNG/JPEG/GIF decode, area-averaging downscale, PNG/JPEG re-encode).	Package imageresize shrinks inline images to fit the provider request-size limits, mirroring the upstream coding-agent image-resize behaviour with a stdlib-only implementation (PNG/JPEG/GIF decode, area-averaging downscale, PNG/JPEG re-encode).
ai/openaicodexauth Package openaicodexauth implements the OpenAI Codex device authorization helper flow used by the root ai OAuth provider.	Package openaicodexauth implements the OpenAI Codex device authorization helper flow used by the root ai OAuth provider.
ai/providers Package providers contains provider-specific implementation helpers.	Package providers contains provider-specific implementation helpers.
ai/providers/images Package imageproviders contains image-provider protocol helpers.	Package imageproviders contains image-provider protocol helpers.
ai/providers/openaichat Package openaichat contains OpenAI Chat streaming helpers.	Package openaichat contains OpenAI Chat streaming helpers.
ai/providers/openairesponses Package openairesponses contains OpenAI Responses streaming helpers.	Package openairesponses contains OpenAI Responses streaming helpers.
ai/utils Package utils contains reusable support code for the ai package.	Package utils contains reusable support code for the ai package.
ai/utils/oauth Package oauth contains reusable OAuth flow helpers for ai providers.	Package oauth contains reusable OAuth flow helpers for ai providers.
coding-agent Package codingagent provides the Go port of @earendil-works/pi-coding-agent.	Package codingagent provides the Go port of @earendil-works/pi-coding-agent.
coding-agent/cli Package cli parses command-line flags and formats CLI help text.	Package cli parses command-line flags and formats CLI help text.
coding-agent/core Package core owns the coding-agent runtime: settings, sessions, resources, modes, model selection, and built-in tool orchestration.	Package core owns the coding-agent runtime: settings, sessions, resources, modes, model selection, and built-in tool orchestration.
coding-agent/core/extensions Package extensions defines the runtime contract for coding-agent extensions: the event bus, lifecycle event types, tool and slash-command definitions, and the Runner that dispatches session events to registered extension handlers.	Package extensions defines the runtime contract for coding-agent extensions: the event bus, lifecycle event types, tool and slash-command definitions, and the Runner that dispatches session events to registered extension handlers.
coding-agent/core/tools Package tools implements the built-in coding tools used by the agent runtime.	Package tools implements the built-in coding tools used by the agent runtime.
coding-agent/utils Package cautils contains small coding-agent utilities that do not own session or runtime state.	Package cautils contains small coding-agent utilities that do not own session or runtime state.
tui Package tui provides the Go port of @earendil-works/pi-tui — a small set of terminal primitives, input parsers, and leaf components that pi-go shares with its TypeScript upstream.	Package tui provides the Go port of @earendil-works/pi-tui — a small set of terminal primitives, input parsers, and leaf components that pi-go shares with its TypeScript upstream.