Quick start: Pegboard docs

Create a stack

From a project directory, create a pegboard.yaml with the agents Pegboard detects:

pegboard init

If your agents already have MCPs configured, you can bring them in instead of starting empty:

pegboard import

import replaces any plain-text secrets it finds with ${env:…} references, so export those variables before you apply.

Declare what you want

Edit pegboard.yaml:

version: 1
agents: [claude-code, codex, opencode]

mcps:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${env:GITHUB_TOKEN}"
  notion:
    url: https://mcp.notion.com/mcp
    agents: [claude-code]

context:
  agents_md: true

Review the plan

plan shows what would change and writes nothing:

$ pegboard plan
claude-code · project
  + mcp github                       (.mcp.json)
  + mcp notion                       (.mcp.json)
codex · project
  + mcp github                       (.codex/config.toml)
opencode · project
  + mcp github                       (opencode.json)
agents.md · project
  + context AGENTS.md                (AGENTS.md)
claude-code · project
  + context @AGENTS.md in CLAUDE.md  (CLAUDE.md)
Plan: 6 create, 0 update, 0 remove, 0 conflicts.

Each line starts with what will happen to that resource:

Symbol	Meaning
`+`	Create
`~`	Update
`-`	Remove
`=`	Adopt: it already matches, so Pegboard only records it
`!`	Conflict: see resolve a conflict

Apply it

pegboard apply

apply asks for confirmation unless you pass -y. Running plan again now confirms that nothing is left to do:

$ pegboard plan
No changes: every tool is in its silhouette.

Check for drift

If someone edits a managed file by hand, drift reports it:

$ pegboard drift --exit-code
Managed by pegboard:
  claude-code · project  mcp github  ok (.mcp.json)
  claude-code · project  mcp notion  edited manually (.mcp.json)
  codex · project  mcp github  ok (.codex/config.toml)
  opencode · project  mcp github  ok (opencode.json)
Drift: 1 entry.

With --exit-code, the command exits with 2 when it finds drift, which makes it useful in CI.

Resolve a conflict

A hand-edited entry shows up in the plan as a conflict, and apply stops:

$ pegboard apply -y
claude-code · project
  ! mcp notion  edited manually since the last apply
Plan: 0 create, 0 update, 0 remove, 1 conflict.
error: there are conflicts: resolve them manually or use --force

To keep the edit, copy it into pegboard.yaml. To discard it, overwrite the file. Pegboard saves a backup first:

pegboard apply --force

Quick start