pitupitu

Talk to your coding agents, on any of your machines.
Start, check on and unblock your coding agents (Claude Code, Codex, Kiro CLI, OpenCode, pi, Qwen Code, Cline, Kilo Code and others) by voice, from the iPhone or Android app or any browser.
Your agents run on the subscriptions you already pay for: Claude Code on your Claude plan, Codex on your ChatGPT plan. No API keys.
This is the open-source agent that links each of your machines to pitupitu.

  

Website · Install · How it works · Commands · Protocol · Privacy · Security

---

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 TUI, herdr's terminal app: a terminal workspace manager for coding agents, the herdr command. 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 it is not installed, pitupitu installs it. The Herdr desktop app is a separate program on its own runtime: pitupitu does not use it, and sessions pitupitu starts do not appear in 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, the apps and the page at pitupitu.chat are the hosted service.

Talk. Say it; it starts. The line above the microphone names what needs you.	Work. What needs you first, then what runs, on every machine.	A session that asks. The question at the top, the answers as buttons, the terminal under it.

_{On a wide screen. The work beside the conversation; open herdr on the machine for the same sessions in your terminal.}

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 the iPhone or Android app, or pitupitu.chat/app in any browser, and say what you want done. You need a coding agent installed and signed in on that machine (Claude Code, Codex, Kiro CLI, OpenCode, pi, Qwen Code, Cline, Kilo Code, or another agent herdr runs); pitupitu never touches their logins. For Kilo Code, use its own installer (curl -fsSL https://kilo.ai/cli/install | bash): the npm package runs under a name herdr does not recognise yet.

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, codex, opencode or any other agent herdr supports, signed in by you, on your own subscriptions (Claude Code on your Claude plan, Codex on your ChatGPT plan) 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. A server pitupitu starts gets what a terminal of yours would give it, since every pane inherits it: your login shell's environment and, on WSL, Windows interop (code, explorer.exe), the Windows PATH and WSLg's display and sound.
• 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.
• For each running agent the box sends what herdr says of it: its kind, name, status, folder, and which of the agent's own sessions it is (the session's id, or the path of its log), so a closed session can be picked up again. Only that id or path, nothing from inside the session, and it is sent whether History is on or off.
• 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 models each offers here, from the agents' own model lists; see Harnesses), 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 TUI (the herdr command, not the desktop app) 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 your agents how (in their own skill folders: Claude Code's, Codex's, Kiro CLI's, and ~/.agents/skills, which OpenCode, Kilo Code, pi, Qwen Code and Cline read), so you can ask your own agent to do it. pitupitu keeps its copies up to date as it updates.
4. Which agent to use (asked only when the machine has more than one coding agent and your account has no default yet; none is suggested, and Enter leaves it for later): the one pitupitu starts when you don't say which. It is saved for your account, so other machines don't ask again; change it any time with pitupitu agent <name> (claude, codex, opencode, …, or auto). Without one, pitupitu asks the first time it matters.
5. 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.
6. herdr (Herdr TUI), the small program your agents run inside: installed if missing (said in one line, not asked). Then, for every agent it finds that herdr has an integration for, their sessions are set to come back after herdr restarts (herdr integration install claude, codex, opencode, kilo, pi, qwen, …).
7. 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.
8. Your folders, on macOS: macOS asks before a program opens your Desktop, Documents, Downloads or iCloud Drive, and agents running in a herdr that pitupitu started are asked about as pitupitu (in a herdr you opened from your terminal, as your terminal app). So that this comes up now, while you are at the Mac, and not later while you are away with only your phone, the service opens each folder once as it starts: click Allow. Release builds are signed, so the answer stays through updates. pitupitu status shows what was allowed; to change it: System Settings › Privacy & Security › Files and Folders › pitupitu.

Then open the iPhone or Android app, or pitupitu.chat/app in any browser.

Commands

