A Piglet is a named PiG configuration that you can share. It is one YAML file that picks the model, the tools, the extensions, the skills and the system prompt for one kind of agent. A reviewer that can only read, a researcher with web search, an editor agent for Zed, a PiG with a music player. Each of those is a Piglet, and none of them is a fork of PiG.
You can run a Piglet straight from its file, register it by name, build it into a launcher script or a signed single-file binary, and publish it to npm or GitHub so that other people can add it with one command.
The smallest useful Piglet
Save this as agents/reviewer.yaml.
name: reviewer
description: "Reviews a change and lists risks."
systemPrompt:
text: "You review changes. List the risks first, then the questions."
tools: [read, grep, find, ls]Check it, then look at what PiG will run.
pig piglet validate ./agents/reviewer.yaml
pig piglet show ./agents/reviewer.yamlOK: reviewer (./agents/reviewer.yaml): 0 extension(s), 0 skill(s)
Piglet: reviewer
Reviews a change and lists risks.
Source: ./agents/reviewer.yaml
Built-in tools: read, grep, find, ls
System prompt: You review changes. List the risks first, then the questions. (61 bytes)Run it with pig --piglet ./agents/reviewer.yaml. The reviewer can't write, edit or run commands, because tools is a ceiling. Its system prompt replaces PiG's, so the model sees your text and the working directory.
Every part of PiG is a slot
In 0.5.0 a Piglet can also change PiG itself. Each part a Piglet can change is a slot, and for each one the Piglet keeps PiG's own part, replaces it with a Go member of its own, or strips it. A stripped part is gone at run time, and in a Piglet binary its code is not compiled in at all.
This is how the pig-core build in the 0.5.0 demo drops tools like grep and comes out much smaller than stock PiG. It is also how pig-tern draws its own interactive screen on top of PiG through the frontend slot. The Piglets reference lists every ID you can strip.
The Piglet commands
Everything lives under pig piglet. These are the ones you will use most.
Command | What it does |
pig piglet validate <name or path> | Checks the file against the schema and resolves every origin. |
pig piglet show <name or path> | Prints the tools, prompt and changed slots PiG will use. |
pig piglet add <path, npm:ref or git:ref> | Registers a Piglet so you can run it by name. |
pig piglet list and pig piglet tree | List what is installed, flat or arranged by extends. |
pig piglet lineage <name, path or binary> | Shows an extends chain and what each link adds, removes or changes. |
pig piglet build <name> --format script or binary | Writes a launcher script or builds a Piglet binary. |
pig piglet keygen <key path> | Creates the ed25519 key pair that signs your binaries. |
pig piglet publish <name or path> --to npm or github | Publishes source to npm or signed binaries to a GitHub release. A dry run until you add --yes. |
pig piglet pull <release> | Installs a signed binary release from GitHub. |
pig piglet update <name> | Moves an installed binary to the newest release in its signed namespace. |
pig piglet verify <binary> | Checks a binary's signature and what it was built from, without running it. |
pig piglet schema | Prints every field a Piglet file accepts. |
pig status counts your Piglets next to your Packages and Resources, and /piglet inside a session shows which one is active.
Pigpen
Pigpen is the home for community Piglets and the components they use. Every Piglet in it is Go only, so it fuses into one binary with no Node. A few you can try today.
- pig-with-batteries is default PiG with curated extensions, including the herdr reporter and a few extra commands.
- pig-warden holds irreversible tool calls before they run and calls out stuck loops and unverified "done" claims.
- pig-games adds PiG Runner and Angry Pigs, starring the pig you picked with
/sprite. - pig-music opens a full-screen YouTube Music player that keeps playing while you work.
- acp lets an Agent Client Protocol editor such as Zed drive PiG.
- a2a calls remote Agent2Agent agents and can serve PiG tasks to them.
- jev adds a typed judge for tool calls and their output.
- pig-porter ports Pi TypeScript extensions to Go.
Add one from npm, or pull its signed binary from GitHub.
pig piglet add npm:@pi-in-go/pigpen-piglet-pig-music
pig piglet pull 'github:MichaelKinsy/pigpen/pig-warden@0.1.0'Every Piglet published to npm also shows up in the Piglet catalog. The how-to guides walk through building, sharing and updating your own.
Browse the Piglet catalog Piglet guides Pigpen on GitHub Piglets reference