USER_GUIDE.md

Pimpo user guide

This guide walks through the app. For the command line, settings and the data folder see Configuration; for how routines work inside and how to write one see Routines; to add services see Connectors.

Pimpo was called Zodim, and Vigia before that. An existing install moves over on its own the first time Pimpo opens (with the old app closed): data, keys, backups and paired phones keep working.

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.

How a task becomes a routine

1. Exploration. The agent does the task once. Anything that would change something (archive, send, delete) is only simulated, and you see exactly what would happen.
2. Routine. If you like the result, tap "Turn into a routine". Pimpo writes code with tests and checks it against what the agent did. You can read the code on the routine's page.
3. On its own. The routine runs on schedule without a model. If a service changes and the routine breaks, you get a notice with "Redo with the agent", and the agent fixes it.

Routines that react to something new

Ask for a reaction instead of a time ("tell me when an email from Ana arrives", "when this site publishes something new") and the routine watches instead of running on a clock. Pimpo checks the source every few minutes without any model, so the checks cost nothing, and runs the routine only with what it has not seen before; the first check only learns what is already there. Change how often it checks in the routine's settings. The empty checks stay out of Activity; what was found and what the routine did show up as usual. The gallery's Email from someone important is one.

Routines that watch Gmail or Slack can also hear of new things as they happen: in the routine's settings, turn on Hear of it as it happens. Gmail then tells Pimpo about new mail at once (the administrator sets up Google Cloud once; see Push triggers), and the settings show until when the push is active; Slack messages in the channels Pimpo's app is in, and mentions of it, arrive as they are sent (ask for "when someone mentions Pimpo in #support, tell me"). What arrives reaches the routine as data, never as orders. Each person's push wakes only their own routines. If the push stops (Pimpo was off, Google sign-in expired), the routine simply goes back to checking every few minutes.

A routine can also write a little: "and tell me in one sentence what she is asking for", "suggest a reply". The part that must be composed is written by a small model (the one set for judgments) for each item, about a fraction of a cent each; everything that can be copied (sender, subject, date) stays plain code. Each text is checked against the daily limit first, shows up in Activity, and treats the email as data, never as orders. What the routine then does with the text still passes your rules and approvals.

Routines that remember, and routines built from others

A routine can keep small values between runs: yesterday's price, the items it already sent, a weekly total. Ask naturally ("only tell me if the dollar went up since last time") and the routine keeps what it needs. The routine's Memory tab shows what it kept and clears it; nothing is kept from a run that failed, and at most 64 KB.

A new routine can also run a routine you already have and use what it returns ("every morning, count today's appointments using my agenda routine"). The new one must declare everything the other touches, so reusing a routine never widens what the owner approved; if the other routine later needs more, the new one stops and asks to be redone. Routines can use others up to three levels deep and never in a loop. Gallery routines cannot use others, since your routines do not exist on other machines.

Routines in a repository

Routines › Repository keeps your routines as files in a folder you choose, ideally a git repository: routines/<id>/routine.js (the code), routine.json (name, description, manifest) and tests.json. Send routines to the folder writes them and makes a local commit; Publish (git push) sends them to the remote only when you click it. Fetch changes (git pull) runs git pull --ff-only (a local edit is never overwritten) and lists every new or changed routine with its tests already run and what it would start being able to touch. Nothing is installed until you click Install or Update, and it is checked again at that moment; a routine that fails its tests, or has none, cannot be installed. Pimpo looks at the repository every 15 minutes and tells you once when something changed. Routines there can be reviewed in pull requests like any code.

Changing a routine without code

Every routine page starts with Routine settings:

• When: every day, weekdays, some days of the week, once a month, every few hours, or a cron expression under "Advanced (cron)".
• The routine's own choices: a city (search by name), a limit, a list of words, a currency, whatever the routine was made with. Pimpo's compiler turns anything personal in your request into one of these, instead of writing it into the code.
• Where to notify: one or more destinations. These can be your Telegram, other Telegram bots (a family group, for example), WhatsApp, Slack, Discord or email. With none chosen, Pimpo uses your usual channel.

To add more Telegram bots, go to Connections › Extra Telegram bots. Create the bot with @BotFather, paste its token, send it a message (or add it to a group), and tap Detect chat.

Long jobs

For work too big for one answer ("compare these 20 suppliers on price, delivery and reviews and prepare a proposal"), open Jobs, describe it and give it a budget (up to $20). Pimpo first shows a plan: up to eight parts, each with only the tools it needs. Nothing runs until you tap Start. The parts then run in the background, three at a time, for as long as they need (up to 90 minutes each); like the chat, they read for real and only propose changes. Jobs shows each part's progress and cost against the budget; when the budget runs out, the job stops and says so. If Pimpo restarts, finished parts stay finished and interrupted ones start again. At the end a report puts the parts together, and you are told on your usual channel.

Progress is kept, not just shown: Home lists what is running now, and each job and each routine shows its parts or steps, the step it is on (by the part's or the tool's name), the cost so far and when it last moved. A reload, the phone or a restart shows the same thing; a job picked up after a restart says so, and a routine run a restart cut short says it was interrupted. Turn on Follow on my channels on a job (before starting it or while it runs) to get one message about it on your channels: on Telegram, Discord and Slack that message is edited in place as the job goes, at most every 10 seconds, and ends with the result; on channels that cannot edit a message (Signal, WhatsApp, iMessage) you get only the start, and the notice at the end. Each person sees only their own progress.

Companies of agents

With Settings › Labs › Companies of agents on, More › Companies lets you build a company of any kind (a shop, an agency, a software project, a channel) whose members are agents. You are at the top, as the CEO.

