Pyunto Diary

pyunto-agent

外部エージェントをPyunto交換日記のパートナーにします。エージェントは一般のメンバーです。 エージェント自身のPyuntoアカウントとX25519 IDキーを持ち、通常の招待リンクで招待されます。 サーバーに変更はなく、平文を見ることもありません。復号はこのプロセス内で行われます。

iPhoneおよびiPad向けPyunto · Android向けPyunto · pyunto-robotics — 同じアイデアを、もう一方に ロボットを置いて実現しています（動画を見る（100秒））

モデルにClaude Codeを使った実際の動作例です。Markdownファイルに筋力コーチのペルソナを設定し、 クライアントがスマートフォンからセッションを記録します。2回目の返信では前日と比較します。 90秒の全編動画を見る。

---

エージェントの2つの種類

同じパッケージ、同じアカウント、同じキー。異なるのは、誰が会話を始めるかです。

1. エージェント — ユーザーにメッセージを送ります

あなたが書くと、同じスレッドでエージェントが促されることなく返信します。

     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)

招待方法： pyunto-agent pair を実行し、アプリで QR コードをスキャンして、日記を選びます。 承認すると、エージェントはすぐに返信を始めます。

用途： 人々がすでに利用している場所で、サービスを提供することです。

汎用チャットボットは、誰かが覚えていてアクセスしなければならないウェブサイトであり、ユーザーについて何も覚えていないタブの中にあります。こちらは、ユーザーのスマートフォンにあるメッセージアプリの登録済み連絡先です。ユーザーがこれまでに書いたことをすべて読み、その人物像をあなたが設定したとおりに返信します。

その人物像はファイルです。--persona coach.md を指定するだけで、丁寧なアシスタントが、お金を払う価値のあるサービスに変わります。

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

この仕組みの活用例：

サービス	チャットボットにはできない、ペルソナの役割
🏋️ ストレングスコーチ	数値を尋ね、先週の数値を覚え、トレーニングを休んでも褒めません
🗣️ 語学チューター	すべてのメッセージを訂正し、学習者自身の間違いを記録し、難易度を上げていきます
🏥 クリニックの経過確認	術後の質問を毎日、順番に尋ね、看護師が確認すべき回答に印を付けます
🥗 栄養士	食事の写真を読み取り、その週の合計を記録し、個々の食事ではなく傾向に気付きます
📚 学習指導者	学生に復習スケジュールを守らせ、実際に何を学習したかを尋ね、「勉強した」という回答を受け入れません
🔧 物件管理者	入居者は問題が起きるたびに同じスレッドで報告できます。エージェントは内容を振り分け、写真を求め、必要に応じてエスカレーションします
📐 現場検査	エンジニアが現場の写真を撮ると、エージェントは案件に関連付けて記録し、不足している情報を尋ねます
📅 断酒・習慣のサポート	大切な時間に状況を確認し、継続日数を記録し、あなたが指示したとおりに再発に対応します

チャット画面ではなく、ここで機能する理由：

• ペルソナが一貫します。 ユーザーが話術で覆せるプロンプトではなく、あなたが管理するファイルです。
• 記憶します。 --history を指定すると、すべての返信で直近のスレッドが参照されるため、「先週の火曜日と同じ」という言葉にも意味があります。
• 相手のスマートフォンに届きます。 通知が届き、相手はすでに使っているメッセージアプリで返信できます。ログインもタブも、覚える必要のあるアプリもありません。
• あなたには何も見えません。 日記はエンドツーエンドで暗号化され、あなたが実行するプロセス内でのみ復号されます。身体や健康、金銭について相談するクライアントに対して、これは正当に伝えられることです。
• 1つのプロセスで複数のクライアントに対応できます。 --space を指定しない場合、pyunto-agent run はアカウントが招待されたすべての日記に返信します。つまり、クライアントのオンボーディングは QR コードをスキャンしてもらうだけです。1つのエージェントを1人のクライアントに固定するには --space を使います。

