Make Pepper yours

An off-the-shelf chief of staff is never right for one person's life. So Pepper is a working starting point: you change it for your own week, usually by asking an AI like Claude Code or Codex, and you keep taking updates.

You don't need to read code. Open your AI in the Pepper folder and say what you want. It reads AGENTS.md, which tells it where each kind of change goes and what it must not touch.

Run these once, in the Pepper folder.

git remote rename origin upstream       # Pepper's own repository, for updates
git checkout -b mine                    # your changes live here

Your changes go in a part, a folder of your own in src/parts/, listed in src/parts/mine.ts. Updates change the rest, so what is inside your part doesn't conflict with them. When an update changes what a part may do, the release notes say so. The npm run fork-gate check tests whether a customised Pepper can take an update without conflicts or losing its own behaviour. Edit a core file instead, one of Pepper's own files outside src/parts/, and updates can conflict with your changes to that file.

Pepper ships with five parts of its own: search, coach, weekly, voice and phone. npm run pepper -- parts lists them, and npm run pepper -- parts off coach switches one off the next time Pepper starts, so restart Pepper afterwards: launchctl kickstart -k gui/$(id -u)/com.pepper.agent. Switching a part off keeps its data and settings.

To change what a shipped part does, don't edit it. Add your own part and switch the shipped one off. The only cost is that your version no longer receives fixes to the shipped part. The phone part is the exception: it opens a direct connection to the phone line, which only the shipped part may do, so change the phone part with its settings instead of copying it.

Each example below is a whole part you can copy, and Pepper's tests run every one, so they keep working. The brief is the summary Pepper sends you three times a day; Ask answers when you send Pepper a question.

• Change what Pepper decides: what leads the brief, what counts as a task
• Add a line to the brief, or rewrite it
• Add a page to the dashboard
• Give Ask a new tool
• Keep your own data in a table
• Add a source of messages

Run npm run backup. If something goes wrong, npm run backup -- list shows your backups, and npm run restore -- <name> puts one back, using its name from that list. A restore stops Pepper, sets the current data aside for 30 days, copies the backup in and tells you which code version it belongs with; start Pepper again with launchd/install.sh.

Run these from your mine branch. They save a backup, merge in the latest from upstream, reinstall and run the checks, then restart Pepper so it runs the update.

npm run backup
git fetch upstream && git merge upstream/main
npm install && npm run check
launchctl kickstart -k gui/$(id -u)/com.pepper.agent

Tasks are kept in the same table as follow-ups, inside Pepper's own data, so the code that runs them stays in the core. You decide what counts as a task and when Pepper nudges you: change what Pepper decides.