pitupitu

<p align="center"> <a href="https://pitupitu.chat"><img src="assets/banner.png" alt="pitupitu: talk to your agents. Start, check on and unblock Claude Code and Codex by voice, from your phone, on any of your machines." width="100%"></a> </p> <h1 align="center">pitupitu</h1> <p align="center"> <b>Talk to your coding agents, on any of your machines.</b><br> Start, check on and unblock Claude Code and Codex by voice, from your phone or any browser.<br> This is the open-source agent that links each of your machines to <a href="https://pitupitu.chat">pitupitu</a>. </p> <p align="center"> <a href="https://github.com/klarluft/pitupitu/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/klarluft/pitupitu?label=release&color=c8371f"></a> <a href="https://github.com/klarluft/pitupitu/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/klarluft/pitupitu/actions/workflows/ci.yml/badge.svg"></a> <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue"></a> <a href="#install"><img alt="Platforms: macOS and Linux" src="https://img.shields.io/badge/platforms-macOS%20%C2%B7%20Linux-555"></a> <a href="https://github.com/klarluft/homebrew-tap"><img alt="Homebrew tap" src="https://img.shields.io/badge/homebrew-klarluft%2Ftap-f6a316"></a> <a href="https://www.rust-lang.org"><img alt="Written in Rust" src="https://img.shields.io/badge/made%20with-Rust-dea584"></a> </p> <p align="center"> <a href="https://pitupitu.chat">Website</a> · <a href="#install">Install</a> · <a href="#how-it-works">How it works</a> · <a href="#commands">Commands</a> · <a href="docs/box-link.md">Protocol</a> · <a href="https://pitupitu.chat/privacy">Privacy</a> · <a href="SECURITY.md">Security</a> </p>

---

You say what you want done and where. pitupitu starts the agent session on that machine, keeps an eye on it, answers what it can, and tells you when it is done or needs you. In the car, on a walk, at the desk: the same sessions, from your phone or any browser.

pitupitu runs your agents in herdr, a terminal workspace manager for coding agents. Open herdr on that machine and you see exactly what your phone sees: the same sessions, live, to watch or type into at the desk. If herdr is not installed, pitupitu installs it.

This repository is the part that runs on each of your machines: a small Rust agent that links the machine to pitupitu cloud over one outbound WebSocket. The conversation, the voice and the page at pitupitu.chat are the hosted service.

<table> <tr> <td width="33%"><img src="assets/talk-phone.png" alt="The Talk screen on a phone: a conversation with pitupitu, and the line above the microphone naming the session that needs you"></td> <td width="33%"><img src="assets/work-phone.png" alt="The Work screen on a phone: what needs you first, then what runs, on every machine"></td> <td width="33%"><img src="assets/session-phone.png" alt="A session that asks: the question at the top, the answers as buttons, the terminal under it"></td> </tr> <tr> <td><b>Talk.</b> Say it; it starts. The line above the microphone names what needs you.</td> <td><b>Work.</b> What needs you first, then what runs, on every machine.</td> <td><b>A session that asks.</b> The question at the top, the answers as buttons, the terminal under it.</td> </tr> </table> <p align="center"> <img src="assets/talk-desk.png" alt="pitupitu on a wide screen: the work beside the conversation" width="100%"> <br>_{<b>On a wide screen.</b> The work beside the conversation; open <code>herdr</code> on the machine for the same sessions in your terminal.} </p>

Quick start

curl -fsSL https://pitupitu.chat/install | sh   # or: brew install klarluft/tap/pitupitu
pitupitu setup                                  # sign in with a code, pick a folder, start the service

Then open pitupitu.chat/app on your phone and say what you want done. You need claude and/or codex (or another agent herdr knows) installed and signed in on that machine; pitupitu never touches their logins.

How it works

phone / browser ──▶ pitupitu.chat (cloud) ◀── box link (outbound WebSocket) ── pitupitu ──▶ herdr ──▶ your agents
                                                                                              ▲
                                                                   you, at the desk: `herdr` ─┘

