PiG
PiG is Pi, the minimal and extensible coding agent for the terminal, rebuilt in Go as one native binary. It starts quickly, needs no Node.js, and runs Pi's TypeScript extensions unchanged. You can also write extensions in Go, Rust, or Python, and bundle extensions, skills, and prompts into a Piglet: one named agent you can share or build into its own executable.
PiG is a pre-stable 0.x release. Core paths are ported and checked against Pi 1.0.3 with paired parity scenarios; edge cases are still hardening. See the port status and file map for current scope and evidence.
If PiG behaves differently from Pi, that is either a bug or a documented divergence. Windows support is a preview.
Install
On macOS, Linux, or Android with Termux (arm64):
curl -fsSL https://pi-in-go.dev/install.sh | sh
On Windows, in PowerShell:
irm https://pi-in-go.dev/install.ps1 | iex
With npm, on any supported platform:
npm install -g @pi-in-go/pig
With Go:
go install github.com/MichaelKinsy/PiG/cmd/pig@latest
You can also download an archive from GitHub Releases or build from source. pi-in-go.dev/install covers every method, including updates and uninstalling.
Quick start
Start PiG in the directory where you want it to work, run /login to connect a subscription or set your provider's API key (for example OPENAI_API_KEY), then ask it something:
cd /path/to/project
pig
Interactive /login masks secret input by default. Turn off Mask secret input in /settings to restore Pi's plain-text typing and submitted input (D80). See login privacy.
The documentation covers everything else, starting with the quickstart. You can also ask PiG to explain itself.
Upstream Pi
Pi is the reference implementation. PiG follows Pi's behavior and design unless a Go constraint or an approved product-neutral requirement makes a difference necessary.
Use the upstream project for Pi itself:
PiG is not an official Pi release. The Pi maintainers do not endorse PiG.
Origins
Michael Kinsy created PiG working at Hewlett Packard Enterprise.
PiG is maintained as an independent open-source project. Project decisions, issues, and contributions belong in this repository. See docs/project/GOVERNANCE.md and docs/project/MAINTAINERS.md.
Compatibility philosophy
PiG adds a Go implementation to the Pi ecosystem and follows the Pi reference implementation.
- Preserve observable compatibility with Pi.
- Treat the pinned Pi release as the reference behavior.
- Minimize unnecessary divergence.
- Record each intentional user-visible or interoperability difference.
- Prefer changes that reduce the cost of the next upstream sync.
- Share generally useful findings with the broader ecosystem when the contribution route permits it.
The pinned Pi release is 0.99.1 at commit d86654abb8862e201933517d6f1fce9f88dd117f. The pin names the behavior oracle. It does not claim that every upstream change is already ported: test/parity/coverage.md reports verified behavior, and the upgrade ledgers under test/parity/upstream-sync/ list each upstream change and its disposition.
PiG's current package scope covers Pi's agent, AI, coding-agent, and TUI
packages. It does not implement Pi's experimental remote Session packages or
its standalone telemetry and evaluation packages. See
docs/parity/PORT_MAP.md for the exact boundary.
Project facts
- Binary:
pig
- Go module:
github.com/MichaelKinsy/PiG
- Configuration root:
~/.pig/, or PIG_HOME
- Agent directory:
~/.pig/agent, or PIG_CODING_AGENT_DIR
- Pi version pin:
internal/coding/pigversion/pigversion.go
- Local upstream mirror:
.upstream/current/
- Main verification gate:
make check
- Full verification and coverage refresh:
make verify
pig --version prints PiG's version as <PiG release>+<Pi release>, for example 0.3.0+0.99.1 (D63): the Pi release is semver build metadata, so the version sorts as the PiG release. pig version prints the PiG release and the pinned Pi release as separate fields. Neither command reads user configuration.
Repository map
| Path |
Responsibility |
agent/ |
Pi-compatible Agent loop, messages, and harness Session state. |
ai/ |
Pi-compatible providers, model catalog, authentication, and streaming types. |
coding/ |
Public coding-agent SDK, extension contracts, Package support, and Piglet support. |
tui/ |
Public terminal components, rendering, input, and terminal lifecycle. |
cmd/pig/ |
Stock PiG command-line application and RPC process surface. |
internal/ |
Private implementation used by Stock PiG. External modules cannot import it. |
extensions/ |
Go, Rust, Python, and declaration-only TypeScript extension SDKs. |
piglets/ |
Explicit agent compositions such as PiG Standard and Pig Porter. |
test/parity/ |
Pinned Pi correspondence, scenarios, inventories, and generated evidence. |
test/ |
Integration, extension-conformance, clean-repository, and upstream-contract tests. |
docs/ |
Maintainer references and the static public documentation site. |
examples/ |
Small extension and embedding examples. |
automation/ |
Build, generation, CI, release, layout, and maintainer tooling. |
PiG aligns public package boundaries with Pi's agent, ai, coding-agent,
and tui packages. Go files within a package follow cohesive implementation
responsibilities instead of mirroring TypeScript file mechanics. docs/parity/PORT_MAP.md
records every source correspondence.
Stock PiG and compositions
Stock PiG is the product-neutral binary built from this repository. It does not
activate PiG Standard Resources, product authentication, product APIs, or
deployment-specific behavior.
A Piglet explicitly selects Resources, tools, discovery, defaults, and environment requirements for one agent. A Package distributes Resources. A Package never owns or activates a Piglet. A Piglet Binary is a direct executable build output for one pinned Piglet composition.
PiG Standard is the explicit Piglet at
piglets/standard/pig-standard.yaml.
It currently selects the extension-provided PiG login, sprite catalogue, and
PiG Runner. Run it from source with:
pig --piglet piglets/standard/pig-standard.yaml
Stock PiG never selects this composition implicitly. A Package can distribute
its Resources, but a Package cannot own or activate the Piglet.
See CONTEXT.md and docs/README.md for the project terms and documentation map.
Security boundary
PiG runs with the permissions of the user who starts it. PiG does not provide a security sandbox for model output, tools, extensions, skills, hooks, or shell commands.
Use a container, virtual machine, or another operating-system boundary when you need isolation. Load extensions and project instructions only from sources you trust. See .github/SECURITY.md.
Install with npm
Install the command with npm (Node.js 18 or newer):
npm install -g @pi-in-go/pig
pig --version
Or run it once without installing:
npx @pi-in-go/pig --version
pig itself is the native binary: npm installs the matching platform package
(@pi-in-go/pig-<os>-<cpu>, for macOS, Linux and Windows on x64 and arm64, and Android on arm64 for Termux) as
an optional dependency, and Node.js runs only a small launcher. Do not install
with --omit=optional or --no-optional, which leaves the binary out. Update
with npm update -g @pi-in-go/pig and uninstall with
npm uninstall -g @pi-in-go/pig. pig update does not replace an
npm-installed binary; update through npm.
Install with Go
Install the command without a source checkout with Go 1.26 or newer:
go install github.com/MichaelKinsy/PiG/cmd/pig@latest
Go writes the pig executable to GOBIN, or to the bin directory of the first
GOPATH entry when GOBIN is unset: $(go env GOPATH)/bin, which is
~/go/bin by default (%USERPROFILE%\go\bin on Windows). Add that directory to
PATH. With an older Go 1.21 or later and the default GOTOOLCHAIN=auto, Go
downloads a new enough toolchain automatically. Release binaries are built with
Go 1.27.2.
Use an exact release such as @v0.2.0 when reproducibility matters. Update a Go
installation by running go install again. Each release tags the root module
(v0.2.0) and the Go extension SDK module (extensions/sdk/v0.2.0) on the same
commit; go install needs both.
Build from source
PiG currently supports source builds on Linux, macOS, and Windows. Do not treat a platform as release-supported until its native release verification passes.
Requirements:
- Go 1.27.2
- Git
- macOS 13 or later for native macOS builds
- Node.js 24.19.0 and npm 12.1.0 for parity tooling
- Python 3.12 for Python SDK tests
- Rust 1.97.1 for Rust SDK tests
- tmux for terminal parity tests on Unix
Build the binary:
go build -o bin/pig ./cmd/pig
./bin/pig --version
Prepare the exact Pi comparator and source mirror:
make upstream-mirror
Run the main local gate:
make check
The upstream-mirror target installs the lockfile-pinned Pi package. It retrieves the exact tagged Pi source and verifies its commit against internal/coding/pigversion/pigversion.go.
Contract model
A ported row means that code exists. It does not prove behavioral compatibility. A non-deferred scenario must exercise and assert the mapped behavior.
Extensions
PiG supports Go, Rust, Python, and Node extension factories through its public extension host. Extensions can register tools, commands, event handlers, flags, shortcuts, providers, and user-interface contributions.
Node extensions use Pi's TypeScript extension API. PiG supplies compatible
runtime modules. The declaration-only package in extensions/sdk-ts adds types
for PiG-only extension capabilities without replacing Pi's TypeScript runtime.
Start with:
Use pig extension init <directory> to scaffold an extension. Use pig install <path> --validate-only --json to validate it.
Supply-chain evidence
PiG treats scanner output as evidence input, not as proof by itself. Release preparation builds a validated dependency inventory and artifact-specific SPDX SBOMs. Reviewers reconcile scanner findings with Go modules, npm locks, Python metadata, Rust locks, embedded assets, generated data, and release contents.
See docs/supply-chain.md for the inventory, SBOM, vulnerability, license, signing, and provenance requirements.
Project policies
Acknowledgements
PiG would not exist without Pi and the work of its maintainers and contributors. Their design and open-source work provide the reference that PiG follows.
Thank you to everyone who contributes to Pi and PiG. Maintainers are listed in docs/project/MAINTAINERS.md, every contributor appears on GitHub's contributors page, and the changelog credits each fix to the person who reported or contributed it.
Star History
PiG is a Go port of Pi, the minimal terminal coding agent originally written in TypeScript, rebuilt as a single native binary that starts quickly and needs no Node.js.