Pimpo
Documentation

User guide

Getting started

Install Pimpo, find your way around and ask for the first task.

Getting around#

Home is where the day starts: ask for anything, and see what needs you, what ran and what is next today, what you spent, and your recent chats. The side menu keeps what you use daily on top (Home, Routines, Activity, Assistants) and the rest under More; your conversations are listed below it. At the bottom, the bell opens Needs you, the one list of what waits for you, so you can answer in place, and the Pimpo menu has Settings, cost, System status (⌘⇧D: how busy the computer and Pimpo are, what is running now and the state of every channel, account and service), pairing a phone, the theme and help.

First steps#

  1. Install. Use the desktop app from the releases page (macOS, Windows, Linux), or run curl -fsSL https://raw.githubusercontent.com/turbine-dev/pimpo/main/scripts/install.sh | sh and then pimpo serve. Open the link it prints.
  2. Create the administrator's account. The first visit asks for your name: whoever installed Pimpo administers it (adds the people of the house, connections and rules) and, like everyone, sees only their own things. Then add a passkey to open Pimpo with Touch ID, Face ID or Windows Hello next time; you can skip it and add one later in Account. Installs from before this ask once too.
  3. Choose the model that thinks for Pimpo. The welcome screen shows what this computer already has (Claude Code, Codex, opencode, a local model in Ollama or LM Studio) or takes one API key (Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter and others). Pimpo picks the models for each job and tests them. A model is only needed to learn a task the first time; the routines it makes run without one.
  4. Pick your safety level. The welcome screen offers conservative, balanced (recommended) and liberal.
  5. Connect what you need in Connections: Telegram or WhatsApp to talk from your phone, then email and calendar. "Sign in with Google" connects both at once with your own Google client.
  6. Ask for something you do every week. Use "New task", or send a message on Telegram.

Want to see it first? Run pimpo serve --demo: a sample mailbox and calendar, no accounts, no costs.

Pimpo, the mascot#

Pimpo is a tuxedo kitten, black with a white blaze and muzzle. He is off until you turn him on in Settings › General (or, in the desktop app, Pimpo on the desktop in the menu bar).

In the desktop app he lives in his own small window, independent of the app: drag him anywhere on the screen, over any program; he stays there with the Pimpo window closed, follows you across desktops and comes back where you left him. He only goes away when you turn him off or quit Pimpo. In a browser he stays inside the page, since a web page cannot draw outside it.

He shows how things are going: he blinks and swishes his tail while all is well, looks from side to side while a task runs, perks up when something needs you, smiles when a routine works, droops his ears when one fails, and falls asleep after a few quiet minutes. Now and then, when all is calm, he plays for a few seconds: chasing a butterfly, batting a ball of yarn, yawning and stretching, or washing his paw (never while a notice is open, and not when the system asks for reduced motion). Notices appear in his speech bubble with See and Later; approvals stay until you answer. Click him for a small menu (new task, what needs you, give a treat, silence for an hour, hide or turn off) and hover to pet him. Give him a treat and he jumps to catch a little fish in the air, then chews happily and purrs (the purr is made by the app on the spot, and only plays when you feed him). Turn him off and he waves his paw and trots off the screen. He only shows what already happened; he never acts on his own.

Language#

Pimpo speaks Português, English, Español, Français, Deutsch, Italiano, 日本語, 简体中文, 한국어 and Русский. Choose in Settings › General: the app, the messages on Telegram and the other channels, approval requests, connector instructions and the dates routines write all follow it. Tasks are answered in the language you ask in. The phone's pairing screen follows the phone's language. This guide is in English only.

Chat#

Talk is a conversation with Pimpo in the app, with every past conversation on the side. Each message remembers the ones before it. Pimpo reads for real (your calendar, your email), but any change it would make is only rehearsed and listed under the answer, with its risk. Confirm and do it does exactly those changes, once, each still under your rules and approvals; Turn into a routine makes the task repeat on its own. The search box above the list of chats finds words in your past conversations, in any order and ignoring accents ("reuniao" finds "reunião"); put a phrase in double quotes to find it exactly as written. It looks only in your own conversations.

Assistants (from the chat's side panel) are roles for the agent: a name, what its job is, the tools it may use and, if you like, the models it may answer with (inside what the person asking may use). Pick one when starting a conversation. Tap the microphone to speak instead of typing: the computer's own dictation is used when there is one, otherwise the audio is transcribed on this machine with whisper.cpp; a question you spoke is answered aloud, and Listen reads any answer. The limit is enforced by Pimpo itself: the assistant only sees its tools, and any other call is blocked, whatever the text says. A routine made from that conversation uses only those tools too.

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