2. MCP — Claude に日記について尋ねる

バックグラウンドでは何も実行されません。Claude Code または Claude Desktop は、あなたが尋ねたときに日記を参照します。

     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     │  │
 │  └──────────────────┘  │
 └────────────────────────┘

招待方法： 以下の手順でサーバーを MCP クライアントに追加してから、Claude にペアリングを依頼します。pair ツールに表示される QR コードを Pyunto アプリでスキャンします。ターミナルでの操作は不要です。

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

用途： 日記を記憶として活用することです。数か月分の記録を検索したり、1週間分を要約したり、デスクトップから記録を書き込んだり、Claude が回答する前に過去の記録を確認させたりできます。やり取りは毎回あなたが始めるため、頼んでいないのに話しかけてくることはありません。

どちらを選ぶ？

	エージェント（run）	MCP（mcp）
誰が最初に話しかけるか	エージェント	あなた
バックグラウンドで実行されるか	はい、継続的に	いいえ、依頼されたときだけ
どこで利用者が話しかけるか	Pyunto アプリ（利用者のスマートフォン上）	Claude Code / Desktop
誰のためのものか	サービスとその利用者	個人と、その人自身の日記
一般的な用途	コーチ、家庭教師、質問に答える窓口	記録の検索と要約

どちらも同じ日記に同時に連携できます。同じアカウントなので、run がスマートフォンで回答しながら、mcp がデスクで同じ記録を読み取ることもできます。

3つ目の種類は別の場所で動作します。 pyunto-robotics は、言語モデルの代わりにもう一方の端にロボットを配置します。「日光を探しに行って」と書くと、シミュレーション上、または実際の機械がそれを実行し、写真を添えて報告します。このパッケージを基盤としており、同じ方法で連携できます。

クイックスタート：クライアントからメッセージを受け取るパーソナルトレーナー

何もない状態からクライアントのスマートフォンで使えるようにするまで、実際のサービスを構築します。

1. インストール

Python 3.11 以降が必要です。仮想環境にインストールしてください。Homebrew の Python ではグローバルな pip install が拒否されます（externally-managed-environment）。

python3.12 -m venv ~/pyunto-env
source ~/pyunto-env/bin/activate
pip install 'pyunto-agent[qr]'

次に、返信に使用するものを選びます。

export ANTHROPIC_API_KEY=sk-ant-...    # the Claude API (used below), or
claude --version                       # Claude Code, if installed: no API key needed

Claude Code を使う場合は、以下の --backend claude-api を --backend command --command 'claude -p --output-format json' に置き換えてください。どちらも設定されていない場合、pair と run はその旨を伝え、QR コードを表示する前に選択肢を一覧表示します。

2. トレーナーを書く

このファイルがサービスになります。トレーナーの性格や、厳しさや優しさ、譲らない点、見過ごさない点はすべてここに記述します。クライアントがそれを話し合いで変えることはできません。

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. 配布用の QR コードを作成する

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.

画像を予約ページや歓迎メールに掲載するか、受付でカードに印刷して配布してください。秘密情報ではなく、有効期限もありません。同じ画像をすべてのクライアントが使えます。スキャンするとできるのは、あくまで参加をリクエストすることだけです。各クライアントは、自分のスマートフォンで自分の日記への追加を承認し、参加する前に誰が運用しているかを確認できます。

印刷用、または Pillow がインストールされていない場合は、.png の代わりに .svg を使用してください。

4. 返信を開始する

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

最初に、アクセスできる日記をすべて表示するので、どの日記に参加できたかを確認できます。

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)

1つのプロセスで、コードをスキャンしたすべてのクライアントに対応します。クライアントが次のように書き込むと、

ベンチプレス 80kg 5x5、最後のセットは重く感じた

トレーナーは、先週の重量を確認したうえで、その人の日記に返信します。返信は、使い慣れたアプリ上で、スマートフォンへの通知として届きます。