• A company's page has five parts: Team (the org chart and the roles), Work (tasks, meetings and the activity), Knowledge (context and rules, and memory), Governance (decision levels and costs) and Output (product, media and the showcase, when the company has them). On the phone one list picks the section. The header shows whether the company is working or paused and what it spent this month; Edit company and Pause company sit beside it, and ⋯ holds Export and Delete. A link with ?tab= (for example ?tab=costs) opens that section.
• New company starts from A template (a software company with a product owner, a project manager, two developers, a CTO, marketing and finance; a marketing agency; an online shop; a content channel; a consultancy; or a blank one; its names, roles, responsibilities and context come in your language), from Describing it (say what the company does and a model proposes its departments, roles, members, context and routines; you see the proposal, and nothing is created until Create this company; capabilities Pimpo does not have are left out and said so), or Blank with a name, its industry and its mission. Import takes a company file someone shared. Export on a company's page saves it as a .company.yaml file; it carries the departments, roles and members, never who you are, and whoever imports it becomes its CEO.
• Roles are the functions in the company: a title, what the role is for, its responsibilities and deliverables, the accounts it needs, the tools it may use and the models it may use. Several members can hold the same role. A role in use cannot be deleted.
• Hire puts an agent in a role: a name, an avatar, a personality, a department, who it reports to and, if you want, fewer models than its role. Working off pauses it: it starts no new work. Remove from company, set apart at the end of its window, removes it after asking, and whoever reported to it reports to its boss. The avatar is the square at the top of the window: type an emoji or a letter; empty, it shows the name's first letter.
• Departments group members on the org chart with a color.
• Context and rules hold what members need to know and what they may do, for the whole company, a department, a role or one member. Each member receives the company's context first, then its department's, its role's and its own. For rules, the most specific one wins: the member's, then the role's, the department's and the company's. A rule that allows what a broader rule forbids asks to be saved as an exception, and stays marked with the rule it goes against. Company rules never go past the house's rules: a member's action takes the stricter of the two.
• What this agent receives, in a member's window, shows its brief as the agent reads it and what each of its tools would do now (allowed, made reversible, asked first or never), with the rule that decides.
• The org chart draws the company as a tree. Drag a card onto another to change who the boss is, or choose Reports to in the member's window; a member can never report to someone below it. On the phone the tree is a list.

Members work on their own:

• Work and routines, in a member's window, has Give a task now (the agent does it as soon as it is free and on duty), its Routines with the agent (instructions on a schedule, every hour, every weekday at 8 or your own cron, each with what one run may spend, up to $5), and the Automatic routines you give it: your routines that run without a model as this member and wake its agent with company.wake when something new arrives.
• A member's work is real: what it sends is sent. Every action still passes the house's rules and the company's, and only the tools of its role are within reach. One piece of work runs at a time per member and three per company; the rest waits in line.
• Working hours, in Edit company, keep work for the days and hours you choose; what arrives outside them waits. A member can have hours of its own.
• On the org chart a member that is working shows a blinking dot (hover it for the task), and a number shows how much waits. Work › Activity lists what members did, are doing and will do, with what each cost; Stop ends a piece of work.
• Pause company stops every member, and a department or a member can be paused on its own: what they were doing stops and waits, and their routines do not run until you resume.

Members work together, and stop to ask:

• Tasks shows the work handed between members, by state. New task hands one to a member with its objective and how to know it is done (both required), its constraints and what is out of scope. Members hand tasks to the people below them the same way (and to their department when Edit company allows it); Pimpo keeps each task's dossier, the links to where it came from, so whoever does it reads the original and not a summary of a summary. When a task is done or blocked, whoever gave it is told.
• A handed-down task is checked against the task it comes from; one that may have strayed shows May have strayed from the goal and waits for its assignee's boss to say whether it starts. Pimpo refuses tasks that would make delegation run away: more than four levels deep, more than ten open tasks for one member, the same task twice, or work handed back up.
• A member can stop and ask its boss before deciding. The question waits until it is answered, as long as that takes, and costs nothing meanwhile; the member takes other work in the meantime. A boss that is an agent answers it as work of its own (or asks its own boss); when the boss is you, the question reaches Needs you, your channels with the options as buttons, and the Tasks tab. With the answer, the work goes on from where it stopped, told what it already did.

The company remembers, meets and reports:

• Memory holds what the company decided and learned: decisions, facts, lessons and the minutes of meetings. There are three: the Company's, which every member reads; each agent's own, which only that agent reads; and each task's, read by the work on it and on the tasks below it. Every member receives the latest with its brief, and looks further back with company.recall. What a member keeps with company.remember is shown as that member's words, never as a rule; only you forget a note.
• How memory is written, on the same tab, says for each memory whether agents write to it freely, after a decision or not at all. By default they write freely to their own and their tasks' memory, and a note for the whole company waits under Waiting for approval (and in Needs) until you keep it; After a decision can also name the boss, Jev, a model or a committee. Keep a note after each piece of work has Pimpo note, by itself, what each finished piece of work did in its agent's or its task's memory.
• Meetings let agents talk an agenda through. With I take part on, the meeting is yours: you talk with all its agents or with the ones you pick under Speak to (or name one with @), and they answer in turn, each hearing the others and knowing its recent work. Talk in a member's window opens a conversation with that agent alone, and Talk with on a question it asked you discusses it before you answer. Make it a task under any answer gives that agent work, with the conversation as its context. End with minutes keeps the minutes and decisions in the memory. Without you, two to eight agents talk for one to four rounds and the chair writes the minutes; a member can call one with company.meet. Meetings only talk, with no tools, and stop at their cost cap (up to $2).
• Performance, on Work, shows how each agent did: work done and failed, minutes and cost for each piece, tasks closed and stuck, questions it asked, kinds of delivery it earned, and, where its role has them, how many of its briefs' predictions came true and how many of its videos pass their checks.
• Showcase, a tab only the company's creator sees, is an optional public page at /showcase/<address> with only what you put on it: briefs that shipped, videos the company uploaded, and links. It shows the company's name, industry and mission and names no one, neither you nor the agents. It is off until you turn it on, and the world reaches it only if it reaches your Pimpo (for example with Tailscale Funnel).
• Dashboards can show a company: its summary (who is working, questions waiting for you, spent today and this month) and its spending this month by day, under Companies when adding a widget. Only people who may view the company see them.
• This week, at the top of Work, sums up what each member did and what it cost, the tasks closed and the questions waiting. On Mondays the same summary reaches you on your channels.

You choose who decides:

• Autonomy, in a member's or a role's window, says who decides when an action would ask first: the agent itself, Jev or Laya with a minimum certainty (sure yes goes ahead, sure no is refused, unsure goes on), a model, the boss, a committee of members voting, a cascade of these, or you. A member's lines come first, then its role's, then the company's default, set in Decision levels; with none, you decide. What the administrator's own rules ask, and messages to other people, always reach a person. What this agent receives shows who decides each tool.
• Decision levels say which decisions go up to whom. Use the four suggested levels (operational, tactical, managerial, strategic) or write your own: each level names who decides (the agent, its boss, the head of its department or you) and its triggers (an amount over a limit, a risk, kinds such as price or contract, being public, words). Each level reads as a sentence, when it applies and who decides, and its pencil edits it in place. A decision is at the highest level its triggers reach. Questions the triggers leave below the top are checked by Jev, and an unsure one comes to you. Strategic questions can reach you with the bosses' opinions on the way. No rule or autonomy takes a decision of your level away from you. The Simulator shows where a decision would land, and Decisions lists every answer given, by whom.
• Earned autonomy: when you approve the same kind of delivery from a member several times in a row (10 by default) without saying no, Pimpo suggests letting it do that alone, in Needs. Let it do it alone adds a line to its autonomy, marked as earned; a no to that kind later takes it back to approval. The decision levels and what always asks a person stay above it. Set the number, or turn suggestions off, on Decision levels.

