Pyunto Diary

pyunto-agent

Make an external agent the partner of a Pyunto exchange diary. The agent is an ordinary member: its own Pyunto account, its own X25519 identity key, invited with the normal invite link. The server is unchanged and never sees plaintext; decryption happens in this process.

Pyunto for iPhone and iPad · Pyunto for Android · pyunto-robotics — the same idea, with a robot at the other end (watch it, 100 s)

*A real run with Claude Code as the model: a strength-coach persona in a Markdown file, and a client logging sessions from their phone. The second reply compares with the day before. Watch the full 90-second video.*

---

Two kinds of agent

The same package, the same account, the same keys. What differs is who starts the conversation.

1. Agent — it writes to your users

You write; it replies, unprompted, in the same thread.

     your phone                     your computer

┌───────────────┐ ┌──────────────────────┐ │ Pyunto app │ │ pyunto-agent run │ │ │ │ │ │ "tough day │ ───────▶ │ reads the entry │ │ at work" │ encrypted │ decrypts it HERE │ │ │ │ │ │ │ │ │ ▼ │ │ "that sounds │ ◀─────── │ Claude API, or │ │ exhausting" │ encrypted │ Claude Code, or │ └───────────────┘ │ your own HTTP URL │ └──────────────────────┘ │ │ └──────── api.pyunto.com ──────┘ (ciphertext only, never plaintext)

How you invite it: run pyunto-agent pair, scan the QR code with the app, choose a diary. The agent starts answering as soon as you approve.

What it is for: running a service that reaches people where they already are.

A general-purpose chatbot is a website somebody has to remember to visit, in a tab with no memory of them. This is a named contact in a messaging app on their phone, who has read everything they wrote before, and who answers in character because you wrote the character.

That character is a file. --persona coach.md is the whole difference between a polite assistant and a service worth paying for:

You are a strength coach. Your client logs every session here.

• Hold them to the programme. If they skipped legs again, say so plainly.
• Always ask for the numbers: weight, sets, reps. A session without numbers is not logged.
• Compare against last week before you praise anything.
• No pep talk. One sentence of encouragement, only when it is earned.

pyunto-agent run --backend claude-api --persona coach.md

Some shapes this takes:

What makes these work here rather than in a chat window:

• The persona holds. It is a file you control, not a prompt the user can talk their way out of.
• It remembers. --history gives every reply the recent thread, so "the same as last Tuesday" means something.
• It is on their phone. A notification arrives; they reply in a messaging app they already have. No login, no tab, no app to learn.
• You see nothing. The diary is end-to-end encrypted and decrypted only in the process you run. That is a real claim to make to a client talking about their body, their health or their finances.
• One process, many clients. With no --space, pyunto-agent run answers every diary the account has been invited into, so onboarding a client is them scanning a QR code. Use --space to pin one agent to one client.

2. MCP — you ask Claude about a diary

Nothing runs in the background. Claude Code or Claude Desktop reaches into the diary when you ask it to.

     your computer

┌────────────────────────┐ │ Claude Code / Desktop │ │ │ │ ┌──────────────────┐ │ ▼ │ │ your phone │ │ "what did I write │ │ Pyunto app │ │ about the garden?" │ │ │ │ │ │ │ the same diary, │ │ ▼ │ │ read and written│ │ ┌──────────────────┐ │ │ from either end │ │ │ pyunto-agent mcp │──┼──────▶ │ │ │ │ read_thread │ │encrypt │ │ │ │ post_entry │ │ └──────────────────┘ │ │ ...12 tools │ │ │ └──────────────────┘ │ └────────────────────────┘

How you invite it: add the server to your MCP client (below), then ask Claude to pair: the pair tool shows a QR code to scan in the Pyunto app. No terminal step is needed.

claude mcp add pyunto-diary -- uvx pyunto-agent mcp

What it is for: using your diary as memory. Searching months of entries, summarising a week, writing an entry from the desktop, letting Claude check what you recorded before it answers. You start every exchange; it never speaks unasked.

