PiG concepts

PiG separates execution, capability distribution, and agent composition. This separation keeps Stock PiG small and prevents each agent application from becoming a new harness fork.

The short model is:

Packages distribute Resources. Piglets select and scope Resources. Piglet Binaries deliver a fixed Piglet as a native executable.

Stock PiG

Stock PiG is the product-neutral coding agent. It provides:

Pi-compatible agent behavior;
built-in coding tools;
the extension host;
Package installation;
Piglet loading and validation;
Piglet Binary construction and verification;
embedded offline documentation.

Stock PiG does not activate PiG Standard or another product composition. It has no marketplace and no derivative-harness behavior. Two PiG-only features ship in the Stock binary: the first-time setup dialog (D88) and the built-in pig-login extension, which holds the fifteen built-in sprites and registers /sprite (D2).

Resources

A Resource contributes one focused part of an agent application. PiG has nine kinds of Resource.

Resource	Purpose
Extension	Add executable tools, commands, events, providers, or UI behavior.
Skill	Add task instructions that the agent loads when needed.
Prompt	Add a reusable prompt or template.
Theme	Change terminal appearance.
Hook	Describe an event command.
MCP definition	Describe an external tool service.
Compatible agent declaration	Expose an agent that a compatible plugin root declares. See Packages.
Context input	Add standing instructions for the model, such as an `AGENTS.md` context file. See Configure PiG.
Agent environment	Define the environment required by the whole agent.

A Resource does not activate itself.

Packages distribute Resources

A Package is an optional distribution envelope. It can contain one or more Resources. Install a Package when you want to make its Resources available:

pig install ./my-package
pig install git:https://github.com/example/my-package.git

Package installation does not select a Piglet. A Package never owns or activates a Piglet.

See Packages.

Piglets define agent applications

A Piglet is one named whole-agent declaration. It can select:

extensions and skills;
built-in and extension tool scopes;
a system prompt;
a model preference;
ambient discovery policy;
secrets and environment requirements;
Binary build requirements;
built-in tools, commands, extensions, model APIs and features to strip (D92);
a Go frontend member that draws the interactive mode in a Piglet Binary (D91).

Run a Piglet from source:

pig --piglet ./agents/reviewer.yaml

A Piglet is the normal unit for an agent application. It keeps the application configuration explicit without creating a separate PiG fork or wrapper harness.

Publish a Piglet's source to npm with pig piglet publish <name> --to npm, and its signed Binaries to GitHub Releases with --to github. See Piglets and Publish a Package or Piglet.

Piglet Binaries deliver fixed applications

A Piglet Binary is a target-native PiG executable for one fixed Piglet composition:

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

A Binary is a delivery form of the same Piglet. It is not another configuration model.

Each executable component records two independent facts:

Axis	Values	Meaning
Realization	fused, subprocess, external	How the component runs.
Materialization	binary, release, `agentEnv`, external	Where its bytes or runtime come from.

See Piglet Binaries.

PiG Standard

PiG Standard is an explicitly selected Piglet. It demonstrates how a derivative PiG experience can use public extension and Piglet contracts without adding product behavior to Stock PiG.

The Standard source is:

piglets/standard/pig-standard.yaml

Its Binary requires every selected extension to be a fuse-compatible Go factory. The build fails if an extension would use a subprocess fallback. The current composition selects piglogin for identity, pigrunner for the PiG Runner game, angrypigs for the Angry Pigs game and bunruntime to install the Bun TypeScript runtime (see TypeScript runtimes).

Choose the correct unit

Need	Use
Add one executable capability	Extension
Share several Resources	Package
Define one complete agent application	Piglet
Hand off one native executable	Piglet Binary
Change PiG core behavior	Stock PiG change, only when the behavior is generic or required for Pi parity

Why this prevents harness sprawl

A conventional derivative harness often combines configuration, extension loading, branding, deployment, and application behavior in a new executable. Each new executable then owns a separate update path and can drift from its base agent.

PiG keeps these responsibilities separate:

Stock PiG
   |
   +-- Packages make Resources available
   |
   +-- Piglet selects one agent application
          |
          +-- run from source
          |
          +-- build as a Piglet Binary

This model gives each application a clear identity while keeping one compatible execution engine.

PiG Documentation