各クライアントの日記は個別に分かれており、エンドツーエンドで暗号化されています。復号は、実行しているプロセス内でのみ行われます。Pyunto のサーバーが内容を見ることはありません。

まずは自分で試してみますか？

ペルソナの設定は省略し、画像を使わずに連携してください。QR コードがターミナルに表示され、スキャンするとすぐにエージェントが返信を開始します。

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

次に、アプリでそのスペースを一度開いてください（これによりエージェントに鍵が渡されます）。その後、記録を書き込みます。

誰に返信するか、メンバーには何が見えるか

• 1人とエージェントの日記では、すべての記録に返信します。
• 3人以上のメンバー（エージェントを含む）がいる場合は、名前で呼びかけられたとき、または全員宛ての記録が送信されたときだけ返信します。別の相手に宛てた記録では起動しません。
• 別のエージェントやロボットが書いた記録に返信するのは、このエージェントの名前（@Claude）が含まれている場合だけです。ロボットの報告や別のエージェントのチェックインには返信しないため、同じ日記にいる2つのプログラムが、参加者の会話に割り込んだり、互いに応答し続けたりすることはありません。
• ロボット（pyunto-robotics）の動作条件はさらに厳格です。人が書いた記録に限り、名前で呼びかけられた場合だけ動作します。
• すべてのメンバーは、アプリの参加者一覧で、エージェントの運用者（--operator）と日記の復号場所（デフォルトは self_hosted）を確認できます（--runtime）。

詳細

エージェントがすでに日記に参加している場合、pair はその旨を伝えて待機します。コードをスキャンして別の日記に追加するか、Enter キーを押して現在参加している日記をそのまま使ってください。

自分で後から起動する場合は、--no-run を追加すると、QR コードを表示して終了します。QR コードに秘密情報は含まれません。参加を求めているアカウント名が記載されており、承認するかどうかはスマートフォンを持っている人が決めます。

PYUNTO_EMAIL を設定していない場合、エージェントは PYUNTO_AGENT_NAME（デフォルトは "Claude"）という名前の匿名アカウントを使用します。デバイス ID とアイデンティティキーは ~/.pyunto-agent/ に保存されます。

クローンせずにインストールする

エージェントを実行するだけで、開発には参加しない場合は、クローンせずに次の1行で実行できます。

pip install 'pyunto-agent[qr]'
pyunto-agent pair --operator "your name"

最新の未リリースコードを実行する場合は、次のとおりです。

pip install 'pyunto-agent[qr] @ git+https://github.com/utagoeinc/pyunto-agent'

詳しいガイド

• GUIDE.md — ターミナルを使い慣れていない人向けに、セットアップ全体を手順ごとに説明しています。API キーの代わりに Claude Code（claude -p）を使用します。
• DEPLOY.md — コンテナ内でサーバーと並行して pyunto-agent serve を実行する方法を説明しています。

アプリからペアリングする場合

誰かがエージェントをセットアップしてくれた場合は、逆の手順で進めます。

1. Pyunto アプリで共有スペースを作成または開き、招待リンクを生成します。
2. pyunto-agent join 'pyunto://invite/…'
3. アプリでスペースを一度開き、スペースキーをエージェントのアイデンティティキーと共有します。
4. pyunto-agent whoami を実行すると、そのスペースで key=yes と表示されます。

写真、動画、ドキュメント

エージェントは、ユーザーが入力した内容だけでなく、添付したファイルも読み取ります。各写真、動画、ドキュメントはダウンロードされ、マシン上の ~/.pyunto-agent/attachments/ に復号されてから、モデルに表示されます。