• The box agent dials out to wss://api.pitupitu.chat/v1/box. Nothing connects in: no open port, no VPN, no certificate on your machine.
• The cloud can ask for a fixed set of operations only, served through herdr: list, open and close workspaces and tabs, stop a session you asked it to stop, start an agent in a pane, send it a prompt or keys, read its screen, wait for it; and update this agent or herdr when you say so. There is no shell and no arbitrary command. The full list is in docs/box-link.md and in calls.rs.
• Your agents run as they always do, your own unmodified claude and codex (or any agent herdr supports) signed in by you, on your own subscriptions or keys, in your own permission mode. pitupitu never reads, sees or uses their credentials.
• herdr's server: the box agent starts herdr server when none is running (at its own start, and whenever herdr stops answering) and never stops it. It runs on its own, so restarting or updating the box agent leaves your sessions running. Open herdr and you attach to that same server; if you opened herdr first, pitupitu uses yours.
• Where sessions go: a project gets a herdr workspace labelled after it, as you would make one; quick work in the pitupitu home folder (a lookup, a question) goes into tabs of one pitupitu workspace, so yours are not littered with them.
• From your files, only skills/*/SKILL.md in the pitupitu home folder are sent, plus what the box reports about itself: its version and herdr's (and whether newer ones exist), which agent CLIs are installed (with their versions), and the folders your agents worked in recently (only the folder paths and when, read from the agents' own session history; nothing else from those files). With history on, which it is unless you switch it off, more of that history is sent: see History.

Install

curl -fsSL https://pitupitu.chat/install | sh

or with Homebrew (macOS and Linux):

brew install klarluft/tap/pitupitu
pitupitu setup

or build from source with a recent stable Rust:

cargo install --git https://github.com/klarluft/pitupitu pitupitu

Release binaries are built for Linux (x86_64, arm64, static musl) and macOS (Intel, Apple silicon) and come with SHA-256 checksums on the releases page.

The install script and pitupitu setup install herdr with its own installer when it is not on your PATH. A herdr you installed with Homebrew, mise or Nix is used as it is. You need claude and/or codex (or another agent herdr knows) installed and signed in.

Set up

pitupitu setup

It asks a few plain questions; pressing Enter takes the suggested answer.

1. Sign in: it shows a code; approve it on any screen at pitupitu.chat. To sign in from your phone, scan the QR code setup shows with its camera (--no-qr leaves it out). The box gets its own key, stored in ~/.config/pitupitu/pitupitu.toml (readable only by you). An account can have many boxes, each named (the hostname by default, --box to choose); setting up the same box again replaces its old key.
2. pitupitu's folder (the home folder): ~/pitupitu by default. Requests that belong to no project run there, and skills/<name>/SKILL.md holds routines you name by voice. What pitupitu should know about you ("client work goes on the work laptop", "I use Codex for reviews") is your preferences, kept in your account: pitupitu prefs edit, the page, or just tell pitupitu "remember that …". (A PITUPITU.md from 0.1 is no longer read; copy anything useful into pitupitu prefs.)
3. Your agents can change pitupitu's settings (asked once, yes by default): installs a skill that teaches Claude Code and Codex how, so you can ask your own agent to do it. pitupitu keeps its copies up to date as it updates.
4. History (not asked, on by default): setup says in one line that pitupitu keeps track of your projects by reading what your agents did on this machine, and where to switch it off. See History.
5. herdr, the small program your agents run inside: installed if missing (said in one line, not asked). Then, for the agents it finds, their sessions are set to come back after herdr restarts (herdr integration install claude and codex).
6. Starting by itself: pitupitu starts now and whenever you log in (a user service running pitupitu connect: systemd on Linux, launchd on macOS). On Linux, setup asks once whether to keep it running while you are logged out, so your phone still reaches the machine and it comes back by itself after a restart; yes by default (loginctl enable-linger). --linger / --no-linger answer for a script.

Then open pitupitu.chat/app.

Commands

| | | |---|---| | pitupitu setup | sign in, pitupitu's folder, herdr, starting by itself (--home, --relink, --box, --no-service, --no-browser, --no-qr, --linger, --no-linger) | | pitupitu connect | hold the link open in the foreground (what the service runs) | | pitupitu status | account, home folder, herdr (version, server, newer release), agents found, service and version as this box sees them | | pitupitu settings | your preferences, default box, agent and models, updates, voice, and every box with its note, on/off, agent and history | | pitupitu prefs | show your preferences; prefs edit, prefs set <file> (- for stdin), prefs clear | | pitupitu box note <text> | one line about this box ("client work, Acme"); --clear | | pitupitu box rename <name> | what you call this machine when you talk; also on the talk page (tap the machine) | | pitupitu box history on / off | let pitupitu read what your agents did on this machine, or stop it (History); on by default | | pitupitu box on / box off | off: stays linked, but pitupitu starts nothing here and ignores its sessions until on again | | pitupitu default <box> | the box used when you don't say which; --clear and pitupitu asks | | pitupitu updates mine\|all\|quiet | what pitupitu brings up between turns unasked: the sessions you follow (default; its own tasks are followed from the start, yours once you pitupitu follow them), every session, or nothing unless asked | | pitupitu agent claude\|codex\|auto | the agent a session gets when you don't say (auto: what the machine has, Claude first); pitupitu box agent … for this machine only | | pitupitu model <agent> <model> | the model that agent runs on when you don't say (pitupitu model claude opus); --clear for its own default | | pitupitu follow [<session>] | follow a session: pitupitu tells you when it finishes or needs you. Run it in a session in herdr, or name one by its title or id; --off or pitupitu unfollow to stop. pitupitu sessions lists this machine's sessions and which are followed | | pitupitu place add <name> <path> | a folder on this machine with a name you say ("in acme, run the tests"); place rm <name>, pitupitu places lists them all | | pitupitu todo | your list: todo add <text> (--here for this repository, --project), pitupitu idea <text>, todo done\|drop\|reopen\|rm <id or words>; pitupitu todo lists the open items (--all, --done, --ideas, --here, words) | | pitupitu remind <when> <text> | a reminder, the t