Hey Pepper docs
Pepper is a personal chief of staff on a Mac you control. It reads the chats you connect, keeps track of the follow-ups you owe people and the ones they owe you, writes you a brief three times a day, and talks to you on Telegram and by phone. It never writes to the chats it reads. Its Telegram bot talks only to you, and by phone it takes messages from other callers; what it drafts, you send.
These pages are for setting Pepper up and running it.
Engineering plans live elsewhere, in docs/handoff/, with the research behind them in
docs/research/.
| Guide | What it covers |
|---|---|
| Install Pepper | The one-line install and the guided setup, or the same steps by hand: Node, Beeper, the Telegram bot, the Anthropic key, the prompts macOS shows, first run, every optional part, and moving to another Mac |
| How Pepper keeps your data safe | What Pepper can and cannot do, where your data goes, who can get in, what to never do, and the known limits |
| Use these docs with an AI assistant | Connect Claude, Cursor or another assistant over MCP, the standard way an assistant plugs into outside pages and tools, so it can walk you through setup |
| Tech stack | Every piece Pepper uses and where it runs |
| Guide | What it covers |
|---|---|
| What Pepper does | What it reads, what it keeps track of, how it talks to you, and what it never does |
| Your first week | The first run, saying hello on Telegram, the first brief, teaching Pepper who people are |
| Telegram commands | Commands, messages, replies, voice notes, photos and buttons |
| Guide | What it covers |
|---|---|
| Briefs | The three daily briefs: when they arrive, what is in them, how to change them |
| Follow-ups | What you owe and what you're owed, how Pepper finds them, how a follow-up closes |
| People | How Pepper learns who someone is, VIPs, what it stores and refuses to store, forgetting |
| Schedule | Things with a date on them, and what's coming up |
| Review | Confirming or dismissing what Pepper picked up, with undo |
| Ask | Asking Pepper questions on Telegram, in the dashboard and by phone, and what it can search |
| Dashboard | Opening it, the tabs, the Ask bar, phone layout |
| Routines | Scheduled jobs with private details kept on your Mac |
| Themes | Dashboard colours and dark mode |
| Guide | What it covers |
|---|---|
| Connections | What Pepper is connected to, signing in, moving to another Mac |
| Beeper chats | Your chat apps through Beeper Desktop, read only |
| Tactiq meetings | Meeting transcripts from Tactiq: follow-ups, Ask, briefs |
| Telegram | The bot Pepper talks to you through, and replacing its token |
| Phone line | Where the phone line's secrets are stored, and how to check it's working |
| Pepper's iMessage | Sending from Pepper's own Apple account (planned) |
| Gmail and Google Calendar | Planned: reading your email and calendar |
| Guide | What it covers |
|---|---|
| Giving Pepper a phone line | All the options compared, phone plans, carrier terms, costs |
| Android bridge | Recommended. A spare Android phone with your SIM, plugged into the Mac: step by step, with screenshots |
| Talking to Pepper by phone | What you, your contacts and strangers hear when they call; your spoken passphrase; what's kept from a call |
| Guide | What it covers |
|---|---|
| Setting up the Mac that runs Pepper | Never sleep, restart after a power cut, FileVault, updates, remote access |
| A second user for Pepper's own iMessage | Planned: preparing Pepper's own Apple account, the folder outgoing messages pass through, keeping both users logged in |
| Guide | What it covers |
|---|---|
| Writing a routine | The rules for a program of your own: its files, what it reports, what Pepper watches |
| Make it yours | Change Pepper to fit your life, with an AI, and keep getting updates |
| Making a theme | How a theme file works, and making your own |
| Troubleshooting | Symptom, cause and fix, grouped by area |
| Frequently asked questions | Privacy, cost, which chats, stopping Pepper, deleting data, and more |
- Write for someone setting Pepper up for the first time: what to do, in order, and what they'll see.
- Steps only a person can do (security settings, purchases, signing in) are marked as you. Pepper never does them.
- No private details: no real names, phone numbers, addresses, account IDs or passwords, including in screenshots.
- Screenshots go in
images/<section>/, at most about 1000 px tall, with alt text. - When something breaks during a real setup, add it to that guide's troubleshooting table.
Docs site. These files are also the docs section of the Pepper website, built straight from this folder.
The first # heading on each page becomes its title, and the sidebar order is in the meta.json files. Keep pages plain
GitHub Markdown. How to run the site and add a page: website/README.md.