Quickstart

PiG is under active development. No public PiG release artifact is available yet. Use a source checkout until verified release artifacts are published.

Requirements

Build the pig executable with Go 1.27.1. Go 1.27 release binaries for macOS require macOS 13 or later.

The complete verification suite also uses:

Git;
Node.js 24.19.0 and npm 12.0.2;
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

The repository is not public yet. This command becomes usable after publication.

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

Install with Go after the first release

After PiG publishes its first Go module version, Go users can install the command without cloning the repository:

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

Go writes the executable to GOBIN. When GOBIN is empty, Go normally uses the bin directory below the first path in GOPATH. 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.

This installation path becomes available only after the public repository has a valid root module tag and the nested Go extension SDK has its corresponding module tag.

Start PiG

Run PiG in the project you want it to inspect:

cd /path/to/project
/path/to/PiG/bin/pig

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

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

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. See Piglet Binaries.

Add an extension

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.

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.

PiG Documentation