piglet

A coding assistant that lives in your terminal.
Multi-provider, extension-first, built in Go.

Install · Extensions · Models · Getting Started · Write Your Own

What It Does

Piglet is a terminal-native coding assistant. It reads your files, runs commands, edits code in place, and persists sessions across days. No copy-pasting, no browser, no IDE plugin.

$ piglet
> refactor the auth middleware to use errgroup

  Reading cmd/server/middleware.go...
  Editing cmd/server/middleware.go...
  Running go build ./...
  Running go test ./cmd/server/...

  Done. Replaced sequential error handling with errgroup.
  3 files changed, tests passing.

One-shot mode for quick questions:

piglet "what does this function do"
piglet "find everywhere we call the payments API"

Install

Requires Go 1.26+.

go install github.com/dotcommander/piglet/cmd/piglet@latest

Verify: piglet --version

Set an API key and run it. First launch auto-detects your keys, picks a default model, and writes config to ~/.config/piglet/.

export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, GOOGLE_API_KEY, etc.
piglet

If no API key is set, piglet tells you exactly which environment variables to set and still writes its config files so you're ready once you add a key.

Extensions

First launch automatically builds and installs the official extensions (memory, skills, LSP, safeguard, and more). You'll see per-extension progress on stderr — it takes a minute or two, then you're fully loaded.

To rebuild extensions later (e.g. after an update), run /update inside piglet.

Build from Source

git clone https://github.com/dotcommander/piglet
cd piglet
go build -o piglet ./cmd/piglet/

First Things to Try

piglet                          # interactive mode — ask anything
piglet "explain this repo"      # one-shot from any project directory

Inside a session:

How It Works

Piglet is an agent loop: you send a message, the LLM responds with text or tool calls, piglet executes the tools, feeds results back, and repeats until the LLM is done. Streaming output appears as it's generated.

Built-in tools: read, write, edit, bash, grep, find, ls — everything the LLM needs to navigate and modify a codebase.

Extensions add everything else: project memory that persists across sessions, on-demand skill loading, LSP-powered code intelligence, repository structure maps, dangerous command blocking, clipboard image pasting, sub-agent delegation, and structured task planning. Extensions are standalone binaries that communicate via JSON-RPC — write them in Go, TypeScript, or Python.

Architecture

core/       Agent loop, streaming, types. Imports nothing from piglet.
ext/        Registration surface (ext.App) — the central API.
tool/       7 built-in tools (read, write, edit, bash, grep, find, ls).
command/    14 slash commands, 2 keyboard shortcuts, 6 status sections.
prompt/     System prompt builder + 2 prompt sections.
provider/   OpenAI, Anthropic, Google streaming providers.
shell/      Agent lifecycle — submit, events, notifications (frontend-agnostic).
tui/        Bubble Tea v2 terminal UI (consumes shell/).
sdk/        Go Extension SDK — standalone module (github.com/dotcommander/piglet/sdk).

Everything is an extension. The core agent loop knows nothing about files, git, or code — tools and extensions provide all capabilities through a single registration API (ext.App). The architecture test enforces dependency boundaries at build time.

Models

Switch mid-session with Ctrl+P or /model. No restart needed.

Any OpenAI-compatible endpoint works via base URL override in config.

Use just the model ID (gpt-5) or the full form (openai/gpt-5). Override with PIGLET_DEFAULT_MODEL or defaultModel in config. Run /model to see all available models.

Piglet writes models.yaml to ~/.config/piglet/ on first run with the current model catalog. To refresh after a piglet upgrade, delete the file and restart — it regenerates automatically.

Commands and Shortcuts

Extensions

Piglet's extension system is the same API used by its own built-in tools. Extensions register through five primitives:

Extension Packs

Piglet works without any extensions — the core agent has built-in tools, commands, and providers. Extensions add everything beyond the baseline.

Official extensions ship as consolidated packs (fewer processes, faster startup). Install with piglet-extensions:

What You Need

Not all packs are required. Here's what matters:

Skip optional packs by setting disabled_extensions in config.yaml:

disabled_extensions:
  - pack-core
  - pack-workflow

Write Your Own

Scaffold a new extension:

/ext-init my-extension

Or build one from scratch in Go, TypeScript, or Python. Extensions communicate via JSON-RPC over stdin/stdout — no linking, no shared memory, any language works.

See docs/building-extensions.md for the SDK reference and examples.

Configuration

Everything lives in ~/.config/piglet/:

# config.yaml
defaultModel: claude-opus-4-6
smallModel: claude-haiku-4-5-20251001   # for background tasks
agent:
  maxTurns: 10
  maxMessages: 200
  toolConcurrency: 10

Auth supports environment variable references and shell commands:

{
  "anthropic": "$ANTHROPIC_API_KEY",
  "openai": "sk-...",
  "google": "!op read op://vault/google/key"
}

Prompt templates in prompts/ register as slash commands — prompts/review.md becomes /review:

---
description: Review code for issues
---
Review the following for bugs and style problems:

$@

See docs/configuration.md for the full settings reference.

License

MIT