pitupitu setup	sign in, pitupitu's folder, which agent to use, 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, and on macOS which folders pitupitu may open
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 <name>|auto	the agent a session gets when you don't say (claude, codex, opencode, pi, qwen, cline, kilo, …; auto: the one the machine has, and with several pitupitu asks); 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 show [<session>]	bring a session to the front in herdr on its machine. Run it in a session in herdr, or name one by its title or id; --box <name> for one on another of your machines, and pitupitu sessions --box <name> lists those
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 time first and quoted when it has spaces (pitupitu remind "tomorrow 9am" call the bank); it prints the time it understood. pitupitu when <phrase> only says what a time means
pitupitu schedule	your reminders and schedules; schedule add <when> --place <place> -- <prompt> starts a session then (or again and again: "every weekday 9am"), schedule digest <when> a summary of your work; both ask first (--yes for a script); schedule pause|resume|rm <id>, schedule snooze <id> <when>
pitupitu --skill	print the skill for agents; pitupitu skill install puts it in ~/.claude/skills and ~/.codex/skills, and the service keeps pitupitu's own copies up to date when it starts (a copy you wrote yourself is left alone); pitupitu skill status shows each copy
pitupitu update [box|herdr|all]	show the newer release and what is running, ask, then install it the way it was installed; sessions keep running (--check only looks, --yes for a script, --handoff restarts herdr's server too, --no-restart)
pitupitu uninstall	stop and remove the service; config, home folder and herdr stay

Every settings command takes --json and never prompts without a terminal, so your agents can run them.

Logs: journalctl --user -u pitupitu -f on Linux, ~/Library/Logs/pitupitu.log on macOS. They carry what happened (connected, which call failed and why), never your prompts or agent output. PITUPITU_LOG=debug for more.

To see a session at the desk, open herdr on that machine (or herdr --remote <machine> over SSH): pitupitu's sessions are there with yours.

Environment: PITUPITU_CONFIG (config file), PITUPITU_CLOUD_URL, PITUPITU_CLOUD_API_KEY, HERDR_BIN (the herdr binary, default herdr on PATH). PITUPITU_HERDR_SESSION points the box agent at a named herdr session instead of the default one; it is for tests.

History

Reading what your agents did is how pitupitu keeps track of your projects: it can tell you what you were doing on the laptop yesterday, or what is left on a project, including the sessions you started yourself. So it is on by default, for each machine on its own, and pitupitu setup asks nothing about it; it says so in one line and links pitupitu.chat/privacy.

What is read: your agents' own session logs on this machine, the sessions of the last 7 days, at most the newest 300, and git in the repositories they worked in. The logs are:

• Claude Code: ~/.claude/projects/*/*.jsonl
• Codex: ~/.codex/sessions/**/*.jsonl
• Kiro CLI: ~/.kiro/sessions/*/sess_*/messages.jsonl and the session.json beside it (its folder and title)
• pi: ~/.pi/agent/sessions/*/*.jsonl
• Qwen Code: ~/.qwen/projects/*/chats/*.jsonl
• Cline: ~/.cline/data/sessions/<id>/<id>.messages.json and the <id>.json beside it (its folder and title)
• OpenCode and Kilo Code: the session, message and part tables of ~/.local/share/opencode/opencode.db and ~/.local/share/kilo/kilo.db, opened read-only; no other table of those databases is ever queried
• Antigravity: ~/.gemini/antigravity-cli/brain/*/.system_generated/logs/transcript.jsonl, and of conversation_summaries.db beside brain, opened read-only, each conversation's folder and title
• Maki: ~/.local/state/maki/sessions/*.jsonl (or ~/.maki/sessions/*.jsonl)

What is sent:

• each session's folder, its repository (root, origin remote without any password in it, branch), when it ran and its title;
• what you typed, cut to 1000 characters, and what the agent answered, cut to 600;
• for each tool the agent used, its name and one target: the file it edited or read, or the first 120 characters of the command it ran;
• at most 32 KB per session: in a longer one the oldest turns are left out, except your first request;
• when pitupitu asks, for instance to talk you through a long report a session wrote: a session's whole last reply, its text only, redacted the same way, at most 64 KB;
• for the repositories those sessions worked in: the branch, HEAD, and the current branch's commits of the last 7 days (at most 50), with the subject line and how many files each changed.

Never read or sent: file contents, edits' text, command output and other tool results, the agents' thinking, subagents' transcripts, anything else in those agents' folders (their settings, credentials, the other tables of a database), credentials of any kind, author names or emails, diffs. Anything that looks like a key or password in what is sent becomes [redacted] first (sk-…, ghp_…, Bearer …, password=… and the like).

To switch it off: pitupitu box history off (or on the page). It stops at once, and the box removes its small record of what it already sent (history.json in its state folder); what pitupitu already stored is deleted on the app page, under What pitupitu knows. pitupitu box history on switches it back on, and pitupitu settings shows which it is for every machine. The exact format is in docs/box-link.md.

Updating

pitupitu never updates itself, or herdr. pitupitu status and the page at pitupitu.chat say when a newer release of either exists (the box asks GitHub a few times a day), and pitupitu can offer it when you talk. Then:

pitupitu update          # this box agent
pitupitu update herdr    # herdr
pitupitu update all      # both

Each shows the version it would install, what is running right now, and asks before doing anything. It updates the way the thing was installed: brew upgrade for a Homebrew install; for the box agent otherwise the release binary (checked against its SHA-256) in place of this one; for herdr otherwise herdr's own herdr update. A herdr installed some other way (mise, Nix) is left to that way.

Your sessions are not touched. The box agent's update restarts only the box agent; its link to the cloud drops for a few seconds. herdr's update replaces the binary and leaves the running server and its sessions as they are; the server runs the new version after it next restarts (pitupitu status says when one is waiting). pitupitu update herdr --handoff restarts it now, keeping the sessions (herdr's live handoff, best effort).

--check only looks; --yes answers for you, for a script; --no-restart leaves the running service on the old version until you restart it. Updating from the page or by voice runs the same, after you said yes. The cloud accepts the current and the previous box protocol; an older box is told to update.

Privacy and security

• The box only dials out; nothing listens on your machine, and the cloud can only make the named calls in docs/box-link.md.
• Your agents' logins stay yours: pitupitu never reads or uses their credentials, and never adds permission flags.
• Audio is never stored. Logs carry metadata only. What is kept, and how to delete it, is at pitupitu.chat/privacy.
• Found a security problem? See SECURITY.md.

Contributing

Issues and pull requests are welcome: see CONTRIBUTING.md for the checks, the release process and the DCO sign-off, and docs/sessions.md for what every session state means. This project follows the Contributor Covenant.

Licensed under the Apache License 2.0.

_{Apple and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries. App Store is a service mark of Apple Inc., registered in the U.S. and other countries. Google Play and the Google Play logo are trademarks of Google LLC.}