Quickstart

PiG is under active development. Install it on macOS or Linux with curl -fsSL https://pi-in-go.dev/install.sh | sh, on any supported platform with npm install -g @pi-in-go/pig or go install github.com/MichaelKinsy/PiG/cmd/pig@latest, or download an archive from GitHub Releases. Windows support is a preview. To build from source instead, follow the steps below. Pi 1.5.0 documents its own install routes in Pi's quickstart.

If you have not used a terminal before, start with Your first ten minutes. It explains each step.

Install with the install script

On macOS and Linux, the install script downloads the newest published release, checks it against the release's SHA256SUMS, and installs pig in ~/.local/bin:

curl -fsSL https://pi-in-go.dev/install.sh | sh
pig --version

When ~/.local/bin is not on PATH, the script prints the export PATH=... line to run. Install troubleshooting lists the script's options, for example PIG_VERSION to install a given release.

Requirements

You need these tools only to build PiG from source. Build the pig executable with Go 1.27.3. Go 1.27 release binaries for macOS require macOS 13 or later.

The complete verification suite also uses:

• Git;
• Node.js 24.22.1 and npm 12.1.0;
• Python 3.12;
• Rust 1.97.1;
• tmux on Unix.

You do not need every verification tool to run a previously built executable.

Build from source

Clone the repository and build PiG:

git clone https://github.com/MichaelKinsy/PiG.git
cd PiG
go build -o bin/pig ./cmd/pig
./bin/pig --version

Do not install PiG by running an upstream Pi npm command. The package @earendil-works/pi-coding-agent installs Pi, not PiG.

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) 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 or pig update, which runs npm install -g @pi-in-go/pig@<version> for the release it finds, and uninstall with npm uninstall -g @pi-in-go/pig.

Install with Go

Go 1.26 or newer installs the command without cloning the repository. Go downloads PiG's source and its dependencies and compiles them on your computer, which can take several minutes the first time:

go install github.com/MichaelKinsy/PiG/cmd/pig@latest

Use an exact version for a reproducible installation:

go install github.com/MichaelKinsy/PiG/cmd/pig@v0.5.0

Go writes the pig executable to GOBIN. When GOBIN is empty, Go uses the bin directory below the first path in GOPATH: $(go env GOPATH)/bin, which is ~/go/bin by default (%USERPROFILE%\go\bin on Windows). With an older Go 1.21 or later and the default GOTOOLCHAIN=auto, Go downloads a new enough toolchain automatically. Add that directory to PATH, then inspect the installed module identity:

pig version
go version -m "$(command -v pig)"

Update a Go installation by running go install again with a newer exact version or with @latest. PiG does not treat a Go-installed executable as a standalone release download, so pig update refuses to replace it without a matching installation receipt.

Explicit pig update version checks retry transient transport failures and transient HTTP statuses at most twice within one ten-second budget. Startup checks do not retry. Signature and manifest errors stop the update. Native standalone updates reject concurrent replacement of the same executable and hold the installation lock until receipt commit or rollback completes (D39). The <executable>.update.lock sidecar exists only while an update runs; the update removes it when it ends.

Each release tags the root module (v0.5.0) and the nested Go extension SDK module (extensions/sdk/v0.5.0) on the same commit; go install needs both.

Install with Nix

The flake builds PiG from source in the Nix sandbox, with every input pinned by flake.lock:

nix run github:MichaelKinsy/PiG -- --version
nix profile add github:MichaelKinsy/PiG

Nix before 2.30 and Lix spell the second command nix profile install.

On NixOS or with Home Manager, add the flake as an input and install inputs.pig.packages.${system}.default, or apply inputs.pig.overlays.default and install pkgs.pig.

The package wraps pig as Pi's flake does: fd, ripgrep, and the clipboard commands come first on PATH, and Node.js comes last so that npm is available for package installs. Extensions build and run as in any other installation, with the toolchains on your PATH and the SDKs PiG stages under ~/.pig. pig update does not replace a Nix installation; update the flake input instead. The flake is verified on x86_64-linux; the other systems evaluate but are not yet verified natively.

