Phone, voice and devices

The phone app, other computers and servers, and talking to Pimpo.

On the phone#

In Settings › Open on your phone, turn on one or both ways in:
- At home: the phone reaches Pimpo over your Wi-Fi. No account, nothing to install, and it stops working when you leave home.
- From anywhere: Tailscale runs inside Pimpo. The first time, sign in to Tailscale (free) in the browser; Pimpo then gets an https://pimpo.<your-network>.ts.net link that works from anywhere. If Tailscale says Funnel or HTTPS is off, turn them on in its admin console as the message explains.
- Already expose Pimpo another way? Paste the address under Use another address.
Name the phone and tap Generate code. With both ways on, the phone uses the home address when it can and the other one elsewhere.
Scan the QR code with the Pimpo app, or paste the link.
Lost the phone? Tap the trash icon next to it. Only that phone loses access.

The phone as part of Pimpo#

Open Phone on the paired phone and choose what it shares: location (arriving at and leaving your places), camera (photos for routines) and shortcuts. Only the phone itself turns these on, and the phone asks for its own permission the first time.

Places. Save one where you stand (Save where I am), with a 150 m radius, or by name only. While Pimpo is open on the phone it notices arriving and leaving, at most once a minute; the position itself is never kept. For arriving with Pimpo closed, make a key for automations and add an automation in iOS Shortcuts or Tasker ("When I arrive home" → Get contents of URL, POST to /api/phone/arrived with Authorization: Bearer <key> and {"place": "Home"}). The key only reports events; it cannot open Pimpo.
Photos. Take a photo sends a photo of a bill, a receipt or a document; the text is read on your computer (Tesseract) and the photo stays there, under phone/photos/.
Routines. Ask for them as usual: "when I get home, tell me what's on tomorrow's calendar", "when I photograph a bill, remind me two days before it's due". They watch phone.arrivals, phone.photos or phone.shortcuts and run as soon as the phone reports, with the same rules, approvals and receipts as any other routine.

A Pimpo on another computer or server#

Locking the desktop app. The desktop app opens as the administrator without asking. To keep it behind your fingerprint or face, turn on Lock with Touch ID or Windows Hello in the Pimpo menu in the menu bar (or the system tray on Windows). It asks once to confirm, then again when the app opens and after its window has been closed for five minutes; on a Mac without Touch ID it asks for your password. The floating Pimpo and floating widgets wait for the unlock too, and close when the app locks again. Linux has no such check, so the item is off there. On Windows the app opens Pimpo at localhost, so you can also add a passkey there in Account; on a Mac, add one from a browser at http://localhost:7788.

Pimpo can run on a machine that is always on (a home server, a VPS) while the desktop app just opens it. On that machine, generate a link in Settings › Open on your phone as for a phone. On your computer, click the Pimpo icon in the menu bar, choose Connect to another Pimpo… and paste the link. The Pimpo on your computer then stops, so the same Telegram bot and the same routines never run twice; its data stays where it was. Use this computer's Pimpo in the same menu brings it back. While connected elsewhere, notifications come from that Pimpo's channels (Telegram and others), not from this computer.

Audio#

A routine or task can read a text aloud and send it to you as audio (audio.send): a podcast of the day's news, a briefing to hear on the way. The voice is your Mac's own, in the language you choose (Portuguese, English, Spanish, French and the other languages macOS has), so the text never leaves the computer; for better voices, add Premium or Enhanced ones in System Settings › Accessibility › Spoken Content and Pimpo picks them. With a voice downloaded in Settings › Models › Download models (Kokoro, natural voices in Portuguese, English, Spanish, French and Italian, or a Piper voice per language), Pimpo reads with it instead, still on this computer; Listen plays a sample in each language. Settings › Models › Voice for audio sets the default voice for routines and, apart, for Listen in the chat: automatic (a downloaded voice, else the system's), a downloaded voice, the system voice, the browser's own (chat only, instant), OpenAI (tts-1 or tts-1-hd with your OpenAI key, billed per character and counted in the daily limit) or ElevenLabs (with your ElevenLabs key and plan credits). The recording arrives on Telegram with a player; other channels get a note, and Needs you › Recent recordings keeps the last ones.

Talking with Pimpo#

In Chats, tap Talk and talk: on the computer or on the phone. With Wake word on, Pimpo waits for its name ("Pimpo, what's on tomorrow?"); after an answer you can follow up without it for a few seconds. It answers aloud with the chat's voice and listens again; talk while it speaks to interrupt it. What you say is written by Whisper on your Pimpo, never by a cloud service, and only while the conversation is on; nothing is recorded otherwise. Pimpo never takes an approval by voice: when an answer would change something, it says to confirm on the screen, and only a tap does it.

This page is built from the repository's documentation. Improve it on GitHub.