Which one?

Both can be paired into the same diary at once — they are the same account, and nothing stops run answering on your phone while mcp reads the same entries from your desk.

A third kind lives elsewhere. pyunto-robotics puts a robot at the other end instead of a language model: you write "go and find some sunlight" and a simulated — or real — machine does it and reports back with photographs. It is built on this package, and pairs the same way.

Quick start: a personal trainer your clients message

Building a real service, from nothing to a client's phone.

1. Install

Python 3.11 or newer. Install into a virtual environment: Homebrew's Python refuses a global pip install (externally-managed-environment).

python3.12 -m venv ~/pyunto-env

source ~/pyunto-env/bin/activate pip install 'pyunto-agent[qr]'

Then choose where replies come from:

export ANTHROPIC_API_KEY=sk-ant-...    # the Claude API (used below), or

claude --version # Claude Code, if installed: no API key needed

With Claude Code, replace --backend claude-api below with --backend command --command 'claude -p --output-format json'. If neither is set up, pair and run say so and list the options before showing a QR code.

2. Write the trainer

This file is the service. Everything the trainer is — strict or gentle, what it insists on, what it refuses to let slide — is here, and your clients cannot talk it out of any of it.

cat > trainer.md <<'EOF'

You are a strength coach. Each client logs their sessions in this diary.

• Always ask for the numbers: exercise, weight, sets, reps. "I trained today" is not a log -- ask what they lifted.
• Compare against their recent sessions before responding. If the weight has not moved in three weeks, say so.
• If they skipped a session, ask what happened. Once. Then move on.
• No motivational speeches. One line of encouragement, only when the numbers earn it.
• Never give medical advice. Pain goes to a doctor, and say so plainly.
• Reply in the language they wrote in. Two to four sentences.

EOF

3. Make a QR code to hand out

pyunto-agent pair --operator "Sano Fitness" --image trainer-qr.png

Written to trainer-qr.png — send this to whoever should be able to reach the

agent. Each person who scans it lets 🤖 Claude into their own diary; the code names the account asking and nothing else.

Put that image on your booking page, in the welcome email, or printed on a card at the desk. It is not a secret and it does not expire: the same image works for every client. Scanning it only lets them *ask* — each client approves it into their own diary, on their own phone, and sees who is running it before they do.

Use .svg instead of .png for print, or when Pillow is not installed.

4. Start answering

pyunto-agent run --backend claude-api --persona trainer.md

It starts by naming every diary it answers in, so you can see which ones you were let into:

Answering in 2 diaries:

Sano Fitness - Aiko [2 members, answers every entry] 1552f3dc Sano Fitness - Ken [2 members, answers every entry] 3124f1b8 (cannot read it yet: open this space in the Pyunto app once)

One process serves every client who has scanned the code. A client writes:

Bench 80kg 5x5, felt heavy on the last set

and the trainer replies in their diary, having read what they lifted last week — as a notification on their phone, in an app they already have.

Each client's diary is separate and end-to-end encrypted. Decryption happens only in the process you are running; Pyunto's servers never see any of it.

Just trying it yourself?

Skip the persona and pair without an image — the QR code appears in the terminal, and the agent starts answering as soon as you scan it:

pyunto-agent pair --operator "your name"                       # with ANTHROPIC_API_KEY set

pyunto-agent pair --operator "your name" \ --backend command --command 'claude -p --output-format json' # or with Claude Code

Then open that space in the app once (that hands the agent the key) and write an entry.

Who it answers, and what members see

• In a diary with one person and the agent, it answers every entry.
• With three or more members (the agent counts), it answers only when it is mentioned by name, or when an entry is sent to everyone. An entry addressed to someone else does not wake it.
• An entry written by another agent or a robot is answered only when it names this agent (@Claude). A robot's reports and another agent's check-ins are not replied to, so two programs in one diary never talk over the people in it or to each other in a loop.
• A robo