Payload Overlay - PairCoder Docs

PairCoder installs and updates files under .claude/ (hooks, agents, skills and commands). bpsai-pair payload overlay is the supported way to keep your own versions of those files so that bpsai-pair upgrade does not overwrite them.

Commands

Command	Description
`payload overlay init`	Create the `.claude/overlay/` scaffold for this project
`payload overlay approve <relpath>`	Approve the current upstream version of an overridden file

Opting in

An overlay only exists if you ask for one; upgrade never creates it. Run this from your project:

bash

bpsai-pair payload overlay init

The command can be run again safely. It only adds skeleton files that are missing and never overwrites anything already in .claude/overlay/.

Options

Flag	Required	Description
`--project-root`	No	Project root (default: the discovered PairCoder project root)

Approving an override

Each override records the upstream version it was based on. When PairCoder ships a new version of that file, an override is applied only after you approve the new baseline. Approve it with the file's path relative to the overlay:

bash

bpsai-pair payload overlay approve hooks/guard.py --approved-by your-name

Options

Flag or argument	Required	Description
`relpath`	Yes	Path of the overridden file, for example `hooks/guard.py`
`--approved-by`	Yes	Who is approving this baseline
`--project-root`	No	Project root (default: the discovered PairCoder project root)

What happens on upgrade

Area	Behavior
`agents/`, `skills/`, `commands/`	Your override is applied on top of the shipped files. If upstream changed since you approved, `upgrade` warns until you approve again
`hooks/`	Hooks are a security boundary. An override applies only after you approve its upstream baseline; otherwise `upgrade` restores the shipped file instead of warning and applying it

Check overrides between upgrades

bpsai-pair arch check-overrides reports overlay problems and upstream drift without running a full upgrade.