Start PiG

Run PiG in the folder of the project you want it to work on:

cd /path/to/project
pig

A source build is at bin/pig in the PiG checkout. Run it by its full path, for example /path/to/PiG/bin/pig, or add that folder to PATH.

PiG stores user state below ~/.pig. Use PIG_HOME only when you need an isolated configuration root.

On an interactive start in the default agent directory that holds no settings.json yet, which includes every fresh PIG_HOME, PiG shows a first-time setup screen: theme, sprite and usage-analytics choices. Esc skips it and saves nothing. A custom agent directory (PIG_CODING_AGENT_DIR) and print, JSON and RPC modes skip it (coding/cli/extensions.go:93-95). Pi 1.5 shows its screen (theme and usage-analytics choices) only when all of these hold (startup-ui.ts shouldRunFirstTimeSetup): the binary is Pi's own distribution (package @earendil-works/pi-coding-agent, app pi, config directory .pi), PI_EXPERIMENTAL=1 is set, PI_CODING_AGENT_DIR is not set, and ~/.pi/agent/settings.json does not exist yet. This is divergence D88. Change the theme later with /settings and the pig with /sprite. Your first ten minutes shows the screen.

Authenticate a provider

List login targets available in the current binary:

pig login --list

Start an available OAuth login:

pig login github-copilot

For an API-key provider, set the provider's documented environment variable:

export OPENAI_API_KEY=...
pig --model openai/gpt-4.1

Use pig --help and pig login --help as the authority for your binary.

Start a first session

Type a request and press Enter:

Summarize this repository and tell me how to run its checks.

Stock PiG gives the model its normal built-in coding tools unless the command line, settings, or an active Piglet narrows them.

Use print mode

Run one prompt without the interactive TUI:

pig -p "Summarize this repository"

Select a model explicitly when needed:

pig --model github-copilot/gpt-5-mini -p "Find the test entry points"

Run PiG Standard

PiG Standard is not part of bare Stock PiG startup. Select it explicitly from a source checkout:

pig --piglet piglets/standard/pig-standard.yaml

The current Standard composition provides its PiG login, /sprite, /runner, and /pig-runner through ordinary extension Resources.

Run your own Piglet

Validate and run one agent application:

pig piglet validate ./agents/reviewer.yaml
pig --piglet ./agents/reviewer.yaml

Register portable Piglet source when you want to invoke it by name:

pig piglet add ./agents/reviewer.yaml
pig --piglet reviewer

See Piglets.

Build a Piglet Binary

pig piglet build ./agents/reviewer.yaml \
  --format binary \
  --out ./pig-reviewer
./pig-reviewer

A Piglet Binary is a target-native executable for one fixed Piglet composition. It can still have explicit external requirements. The build needs Go, or Docker or Podman for the container builder. A pig that you built yourself also needs a PiG source checkout named by PIG_SOURCE_ROOT; a published release fetches its own source. See Piglet Binaries.

Add an extension

A Go extension needs the Go toolchain. pig setup shows whether go is found, and pig setup go installs it. Create and validate a Go factory:

pig extension init ./review --lang go
pig install ./review --validate-only --json

Run it for one session:

pig -e ./review

Use a Piglet when the extension belongs to a named agent application. Your first extension walks through each step.

Verify a source checkout

Prepare the exact Pi comparator and source mirror:

make upstream-mirror

Run the primary gate:

make check

Use the toolchain versions declared by the repository. A green build does not replace parity review, vulnerability review, artifact inventory, or release authorization.

Choose how to customize PiG

Start with the least powerful mechanism that meets your need. Move to the next rung only when the rung before it cannot do the task. The table shows where the files go and how to check each result.

Applied use cases and How PiG works explain the pieces. Concepts names the Resources a rung adds.

Next steps

• Using PiG
• PiG concepts
• Extensions
• Packages
• Piglets
• Build a derivative harness