Connections

A connection is one link between Pepper and something outside it, like Beeper or the Telegram bot. Each one that's built has a secret, the token or saved sign-in that lets Pepper in, and a health status. A source is a connection Pepper reads messages from, like Beeper and Tactiq.

Telegram talks to you, and most of the others only read. Pepper never sends as you: the two planned senders in the table will send as Pepper, and only with your OK.

Every built connection is in one of five states. The dashboard (Pepper's web pages), npm run doctor (the setup check) and npm run status use the same words. The morning brief only mentions a problem, and says when one needs you. Planned connections have no state yet.

For a connection whose secret you set up by hand, npm run pepper -- connect <name> tells you where the secret lives and how to replace it. <name> is the connection's short name, for example beeper or tactiq.

The Connections tab (Connect on a phone) lists every built connection with its state, and the planned ones under Planned. Tap a connection to open its page: the fix when it needs you, with a Copy button; what it may do and what it feeds (follow-ups, briefs, Ask, people); how much it has stored; where its secret lives; and the last 20 times its outcome changed, kept for 90 days. Sources have Sync now, Pause and Resume. Pepper doesn't sync a paused source until you resume it, and keeps what it already stored. Doctor still checks the service, and if you turned on the meeting excerpts tool in Ask, it still gets excerpts from Tactiq. Routines are Pepper's scheduled jobs. The ones that send something outside the Mac running Pepper are listed at the bottom.

Some services give you a token to paste into .env, Pepper's settings file. Others need you to sign in through a browser, and then Pepper renews the sign-in by itself. For those there is one command:

npm run pepper -- connect <name>

It prints a sign-in link and waits up to 10 minutes. When you've signed in, it saves the sign-in in data/connections/<name>.json, a file only you can read, never part of the repo. Running it again replaces a sign-in that stopped working.

When the browser isn't on the Mac. Pepper usually runs on a Mac you reach over SSH. After you sign in on your laptop, the service sends your browser back to 127.0.0.1:8977, which points at the laptop, not the Mac. The following command forwards the sign-in response from your laptop to the Mac running Pepper. Run this on the laptop, in a second terminal, before opening the link:

ssh -N -L 8977:127.0.0.1:8977 you@your-mac

npm run pepper -- connect <name> prints this line with your Mac's name filled in. Close the SSH connection once the sign-in is done.

Removing a sign-in: npm run pepper -- connect <name> --remove. There is no button for this on the dashboard, on purpose. On a phone, one wrong tap would delete a sign-in and cause an outage.

Some services replace the saved sign-in every time Pepper renews it, and the old copy stops working. Two Macs with the same copy break each other's sign-in. So when you move Pepper:

1. Stop Pepper on the old Mac.
2. Copy the data folder and .env to the new Mac, as the install guide says.
3. Never start Pepper again on the old Mac with the same data/connections/ files.
4. Run npm run doctor on the new Mac. It checks each sign-in it can read and renews it if it is close to expiring. A connection that is switched off, or whose file it can't read, is listed as off and skipped. The check can pass without testing whether the sign-in can be renewed.

If a sign-in still fails after the move, sign in again on the new Mac.

For whoever writes the code. Every new connection needs:

1. One registerConnection call next to its code, with a docs field pointing at its page here.
2. A page in this folder, listed in meta.json and in the table above.
3. If it feeds tasks, an extraction test, named in EXTRACTION_TESTS in test/connections.test.ts.

test/connections.test.ts fails when the page or the test is missing.