Pegboard
Docs menu

Concepts

Stacks, scopes, targets, and the rules Pegboard follows when it touches your files.

Vocabulary

Term What it means Similar to
Stack A pegboard.yaml: the desired state of a scope Playbook, root module
Scope global (your user) or project (a directory) Inventory
Target One agent in one scope, such as Claude Code in this project Host
Provider The adapter that reads and writes one agent’s files Module, provider
Resource An MCP, a skill, or a context rule Resource, task
State The record of what Pegboard wrote to each target terraform.tfstate
Lock The exact versions and hashes that were resolved .terraform.lock.hcl

Scopes

There are two stacks, and they’re never merged:

  • Global: ~/.config/pegboard/pegboard.yaml applies to your user config, such as ~/.claude.json.
  • Project: ./pegboard.yaml applies to project config, such as .mcp.json.

Agents already read their global config alongside the project one, so copying global entries into each project would duplicate them. Without --scope, plan and apply work on every scope that has a pegboard.yaml. Setting inherit: none in a project stack excludes the global scope.

How Pegboard treats your files

  1. Deterministic work is code. An agent may run pegboard, but the translation itself never goes through an LLM.
  2. It never overwrites what isn’t its own. Pegboard only touches the keys, files, and links it created, as recorded in state.
  3. It shows you first. Every change goes through a readable plan.
  4. It’s idempotent. A second apply changes nothing.
  5. Secrets don’t live in the YAML. Stacks hold references only.
  6. The truth is in readable files. Everything can be versioned with git.
  7. It pulls, it doesn’t push. Pegboard configures the machine it runs on. Moving config between machines is a job for git, CI, Ansible, or an MDM.

How each format is edited

Pegboard rewrites only the part of the file holding MCPs:

Format What happens
JSON The MCP container’s value is replaced. The rest of the file stays byte for byte.
TOML Each MCP’s section is replaced in place, and comments remain. An MCP written as an inline table is reported as a conflict.
YAML Comments are preserved, but indentation is normalized to 2 spaces.

What Pegboard doesn’t do

  • Install the agents themselves
  • Push config to remote machines
  • Manage models, provider API keys, permissions, or agent hooks
  • Act as a registry or marketplace for MCPs and skills
  • Write the contents of your AGENTS.md, which stays yours