添付ファイル	Claude API（claude-api）	Claude Code（command）	http
写真	画像そのもの	ファイルパス。Claude Code が開きます	パス + data_base64
動画	間隔を均等にした4つのフレーム（ffmpeg が必要です）	ファイルとそのフレーム	パス + data_base64
PDF	PDF そのもの	ファイルパス	パス + data_base64
テキスト、Markdown、CSV	テキスト	ファイルパス	パス + data_base64
Word、Excel、PowerPoint	テキスト（pip install 'pyunto-agent[docs]'）	ファイルパス	パス + data_base64

そのため、ドキュメントを添付して「これの文法をチェックしてくれますか？」と頼んだり、写真を3枚添付して「庭についてどう思いますか？」と尋ねたりすれば、期待どおりに動作します。いくつか詳細を説明します。

• 写真の直後にキャプションが独立したエントリーとして追加されます。エージェントは写真の後に数秒待ってから、写真とキャプションをまとめて一度だけ回答します。
• 各返信でモデルに表示されるのは、スレッド内の最新4件の添付ファイルのみです。
• Claude Code の場合、添付ファイルのフォルダーは自動的に --add-dir で渡されるため、ファイルを開くことができます。
• テキストと同様に、モデルに表示される内容はそのモデルのプロバイダーに送信されます。日記の参加者にそのことを伝えてください。

エージェント：Claude API の返信

pyunto-agent run --backend claude-api --persona persona.md   # replies, phone notification
pyunto-agent run --backend claude-api --silent               # replies, no notification
pyunto-agent run --backend claude-api --dry-run                     # log replies, do not post

エージェント：パートナーとしての Claude Code

pyunto-agent run --backend command --command 'claude -p --output-format json'

コマンドには標準入力でプロンプトが渡されます（ペルソナ、これまでのスレッド、prompt を含む JSON）。標準出力が返信として使われます（{"result": …}、{"reply": …}、またはプレーンテキスト）。プロンプトを引数として渡すには、コマンドに {prompt} を追加してください。

MCP：Claude 向けツールとしての Pyunto

公式 MCP Registry に com.pyunto/diary（Pyunto Diary）として掲載されています。uv で実行でき、ほかにインストールするものはありません。

Claude Code

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

Claude Desktop（claude_desktop_config.json）および Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "pyunto-diary": { "command": "uvx", "args": ["pyunto-agent", "mcp"] }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "pyunto-diary": { "type": "stdio", "command": "uvx", "args": ["pyunto-agent", "mcp"] }
  }
}

次に「私の Pyunto ダイアリーとペアリングして」と言ってください。Claude が pair を呼び出して QR コードを表示します。アプリでスキャンし、ダイアリーを選択して承認したら、キーを共有するためにアプリでそのダイアリーを一度開きます。

ツール	機能
pair	アカウントを自分のダイアリーのいずれかに追加するための QR コードを表示します
whoami、list_spaces、list_members	アカウント、そのダイアリー、および各ダイアリーの参加者（エージェントを実行している人も含む）を確認します
list_threads、read_thread	このマシン上で復号したエントリーを読み取ります
read_attachment	写真（画像として）、動画（フレームとして）、またはドキュメント（テキストとして）を読み取ります
wait_for_message	誰かが書き込むまで待機します
post_entry、react、post_sticker、post_list_item	ダイアリーに書き込みます
quick_list_stats	期間内に各クイックリスト項目が記録された頻度を確認します
join_space	アプリで作成した招待リンクまたはコードから参加します

Claude Code での最小限の自律ループは次のとおりです。

> Use wait_for_message, then reply with post_entry in the same thread. Repeat.

ダイアリーのパートナーがチャットモデルにはできないことを言える理由は、次の 2 つにあります。

quick_list_stats は、服用した薬、子どもに読んだ本、食事、散歩など、ダイアリーで記録される繰り返しの項目を期間内で数えます。これにより、エージェントは質問する代わりに「今週で 3 回目ですね」と言えます。集計は復号したエントリーを使ってユーザーのマシン上で作成されます。サーバーにはこれらの投稿が暗号文として保存されるため、どのエンドポイントでも集計に回答できません。

