Tech stack
Pepper runs on one always-on Mac. Apart from calls to Claude, the model Pepper uses, nothing leaves that Mac unless you've connected a service that needs it.
| Piece | What it is for |
|---|---|
Node.js 24 + TypeScript (tsx) | Pepper itself: the background process, the command line, routines |
| SQLite (one file, with full-text search) | Messages, people, tasks, briefs. Pepper's memory notes are files in data/memory. npm run backup makes a copy you can restore on another Mac |
Claude via @anthropic-ai/sdk | Briefs (three a day), answers, extraction (finding follow-ups in messages), drafts (Opus 5.5 or Sonnet 5.5, chosen per task) |
| zod | Checks every structured model output before it's used |
| launchd LaunchAgents | Keeps Pepper and the phone line's helpers (adb and FreeSWITCH) running after login, and runs routines on their schedules |
| Piece | What it is for |
|---|---|
Telegram bot (grammy) | Briefs, questions, tasks, voice notes. Only talks to you |
| Dashboard (local web page) | Today view and routine status. Shows no credentials; keep secrets out of routine descriptions and status lines |
| Phone: see Giving Pepper a phone line | Talking to Pepper, and taking messages from callers. Calling people for you is planned |
| Piece | What it is for |
|---|---|
Beeper Desktop, the app that brings your chat apps into one place, through its local API (@beeper/desktop-api) with a read-only token | Telegram and Signal today (any network Beeper connects to) |
Routines (docs/ROUTINES.md) | Small scheduled jobs whose private details stay on your Mac, e.g. sending daycare photos to the family |
| Piece | What it is for |
|---|---|
Chatterbox Turbo (4-bit, mlx-audio) | Pepper's voice, in Telegram voice notes and phone calls, once PEPPER_TTS=chatterbox is set (phone setup does this) |
| parakeet-mlx | Speech-to-text for voice notes and calls, on the Mac. OpenAI is an option for everything but the phone passphrase |
| ffmpeg | Audio conversion |
macOS say | The voice until Chatterbox is set up, and the fallback if it fails. On a phone call, Pepper tells you when the fallback was used |
Pepper's calls go through a spare Android phone.
| Piece | Where | What it is for |
|---|---|---|
| FreeSWITCH | Mac | Small call server on your home network |
| adb (Android platform tools) | Mac | Sets up and supervises the phone over USB |
| Shizuku | Phone | Extra Android permissions without rooting |
| voice-sip-agent | Phone | Bridges cellular calls to the call server |
Details: Android bridge.
You can prepare the Mac now; the program that does the sending isn't part of Pepper yet.
| Piece | What it is for |
|---|---|
| A second macOS user + Messages + AppleScript | Will send from Pepper's own Apple account. See the setup |
/Users/Shared/pepper-outbox folder | Send requests pass between the two macOS users through this folder, with time limits and a regular signal that the sending helper is running |
Use these docs with an AI assistant
Connect your AI assistant to these docs and it can look things up while it walks you through installing and running Pepper. The connection uses MCP, the standard way an assistant plugs into an…
Themes
A theme changes the dashboard's colours. Everything else stays the same: the pixel titles, the thick outlines, the layout and the fonts are Pepper's design, described in the brand book. That keeps…