MichaelKinsy/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.

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.

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.

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:

• Pi source
• Pi documentation
• Earendil Works
• Pi community

PiG is not an official Pi release. The Pi maintainers do not endorse PiG.

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.

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.

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

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

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

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.

• .upstream/current/ is the local source-language mirror.
• Go code is the target implementation.
• docs/parity/PORT_MAP.md maps tracked upstream files.
• test/parity/scenarios/ records observed behavior.
• test/parity/coverage.md reports generated verification status.
• docs/parity/DIVERGENCES.md records intentional differences.
• AGENTS.md defines maintenance rules.
• Makefile defines build, test, parity, and release gates.

A ported row means that code exists. It does not prove behavioral compatibility. A non-deferred scenario must exercise and assert the mapped behavior.

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:

• Extension authoring
• Extension API parity
• Extension runtime cells

Use pig extension init <directory> to scaffold an extension. Use pig install <path> --validate-only --json to validate it.

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.

• Read .github/CONTRIBUTING.md before proposing a change.
• Read .github/SECURITY.md before reporting a vulnerability.
• Read .github/SUPPORT.md before requesting support.
• Read docs/project/GOVERNANCE.md and docs/project/MAINTAINERS.md for project ownership.
• Read LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md for licensing and attribution.

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.