Costs have their owner:

• Costs shows what the company spent today and this month, what it is likely to spend this month (from its routines and the pace of the last two weeks), and, per member, what it spent, how many pieces of work it finished, what each cost and its forecast. Every model call, judgment and meeting is booked for one member.
• Limits sit in layers: the company's (a day and a month), a department's (a month) and each member's monthly salary, all inside your own limit and the house's. A company cannot be given more than your own daily limit. Near 80% of a limit you are told once that day; at the limit the agents stop until the next day or month, or, if you choose Only tell me, they go on and you are told. A piece of work never gets more than what is left.
• Work paid by your subscription (Claude Code with a Claude plan, Codex with ChatGPT) costs no money per call, so dollar limits alone do not hold it back. On subscription shows what it would have cost on the API, and Count subscription work at API prices makes the limits count it too. When the subscription runs out of turns, the work waits an hour and tries again (up to six times) instead of failing.
• Hire shows what a member in that role costs a month, from the others in it.
• Finance: a member with costs.read reads a month of what the company spent with Pimpo, by member and department, against its budget and the month before, with what looks wrong: a day that spent more than twice the usual of the two weeks before it, or a member on pace for half again what it spent last month. With the Stripe connection (a restricted key that only reads the balance and charges) and github.sponsors, it also reads what comes in. On the first of each month it is asked to write the month's report, kept in the memory. It proposes budgets with company.budget_propose, for the company, a department or a member; they wait on Costs and in Needs, and only Apply changes the limit, within your own. Nothing a finance member does moves money.

Each agent has accounts of its own:

