Making your repo pier-ready

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

File	Runs / read	Contains
.pier/setup.sh	Once at pier bake (prebuild), then once per new session, async, in a setup tmux window	Repo state: deps, services, migrations, seeds (must be safe to re-run)
.pier/include	At create	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

Setup runs once per session, when the session is built: a pooled session ran it before you claimed it, and a parked session never runs it again. Waking a parked session brings back its tmux windows and agent conversations, and restarts the Docker containers that were running when it parked, so the stack comes back without setup.

On a baked repo, setup re-runs on a disk that already holds the prebuilt checkout and everything the bake’s setup left around it, so it must stay safe to re-run on a warm disk.

Prefer docker compose up -d for services. A server started in the background (cmd >log 2>&1 &) keeps running after the setup window closes, but only containers come back when a parked session wakes.

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

• pier ls and the app show (setup running) or (setup failed)
• pier logs <session> prints the log from anywhere, no attach needed (-f follows, l in the app)
• ~/.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. pier 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.

pier setup installs it with the rest of the defaults, for every agent on the machine. Claude Code (~/.claude/skills) and Codex (~/.codex/skills) read the same skill format. pier setup --skills refreshes it without the other questions, e.g. after a pier upgrade. To pin it to one repo instead, copy it into that repo’s .claude/skills/.

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