Making your repo pier-ready

Pier uses one committed .pier/ directory with three optional files:

File	Runs / read	Contains
.pier/setup.sh	Every session’s first boot, async, in a setup tmux window	Repo state: deps, services, migrations, seeds
.pier/include	At create	Untracked/ignored files to carry (env files, local certs)
.pier/bake.sh	Once, during pier bake	Toolchains beyond the default image (pnpm, python, rust, …)

Do not ignore .pier/: it is shared project configuration. Loose local files listed in .pier/include, such as .env, should remain in .gitignore.

Upgrading from the old root files

Pier v0.6 no longer reads .pier-setup.sh, .pier-include, or .pier-bake.sh. Move whichever files your repo uses into the committed directory:

mkdir -p .pier
git mv .pier-setup.sh .pier/setup.sh
git mv .pier-include .pier/include
git mv .pier-bake.sh .pier/bake.sh

Do not add .pier/ to .gitignore during the move.

.pier/setup.sh

# .pier/setup.sh (cwd is the repo root, logs to ~/.pier-setup.log)
set -euo pipefail
pnpm install
docker compose up -d
pnpm db:migrate

Prefer docker compose up -d for services. A bare background process must fully detach with setsid cmd </dev/null >log 2>&1 & or it dies when the setup window closes.

Setup cannot fail silently. It runs after the checkout, dirty patch, and .pier/include files are in place, and the outcome always surfaces:

• pier ls and the TUI show (setup running) or (setup failed)
• pier logs <session> prints the log from anywhere, no attach needed (-f follows, l in the TUI)
• ~/.pier-setup.log ends with pier setup: done or pier setup: FAILED (exit N)
• a failed window renames to setup-failed and stays open instead of vanishing

Set PIER_SETUP_SCRIPT to run a different script for one create.

.pier/include

# .pier/include: one path or glob per line (no **), a directory carries its subtree
.env
apps/*/.env.local

A file symlink matched directly by a line or glob is dereferenced: its target contents arrive as a regular file at the symlink’s repository path. Directory symlinks are never followed.

.pier/bake.sh

# .pier/bake.sh (agent user, passwordless sudo, NO repo checkout yet)
set -euo pipefail
sudo corepack enable
echo COREPACK_ENABLE_DOWNLOAD_PROMPT=0 | sudo tee -a /etc/environment >/dev/null
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack install -g pnpm@10.6.5

See Bake for when and why to bake.

The pier-onboard skill

Don’t write those files by hand. The pier repo ships skills/pier-onboard, a skill that teaches a coding agent to inspect your repo, write all three files with the right boundaries, and keep loose local files protected by .gitignore.

cp -r pier/skills/pier-onboard ~/.claude/skills/    # or your repo's .claude/skills/

Then ask your agent to “set this repo up for pier”.