• Own accounts, in a member's window, connects accounts for that agent only: its own mailbox, GitHub, Slack, Notion and any other connection Pimpo has. Each one says what kind of account it is: a service's, a machine's (where the service allows automation), the brand's, or a real person's. Pimpo warns when a service's terms may not allow that kind, such as an agent's personal profile on a social network; brand accounts are the safe choice there. A role can list the accounts it needs; its members wait until they have them, and the org chart shows a key when one is missing.
• GitHub gives a developer, a reviewer or a product owner the work of a real team: reading a repository, its issues and pull requests, opening and editing issues, opening pull requests, reviewing them, reading their checks, merging and publishing releases. Merging, releases and comments are irreversible, so they go to whoever your rules and decision levels say before they happen. Give each agent a fine-grained token of its own, limited to the company's repositories.
• Product: a product owner keeps what it hears with company.signal (the same page or nearly the same title heard again counts on the first, with every place it was heard) and proposes briefs with company.brief: the problem, the proposal, claims that each cite a source and quote the words that support them, scores from 1 to 5 and predictions of what will change. The score is 2 × value + differentiation + 2 × adoption − build risk − safety risk. Jev flags a claim whose quote does not support it, and a claim that quotes nothing is flagged too. Briefs wait for you on the Product tab and in Needs: accept or reject them, then Mark as shipped with where they shipped. On days 30 and 90 after that, the author is asked to check each prediction against what happened, and the tab shows how many came true. A project manager writes issues with acceptance criteria (github.issue_create turns them into a checklist) and gets its team's day with company.standup: what each member below it did, is on, waits for and is stuck on, to keep as a standup note.
• Media: a content role makes videos on this computer. media.voice reads a text with the voice you chose for routines, media.capture takes a screenshot of a page in the agent's own browser (only hosts your rules allow, with Use a browser on in Labs), and media.render puts scenes of an image, a voice and a caption together with ffmpeg as a tutorial (16:9, up to 20 minutes) or a short (9:16, up to 60 seconds), its sound brought to −14 LUFS and its captions as a subtitle track. Every video is checked before anyone is asked about it: its length, its aspect, its loudness and its captions. The Media tab shows them with what the checks found. ffmpeg must be installed (on a Mac, brew install ffmpeg).
• Publishing: youtube.upload sends a video that passed its checks to the company's channel, always as private and marked as made with AI; youtube.publish makes it public and, being irreversible, goes to whoever your rules and decision levels name; youtube.stats reads how it does. linkedin.post posts on the company's page. For a network Pimpo does not post to, such as Instagram or TikTok, publish.assisted sends the ready post to your phone to publish by hand. Connect YouTube (the channel's brand account) and LinkedIn (the company page) as accounts of the agent. Whatever a member publishes ends with the company's AI disclosure, which you can word in Edit company but not leave out.
• Coding: a role with code.workspace codes. In the member's window, Coding picks the CLI it codes with (Claude Code, Codex or opencode, with a model if you want one) and whether it codes in that CLI's sandbox, where commands write only in the task's folder; opencode has none, and without it commands run on your computer as you do. Each task gets its own git worktree and branch (pimpo/<member>/<task>); the CLI changes the files, Pimpo commits them as the agent and pushes the branch with the agent's GitHub token, and the agent opens the pull request with github.pr_create. The CLI gets none of your keys nor your git credentials. Variables for coding, in Edit company, are given to the CLIs, one NAME=value per line; they are not for secrets. When a task is done its worktree goes away; what was pushed stays on GitHub.
• The company's accounts, on the Costs tab, are shared ones (the official channel, the support inbox) with what each agent may do: nothing, read, or act. An agent uses its own account first, and the company's only when it was given it.
• An agent never uses your accounts, or another agent's. It never reaches your phone, your Mac's apps, your house, your Google account, your music, your notes or your memory, and it browses with a browser profile of its own, never with the sites you signed in to.

A company is yours alone, like your routines: nobody else in the house finds it, the administrator included. Shared with someone as a partner, they see it with what they were given (view, approve or configure); only you delete it or change who it is shared with.

Run history

Routines › Runs lists every run of every routine, newest first, with its cost, how many calls it made and how long it took. Failed shows only what went wrong, with the error. A routine can run as often as every 5 minutes (Every few minutes in its schedule).

Dashboards

Painéis (Dashboards) shows widgets in tabs: one tab per dashboard, as many as you like (home, work, the shop). The first one, Home, starts with the ready-made widgets. + makes a new tab with a name and an emoji.

• Editing. Edit lets you drag a widget by its handle, resize it from its corner, remove it, rename the tab or delete it. Add widget lists everything you can put on it, drawn as it will look. On the phone, and in a narrow window, the widgets stack.
• Kinds. A widget is one of seven kinds:
  • a number, with its trend and a sparkline of its history;
  • progress towards a goal;
  • a status (OK, attention or alert);
  • a list;
  • a table;
  • a chart (line, area, bar or donut);
  • a few lines of text.
• Ready-made widgets. They need no routine: what needs you, today's runs, your reminders, spent this month, and today's limit.
• Routines as widgets.
  • Ask for one in the chat: "show me the dollar every hour", "keep a widget with today's orders". The routine then updates its widget each time it runs.
  • A routine you already have becomes one with Turn into a widget on its page. Pick a kind, or let Pimpo pick. Pimpo redoes the routine so it also shows its result, keeping everything else it does, and you approve the new version as with any change. A routine that already shows a widget offers See on dashboards instead.
  • Any routine can also go on a dashboard as its health: its last run, success rate and next run.
• Refreshing. Widgets update live as routines run, and say when they are out of date. Refresh now in a widget's menu runs its routine once. When the routine uses a model and its last run cost a cent or more, it asks first.
• Floating on the desktop. In the desktop app, Float on the desktop in a widget's menu puts it in a small window of its own, above your other windows and on every desktop. Drag it by the card and resize it from its edges; it keeps its place and size, and comes back when the app starts. Its × closes it, and the arrow opens the dashboards. Floating widgets update live, and they close while the app is locked (see Locking the desktop app) and come back with the unlock.
• On the Android home screen. In the Pimpo app on an Android phone, Add to the home screen in a widget's menu places it on the home screen. It refreshes about every half hour and whenever you open the app, and a tap opens Pimpo. Away from home, or with Pimpo off, it keeps the last values and says how old they are. You can also add a Pimpo widget from the launcher's widget list and choose one of the widgets already on that phone. The phone reads them with a key of its own, made on the phone, that reads only those widgets and nothing else; it stops working when the phone is removed. iPhone widgets wait for a later version.
• Sharing.
  • Share with the house, in edit mode, shows a dashboard to everyone in the house.
  • They see only the widgets you marked Share with the house in the widget's menu, and their own ready-made widgets. Everything else shows as not shared with them.
  • Nobody else can change your dashboard.

Approvals and rules

• Needs you is one list of everything waiting for you: approvals (with For this routine where it applies), keys Pimpo asked you for privately (each opens its own form), questions from routines (tap an option or type the answer), routines stopped after a failure, jobs that ran into a problem (for a week) or whose plan waits to be started, tasks ready to review, how many lessons wait for you and, for the administrator, suggestions and parts of the house that stopped working.
  • The most urgent comes first: an approval about to expire (it says when), then approvals, questions, what broke, and the rest; within each, the newest first.
  • Filter by kind with the tabs on top. Answer in place: allow or deny, pick an answer, run a routine again or redo it with the agent, or open a job or task.
  • The bell (in the header on the phone, at the bottom of the menu on the computer) shows how many things wait and opens the same list; Home shows the first three.
  • It only ever shows your own things, the administrator included, and it updates by itself as things change.
• Approval buttons: Allow (this time), All this run (the rest of this run), Always (this routine, from now on), Deny.
• For this routine lets a routine repeat exactly this action without asking again: the same kind of action to the same recipients, on the same site, with an amount up to the one you approved (you can raise the limit in Needs you). A different recipient, site or larger amount asks again, and so does a new version of the routine. The email's words can change every day; who it goes to cannot. Routines › Approved for routines lists these approvals and takes any back. It is safer than Always, which allows the whole capability for that routine. Members use it for their own routines; WhatsApp to other people, locks and alarms still always ask. On WhatsApp it takes the place of Always, which stays in the app.
• Rules: write rules in plain words ("never delete emails from my boss"). You see exactly what the rule will enforce, and a test against last week, before saving.
• Some things always ask, whatever the rules say: WhatsApp to other people, locks and alarms.

Receipts and undo

Every action has a receipt: what was done, with which arguments, under which rule. Reversible actions can be undone from the receipt. Deletes go to the trash, and sent emails wait 10 minutes before leaving.

Settings history

Settings › History lists every change to rules and the safety level, the budget, connections, models, people and the other settings, newest first, with who made it and when; filter it by area. Undo (after a confirmation) puts the earlier values back. Undo starts from the newest change: a setting changed again since must have that newer change undone first. Passwords, keys and tokens are never kept in the history, not even encrypted: it only says one was added, replaced or removed, and to change one back you type it again. Adding or removing a person is not undone here. A member finds the history of their own mail and calendar in Account; nobody else sees it, the administrator included.

Memory

Pimpo remembers what you tell it. Facts it read somewhere are marked "not confirmed" and never guide it until you confirm them. Every change is versioned: History › Go back to this undoes any change.

Each fact shows where it came from: a conversation, a task, a routine or a job (a link opens it), an email and its sender, an import, something you typed, or a preference Pimpo learned. Facts saved before Pimpo kept sources say "Unknown source". Sources groups your facts by where they came from; Delete everything from this source lists the facts that go and, once you confirm, deletes them all, for example everything read in emails from one sender or noted in one conversation. A fact found in two places goes with either. It is one change in History, so it can be undone. You see and delete only your own facts' sources, and of the household's facts only the ones you shared.

Search memory in plain words ("what can't I eat?"): with Jev set up, Pimpo finds facts by meaning, not only by the words they share, and the agent uses the same search. Every night Pimpo merges facts that say the same thing, never trading one you confirmed for one it read somewhere, and never merging facts that differ in a date, place or name. Organize does it now, and History undoes it.

Preferences Pimpo learns

Once a week Pimpo looks at what you asked and decided yourself (the requests you made, the approvals you denied or made permanent, the suggestions you took or declined) and may note up to five preferences, such as "answers in Portuguese" or "nothing before 8". It never learns from an email, a page or anything else it read. Each one shows up in Memory marked learned, with what showed it: Confirm makes it a fact like any other, and removing it means it is not learned again. Turn it off in Settings › Notifications. Each one is also a lesson in Lessons.

Lessons

Lessons (with a count in the menu, and a line in Needs you) is where everything Pimpo noticed and would keep waits for you, and only for you: nobody else in the house, the administrator included, sees your lessons. There are four kinds:

• Preference: one it learned from your own requests (above), with links to the requests it came from.
• Fact: a note the agent took during a task ("your boss is Carlos"), with a link to that task. It may have read it in an email, so it counts as unconfirmed until you accept it.
• Routine: a task you asked more than once that worked and is not a routine yet, or a suggestion (below). It shows the request the routine would do and links to each time you asked.
• Fix: a routine failed and the agent redid it (Redo with the agent). It shows the error and what the new version did.

Accept does what you would do by hand: it confirms the fact or preference, or turns the task into a routine (or keeps the repaired version) through the usual compiler, with its checks, so an older version stays in the routine's history. Edit lets you change the words first: the fact is kept in your words, and a routine or fix with new words is done once more for you to watch and approve. Reject removes the note or discards the repair, and the same lesson is never proposed again, even worded a little differently. Nothing on this page applies until you choose, and the Memory page and Needs you show the same things, so deciding in either place counts. Once a week, if lessons are waiting, Pimpo tells you on your channel with a link (turn it off in Settings › Notifications › Weekly lessons digest); you decide on the page, never by replying.

People

In People, invite family members as a member or a guest. They send the invite code to the bot and get their own memory and accounts. To give someone the app, pair a device for them in Settings › Open on your phone (choose whose device it is): it signs in as them.

Everything is private to its person: routines, conversations, memory, activity, approvals, recordings, long jobs and what their phone shares. Nobody sees anyone else's, and that includes you, the owner: you run the house (people, connections, models, rules, backups) but never see what the others keep. Only costs are shared, as a total, because the budget is the house's. A fact marked Household in Memory is shared with everyone.

Signing in. Besides the link, each person can add a passkey in Account (the menu under your name): afterwards Pimpo opens with Touch ID, Face ID, Windows Hello or a security key, as them. A passkey works at the address where it was made, localhost on the computer or an https address; on the home-network address, and in the desktop app's own window, use the link (Pimpo offers a passkey only where one can work). Sessions and devices left unused expire (30 and 180 days).

A member manages their own routines and answers their own approvals; a guest can only ask, and a guest's changes wait for the person responsible for them. A lasting "always allow" is a rule for the whole house, so only the owner makes those. Removing a person revokes their devices at once.

Models and spending. Under each person, Models and spending chooses which of the house's models they may use (all of them, or some) and a daily limit of their own, in dollars, at most the house's. A guest starts with $0.25 a day until you set another. Every cost counts for the person it was for, whether it came from a chat, a routine, a job or a judgment, and a call is refused when it could pass their limit or the house's. The automatic choice picks only among their models (the cheapest of them when its own pick is not allowed), a model chosen by hand outside them is refused with the reason, and their routines and jobs keep to them too. You see only whether someone reached their limit today, never how much they spent: costs are shared as a house total. Each person sees their own models, limit and today's spending in Account.

On the phone

1. 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.
2. 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.
3. Scan the QR code with the Pimpo app, or paste the link.
4. 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.

Dashboards in Telegram

When Pimpo has a public https address (From anywhere with Tailscale Funnel, or your own https address under Use another address, in Settings › Open on your phone), the bot adds a Dashboard button next to the message box of everyone who paired Telegram, and notices that wait for an answer get an Open dashboard button. It opens a small Pimpo inside Telegram, on the phone, the desktop app or Telegram Web:

• Needs you: approvals (allow once or deny) and the questions routines asked, with their options.
• Routines: your routines, with Run now and Pause or Resume.
• Spending: what the house spent today against its daily limit, this month, and what your routines cost this month.
• Widgets: your widgets, all of them or one dashboard at a time.

It signs you in as the person who paired that Telegram account, with nothing to type, and shows only your things; guests see what guests may use. The session lasts an hour; after that, close it and open it again from the bot. Telegram opens only https pages, so without a public https address the button does not appear (and goes away if the address does). A Telegram account nobody paired gets nothing.

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.

Webhooks

Any routine can be started by another service calling a secret address: on its page, turn on Start by webhook. Use it from an iPhone Shortcut ("when I leave home, send me the day's brief"), IFTTT, Zapier, GitHub or a form. What is sent (JSON, form fields or text) reaches the routine as event.webhook with method, query and body, so a routine can act on it ("when a new order arrives, tell me who bought what"). Ask for such a routine in a chat and Pimpo makes it start by webhook. Addresses work on this computer and on the home network; for internet services, turn on Tailscale with Funnel. Anyone with the address starts the routine, so treat it like a password; New address replaces it at once. A paused routine does not start, a call carries at most 256 KB, and a routine starts at most 30 times a minute this way.

For GitHub, turn on Start from GitHub instead ("when a pull request is opened in my repository, tell me its title"): copy the address and the secret, shown only once, into the repository's Settings › Webhooks. GitHub signs every delivery with the secret, so nobody else can start the routine, and a delivery GitHub sends again starts it only once. The routine gets event.github with the event type, the action and the payload.

Google Sheets

With Google connected, tasks and routines can read a range of a spreadsheet and add rows to it (sheets.read, sheets.append): log expenses, habits or orders, or read a list to act on. Name the spreadsheet by its address. Turn on the Google Sheets API in your Google Cloud project; if you connected Google before this, sign in again to allow spreadsheets. Added rows can be undone in Activity.

Spotify

Connections › Spotify lets tasks and routines see what is playing, play a song, playlist, album, artist or podcast by name, pause and set the volume, on any of your Spotify devices ("play my news podcast on the living room speaker at 8", "pause the music when a meeting starts"). Create an app at developer.spotify.com, add the address Pimpo shows under Redirect URIs, and paste its Client ID; no secret is needed. Controlling playback needs Spotify Premium.

Apple Reminders, Notes and Calendar

On a Mac, Connections › Apple Reminders, Notes and Calendar lets tasks and routines use Apple's own apps: add a reminder that rings on your iPhone and Watch, mark one done, list the open ones; search your notes and add to a note in Pimpo's folder; read the Mac's Calendar. Give the Notes folder Pimpo writes in (created if missing) and, if you like, the default Reminders list. The first time, macOS asks to let Pimpo use each app (System Settings › Privacy & Security › Automation). Reminders added and notes changed can be undone in Activity. When this is connected, "remind me tomorrow at 9" goes to the Reminders app.

Routines that ask you

A routine can ask you something and act on your answer: "every night ask me if I worked out and count the week's workouts", "ask before archiving". The question arrives with its options as buttons in Needs you and on Telegram, as buttons on WhatsApp (a list when there are more than three), and numbered on Discord, Slack and Signal; your answer runs the routine again, which records it or does what you chose. You can also answer in words: type it in Needs you, or reply to the question on a channel, with the option's number, its name or just the start of it ("swim" for "Swimming" works when no other option starts that way; case and accents do not matter). An answer that is none of the options is not taken: Pimpo shows the options again. Sending an option's exact name without replying also answers the question you were just asked, as long as you have not written anything else on that channel since; otherwise it is an ordinary message. A new question replaces the same one still unanswered, and a question expires after 24 hours.

Keys Pimpo asks for

When a routine or a task needs a password or key you have not given (a GitHub token, a Notion integration token, your email's app password), or the service stops accepting the one you gave, Pimpo asks for it privately. You get a notice, "GitHub needs your token", with a link to a form in the app; the request also waits in Needs you. The form writes the key straight to Pimpo's vault, under your name: a member's keys are theirs and the administrator never sees or answers their requests. After saving, Run the routine again or Try the task again picks up where it stopped. The link works once and expires after a week.

Never send a key in a chat or a channel message. If you do, Pimpo takes it out before the message goes anywhere (the model, the conversation, the activity log) and does not keep it; it tells you so and points you to the form. It recognizes common formats (API keys of the big providers, GitHub, Slack and Telegram tokens, private keys) and values written after "password:" or "token=". It removes only what looks like a key, so the rest of your message still goes through.

Reminders

Ask in any chat, in the app or on a channel: "in 30 minutes remind me to check the deploy", "remind me tomorrow at 9 to call Ana". Pimpo sets a reminder that goes out once, where your notices go, and is gone; nothing is turned into a routine. Pending reminders are listed at the top of Routines, where each can be cancelled. One that falls due while Pimpo is closed goes out when it opens, saying it is late. What repeats ("every Monday…") is a routine instead.

Other chat channels

Messages you send on Telegram, WhatsApp, Discord, Slack or Signal continue one conversation, so a follow-up like "and tomorrow?" knows what came before. Each conversation also appears under Chats in the app, where you can pick it up. Send /new (or /novo) to start over; after three quiet hours a new conversation starts on its own. While a task runs, Telegram, Discord and Signal show Pimpo typing (Slack and WhatsApp do not offer that to bots in direct messages).

Besides Telegram and WhatsApp, you can talk to Pimpo in private messages on Discord, Slack or Signal. Set one up in Connections (each card says what to create and which token to paste), then send it pimpo followed by the pairing code shown in Connections. Only you are answered; strangers get nothing. These services have no buttons, so choices arrive numbered: answer 1, 2… A bare number answers the latest notice; to answer an older one, reply to it (Discord's Reply, a reply in the notice's thread on Slack, or quoting it on Signal) with the number, and it answers exactly that notice. Signal goes through a signal-cli daemon on your computer, so messages stay end-to-end encrypted up to it. iMessage works on a Mac: sign Messages in with an Apple ID (ideally one just for Pimpo), give Pimpo Full Disk Access so it can read what arrives, and send that Apple ID pimpo and the code; answers go out through Messages. SMS is not supported (it needs a paid service).

Personal WhatsApp (unofficial) talks through a WhatsApp Web bridge on your computer (WAHA) signed in to your own number. WhatsApp does not allow it: the number can be banned and it breaks without notice, so it is off until you turn on Labs › Personal WhatsApp (unofficial), and it never approves anything; choices wait for the app or another channel. The official WhatsApp (Business) in Connections has none of these risks.

If a channel keeps failing for three minutes (Telegram, Discord, Slack or Signal), Pimpo tells you on the others, with a computer notification and in Needs you, and again when it comes back. System shows the failing channel in red with the error. WhatsApp is left out: a failed WhatsApp message is usually about that message (the 24-hour window, a blocked number), not an outage.

More connectors

Web pages: a task or routine can read any web page (web.read): its title, its text without menus' scripts and styles, the structured data shops publish (the product's price, its availability) and its links. Like any web read, the first visit to a site asks you once. Some big shops (Amazon, Mercado Livre, Zoom) refuse automated reads; KaBuM and most smaller sites answer.

Web search in Connections lets Pimpo search the internet, with a Brave Search API key (free for 2,000 searches a month), a Perplexity API key (about US$5 per thousand searches, billed by Perplexity) or the address of a SearXNG instance you trust. DuckDuckGo has no official API for web results; a SearXNG instance can include it among its sources.

Connections › Explore searches the official MCP registry: hundreds of servers for files, GitHub, databases, notes, maps and more. Choose one, fill in what it asks for, and See the tools shows what it offers. Check which tools Pimpo may use and how risky each one is (irreversible ones always ask you first), then install. Add by hand takes a command or an https address you already have. See CONNECTORS.md to write your own.

A service with a REST API needs no program and no recompiling: describe its requests in a connector.json (the address, the key it needs, and for each capability the method, path and what to keep from the answer) and send it in Connections › Install connector (.json · .zip). Pimpo checks it, runs its contract and asks for the key. CONNECTORS.md explains the format; examples/connectors/hnsearch is a complete one. If the service publishes an OpenAPI (Swagger) description, Connections › From OpenAPI writes the file for you: give its address, choose the operations and how risky each one is, fill in the key and install.

Secrets in 1Password or HashiCorp Vault

Any secret field (a model key, a bot token, a connector's key, an app password, the backup passphrase) can hold a reference instead of the secret: choose the link icon, Use a reference, and type where the secret is:

• 1Password: op://Vault/Item/field (or op://Vault/Item/section/field), the same reference 1Password's "Copy secret reference" gives.
• HashiCorp Vault: vault://secret/data/path#field, a KV version 2 path (the mount, data, then the path) and the field.

Check reads it once and says only "Found" or why not; the value is never shown. Pimpo keeps only the reference and reads the value when a connection needs it, keeping it in memory for up to five minutes. If the reference cannot be read later, the connection fails with a message that names the reference.

Set up the password managers first. The administrator sets up the house's in Connections › Password managers; they read the house's references. Each person can add their own in Account › Password managers, and only their own connections use them: nobody else sees them or reads with them, not even the administrator, and a person's references never read with the house's credentials.

• 1Password: a service account token (the op command line must be installed), the 1Password app on this computer (house only; turn on Settings › Developer › Integrate with 1Password CLI) or a 1Password Connect server with its token.
• HashiCorp Vault: its https address, a token or an AppRole (role id and secret id), and a namespace if you use them.

Test checks that the password manager answers. Backups and exports keep the references as references, so a restored copy reads from the same place.

Gallery

Browse ready-made routines, filtered by what they can touch. Pimpo checks the author's signature, runs the routine's tests, and audits what it really calls before installing. To share one of yours, use Publish on its page.

Skills

Skills written for OpenClaw, Hermes or agentskills.io (a folder with a SKILL.md) teach the agent how to do a kind of task. Install them in More › Skills: paste a GitHub link to the skill's folder or send its .zip. Pimpo shows what the skill is, its full text, and which capabilities its text seems to need; you choose what it may use.

You do not pick a skill: the agent knows the ones installed and uses one when a task matches. From that moment, and until the task ends, it can use only the capabilities you allowed that skill; a skill allowed nothing can only guide it.

A skill is text someone else wrote, so Pimpo never treats it as your words: every action still passes your rules and approvals, the scripts it carries are not run, a skill the protection list reports is refused, and a skill changed on disk stops until you install it again.

Using sites without an API

With Settings › Labs › Use a browser on (it needs Google Chrome), the agent can open sites, read them, follow links, fill in fields and press buttons, in a browser profile of Pimpo's own, not your usual Chrome. Use Open Pimpo’s browser in the same screen to sign in to the sites your routines should use; Pimpo never types passwords, it uses the sessions you leave there.

Reading a page and following a link change nothing. Typing and choosing are kept undoable, and pressing a button asks you first, because it may submit, buy or send. A routine can only reach the sites it names, and a page that sends it anywhere else is refused. Everything a page says is treated as the site's words, never as instructions.

Running code

With Settings › Labs › Run code in isolation on (it needs Docker), the agent can run a short Python, JavaScript or shell program for a task, such as converting a spreadsheet or adding up a CSV. Each program runs in a fresh container with no network, no access to your files or keys, and 60 seconds at most; it gets only the files the task gives it and returns what it prints and writes. Routines can use it too, and their tests record its results like any other step.

Suggestions

Once a day Pimpo may notice something you repeat and offer a routine: "you pay this bill every month; want a routine for it?". The suggestion arrives in Needs you and on your channel, and says what Pimpo would do. Yes, learn it starts it the usual way (you watch it once and approve it); No, thanks makes sure it does not come back. For this Pimpo looks only at who writes to you and about what, your upcoming events and your routines, never at what emails say. Turn it off in Settings › Notifications › Suggestions.

Updates

The desktop app updates itself: when a new version is ready it says so at the top of the app and in the menu bar, and Update and restart installs it. Before a new version touches anything, Pimpo keeps a copy of your data. Settings › General › Updates looks for updates now, turns on beta versions, and goes back to the version you had before, with your data as it was then. On a server, run pimpo update (and pimpo update --rollback to go back).

Moving and backups

• Settings › Automatic cloud backup keeps a copy of everything in your own storage, every day or every week, and keeps the last copies you choose:

  • Amazon S3 or compatible (Cloudflare R2, Backblaze B2, MinIO, Wasabi): give the bucket, the region (auto on R2), the service address when it is not Amazon, and an access key that can read, write, list and delete in that bucket.
  • Google Drive: connect Google in Connections (with the Google Drive API turned on in your Google Cloud project) and allow Drive. Backups go to a "Pimpo backups" folder; Pimpo only sees files it created.
  • Each backup is encrypted on your computer with the passphrase you choose, database and memory included, so the storage service cannot read it. Keep the passphrase somewhere safe: without it no one can open the backups.
  • See backups › Restore brings one back; it takes effect when Pimpo restarts, and what was there is kept aside. If a backup fails, you get a message.

• Settings › Export and import everything creates one file with everything, all encrypted with a passphrase of at least 12 characters you choose. Import it on another computer. What was there before is kept aside.

• pimpo export file.pimpo and pimpo import file.pimpo do the same from the terminal. A file exported by an older Pimpo, not sealed as a whole, opens only with pimpo import --unsealed file.pimpo.

• pimpo snapshots and pimpo restore go back to an automatic daily snapshot. Paired devices, passkeys and people stay as they are now, so a device you removed does not come back.

• pimpo routines import FOLDER installs routines from a folder in the repository's layout (routines/<id>/), after the same checks as the repository: manifest, their own tests and an audit. They arrive paused; review their settings and resume each one. --active installs them running.

• Coming from OpenClaw or Hermes? Use Settings › Bring over from OpenClaw or Hermes, or pimpo migrate openclaw.

When the database is damaged: Pimpo checks its database every time it starts (SQLite's own check and the newest part of the history chain) and before every copy. A copy of a damaged database is refused, so it never pushes a good copy out; the check-up shows it and you are told once. At start, a damaged database is moved, untouched, into quarantine/ in the data folder, and Pimpo opens only a recovery page, for the administrator alone (your login link, a browser or device of yours that was signed in, or the recovery link Pimpo prints at start and pimpo token shows). There you can go back to the newest copy that passes its check (damaged copies are never offered), start fresh, or download the damaged file as a zip for a repair elsewhere. Either way the damaged file stays in quarantine/, and Pimpo then starts as usual. On the command line, pimpo restore NAME does the same while Pimpo is stopped.

Local copies (Settings › Backup): Pimpo copies everything on this computer every day, before each update and before an import, and keeps the last ten. Pick one and choose Go back to this; it takes effect when Pimpo is closed and reopened, and the current state is copied first, so it can be undone. After an update Pimpo tells you once that the copy from before is there. Going back to a copy restores data, not the previous version of the app.

Check-up

In System status (the Pimpo menu, or ⌘⇧D), Check everything tests every part for real, right now: each chat channel answers, email and calendar can be read, every model a job may use answers one word (API models, up to a cent each; Claude Code is only looked for, so your usage limit is not spent), each service passes its own check, local copies and cloud backups are recent, and there is room on the disk. Problems come first, each with what to do and a link to where to do it.

Help, notifications and labs

Help (at the bottom of the menu) answers questions about Pimpo itself: it starts a chat, and the agent reads this guide to answer. In Settings › Notifications choose what reaches you outside the app: task results, failed routines and backup problems can be silenced (they stay in Needs you); approval requests always arrive. Settings › Labs turns off newer features: organizing memory every night, searching memory by meaning, and exploring the MCP registry.

Models

Settings › Models (also reached from Connections › Intelligence) says which model does each job: doing tasks and chatting, writing routines, and answering the routines' yes-or-no questions and short texts.

• On this computer: Pimpo finds Claude Code (your Claude subscription), Codex from the ChatGPT app (your ChatGPT subscription), and a running Ollama or LM Studio with their models, which are free and private; an Ollama with no models says how to get one. Codex runs with its own shell, browser, computer control, apps and image viewer turned off and your Codex settings ignored, so it only reaches the world through Pimpo's tools; this was checked against the real CLI with a file, an image and a website it could not reach. opencode lends Pimpo the providers you signed in to there (GitHub Copilot, OpenCode Go, OpenRouter, DeepSeek…): choose models under opencode › Choose. Every opencode tool (shell, files, web, sub-agents, skills) and any MCP server of your own opencode config is denied, only Pimpo's tools are allowed, and each run's session is deleted afterwards; checked against the real CLI with a file, a shell command and a website it could not reach. Copilot, OpenCode Go and OAuth sign-ins count as subscription; OpenCode's free models only run inside OpenCode itself, so they are not listed. Chat apps (ChatGPT, Qwen, Claude) don't let other programs use their models, and Qwen Code goes through DashScope: connect the Qwen (DashScope) provider with the same key so its cost is counted.
• Providers: Anthropic, OpenAI, Google Gemini, OpenRouter, Qwen (Alibaba DashScope), DeepSeek, Groq, Mistral, xAI, or any server that speaks OpenAI's chat API. Paste the provider's key and its models appear with their prices, taken from OpenRouter's public catalog of list prices. A model the catalog does not know needs its price typed in, because the spending limit counts every call and Pimpo never guesses a price.
• Test and use: each model answers one real word (capped at one cent) before it is added, with the time it took or a plain reason when it fails (key refused, out of credits, usage limit, model not available, service down).
• Fallbacks: each job can have up to four models that take over, in order, when its model fails for a provider reason (for example Claude Code's usage limit). You hear once when a job falls back and once when its model answers again. Your own spending limit is never worked around this way.

Choosing the model in a chat. The pill under the message box picks the model for that conversation: Automatic (the default) or any model above. Under each answer you see which model replied and why, for example "Claude Code · haiku · automatic: simple request".

• Automatic choice (Settings › Models › Automatic choice in chats): each request is weighed before it is answered. Quick ones (a fact, one calendar item, a short reply) go to a light model, heavy ones (many steps across services, a long or delicate text) to a strong one, and everything else stays on the tasks model. Jev weighs the request when it is set up, and only a clear verdict (60% or more) moves it; otherwise a few simple rules do, and any doubt stays on the tasks model. With Claude Code the light model is haiku and the strong one opus; with provider models, the cheapest and the dearest of your list. You can pick them yourself, or turn the automatic choice off. After 80% of the daily spending limit the strong model is no longer used.
• Thinking level: the same pill has Thinking: Automatic, low, medium, high or max. Automatic follows the same weighing: low on quick requests, high on heavy ones (not after 80% of the daily limit), and the job's level otherwise. Settings › Models sets each job's level next to its model; leave it on the default to use the model's own. Claude Code and the Anthropic API take all four levels; Codex calls max "xhigh"; OpenAI, OpenRouter, Gemini, Groq, xAI and local servers stop at high; DeepSeek, Mistral and Qwen choose thinking by model instead. A model that does not accept a level answers without it.
• Channels: on Telegram, WhatsApp and the others, send /model to see the model in use, /model opus (or any model of your list) to fix one, and /model auto to go back to the automatic choice. /think does the same for the thinking level: /think high, /think auto.
• Who answers judgments (the yes-or-no questions of routines and decisions): Local model, Laya on this computer, Jev or your model. Laya is Jev's open decision model: calibrated, free, and run here with pip install "laya[serve]" && laya-serve. Give its address (port 8000); Test Laya saves it and asks Laya a question there. With Local model, an address set for Laya makes it answer first, before Pimpo's small model and Ollama; what neither is sure about still goes to Jev or your model. In a company, Laya is also a decider, with a minimum certainty, like Jev.
• Routines run without a model, except for their yes-or-no questions and short texts. A routine that has them shows Model for judgments and texts in its settings; leave it on the default (the model for judgments) or pick another for that routine alone, and its thinking level beside it.

Rules and approvals do not change with the model: every tool call still goes through Pimpo. With Anthropic, the instructions, tool list and conversation so far are kept in the provider's prompt cache between turns, so a long task pays about a tenth for what it already sent; the cost shown includes the cache's own prices. When a conversation or job with an Anthropic model grows very long, Anthropic summarizes its older parts on its servers so it can go on (Settings › Models › Summarize long conversations, on by default, with the size where it starts); the summary is counted in the cost.

The providers' lists are live: each provider's models come from the provider itself, kept for a day, and Look again asks at once. A model a provider has just started offering is marked New (New · price unknown until you type its price). One of your models the provider no longer offers is marked Retired, and the jobs, chats and routines that use it suggest choosing another.

Downloading models

Settings › Models › Download models downloads models that run on this computer and shows each download as it happens, with its size, progress and a cancel button:

• Voices for reading aloud (the voice engine comes with the first one). Every file comes from a pinned address and is checked against its SHA-256 before it is unpacked, and unpacks only inside its own folder (~/.pimpo/local). They are not included in backups; download them again on a new computer.
• Speech to text (optional): a Whisper model (base, small or turbo) understands your Telegram voice notes and dictation in the app right here; without one, Pimpo uses whisper.cpp if it is installed. Voice notes in OGG need ffmpeg (brew install ffmpeg).
• Language models through Ollama (which must be installed and open), with suggestions that fit this computer's memory, or any model name. Once downloaded, choose it under On this computer › Ollama.

From the terminal, pimpo local list shows the catalog and what is installed, and pimpo local install ID downloads with the same checks. The list comes from a JSON catalog built into Pimpo (internal/local/catalog.json). A catalog.json of your own in ~/.pimpo/local replaces it; every entry needs an https address, its size and its SHA-256.

Costs

Cost shows what you spent today, this month and on what. Claude Code signed in with a Claude plan and Codex signed in with ChatGPT are paid by your subscription: they spend no money and do not count toward the daily limit. Through your subscription shows what the same work would have cost on the API, for reference. The daily limit (Settings) is checked before every model call; routines barely spend anything.