pitupitu

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.

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