list_members は、スペースに誰がいるか、また各エージェントを誰がどこで実行しているかを示します。機密情報を書き込む前に呼び出すと、投稿を誰が読めるかを確認できます。

@pyunto/tm-mcp と組み合わせると、パートナーは人間のスケジュールを読んだり、予定を入れたりすることもできます。

リファレンス

コマンド	動作	オプション
pair	QR コードを表示します。スキャンした人がエージェントを日記に参加させます。その後、投稿に返信します	--operator NAME（すべてのメンバーに表示）、--runtime self_hosted|hosted|endpoint、--image FILE.png|.svg（コードをファイルに書き込んで終了）、--big（ターミナルに大きな QR コードを表示）、--no-run（ペアリング後に終了）、および run のオプション
run	エージェントが参加しているすべての日記の投稿に返信します	--backend claude-api|command|http、--command CMD、--url URL、--model ID、--persona FILE.md、--space ID（繰り返し指定可能。指定した日記のみ）、--history N（コンテキストとして使う投稿数。デフォルトは 12）、--silent（通知なしで投稿）、--dry-run（返信をログに記録し、投稿しない）
mcp	Claude Code / Claude Desktop 用の stdio 経由 MCP サーバー
whoami	エージェントのアカウントと、各スペースの key=yes/no の状態を表示します
join LINK	アプリで作成した招待リンクから参加します
send SPACE_ID TEXT	投稿を 1 件送信します	--thread ID、--silent
serve	他のユーザーに代わってエージェントを実行する HTTP サービスです（DEPLOY.md を参照）	--listen HOST:PORT（デフォルトは 127.0.0.1:8788）、および run のオプション

バックエンド：claude-api には ANTHROPIC_API_KEY が必要です。command はプロンプトを JSON として stdin で任意のプログラムに渡し、その stdout を返信として使用します（claude -p --output-format json は Claude Code です）。http は同じ JSON を --url に POST します。

環境変数または作業ディレクトリ内の .env ファイルで設定します。

変数	意味
ANTHROPIC_API_KEY	--backend claude-api 用
PYUNTO_EMAIL、PYUNTO_PASSWORD	匿名アカウントの代わりに登録済みアカウントで実行します
PYUNTO_AGENT_NAME	匿名アカウントの表示名（デフォルトは Claude）
PYUNTO_AGENT_DIR	デバイス ID、ID キー、スペースキーの保存場所（デフォルトは ~/.pyunto-agent）
PYUNTO_BACKEND、PYUNTO_COMMAND、PYUNTO_BACKEND_URL、PYUNTO_MODEL	--backend、--command、--url、--model のデフォルト値
PYUNTO_PERSONA	--persona のデフォルト値
PYUNTO_HISTORY	serve 専用：コンテキストとして使う投稿数（デフォルトは 8）
PYUNTO_AGENT_LISTEN、PYUNTO_AGENT_SECRET	serve 専用
PYUNTO_BASE_URL	API サーバー（デフォルトは https://api.pyunto.com）

各バージョンの変更内容は リリース に記載されています。

注意事項

• 日記のテキストは、選択したバックエンドに送信されます。claude-api の場合、Anthropic の API に送信されます。そのことを日記の参加者に伝えてください。
• レート制限：デフォルトでは 1 時間あたり 60 件の返信です（Bridge(max_replies_per_hour=…)）。
• エージェントが日記を読めるのは、メンバーがスペースキーを共有した後のみです。メンバーがスペースを開くと、アプリがキーを共有します。whoami に key=no と表示される場合は、アプリでスペースを開いてください。
• テストベクトルを含む暗号化の仕組みについては、https://pyunto.com/encryption.html を参照してください。
• テスト：pip install -e '.[dev]' を実行してから pytest を実行します（シールドボックスのテストベクトルを含みます）。

ライセンス

Apache-2.0。LICENSE を参照してください。