Patricia

[!NOTE] このリポジトリは bettergroupinc/patricia-monorepo から plugins/patricia/ に生成されています。 自動化によって、この公開ミラーが同期されます。 ソースコミット: df2bda0088e804342599b2b58d411e65a4cfd8d7。 プルリクエストとイシューはモノレポで作成してください。

patricia Claude Code プラグイン

これを一度インストールすれば、エージェントは改めて指示されなくても Patricia の MCP サーバーを適切に使えます。

このプラグインには3つの要素があります。

1. ガイダンス。 5つのスキルで、Patricia の基本、オンボーディング、委任作業、インテグレーション、メモリブリッジを扱います。
2. MCP 接続。 インストールすると、OAuth サインイン用に Patricia の Streamable HTTP サーバーが設定されます。
3. 5つのローカルフック。 プロジェクトのオンボーディング、メモリの呼び出し、インテグレーションの事前確認、メモリのプッシュ提案を行います。Patricia に書き込むことはありません。

これは配布可能な Claude Code プラグインです。利用者が自分のマシンにインストールすると、その人の Claude Code セッションで動作します。Patricia の製品スキルカタログではなく、Patricia 内で実行されるものでもありません。

インストール

claude plugin marketplace add patricia-app/patricia-plugin
claude plugin install patricia@patricia

その後、新しいセッションを開始するか、/reload-plugins を実行してください。

このマーケットプレイスは https://github.com/patricia-app/patricia-plugin. です。ここにあるすべてのファイルは、Patricia のモノレポから自動生成されます。

コントリビューター向けの注意: モノレポは非公開です。アクセス権のあるコントリビューターは、モノレポ自体をマーケットプレイスとして追加できます。ルートの .claude-plugin/marketplace.json が patricia プラグインを ./plugins/patricia に指定しているためです。

インストールしてください。--plugin-dir で読み込まないでください。 ディレクトリから読み込んだプラグインではスキルは使えますが、フックは使えません。そのためガイダンスは機能しても、メモリブリッジは一度も実行されません。これは推測ではなく、実測で確認されています。--plugin-dir 経由で読み込んだプローブフックは一度も実行されませんでしたが、同じフックをプロジェクト設定で宣言すると、同じヘッドレスモードで同じ書き込み時に実行されました。Claude Code がプラグインの hooks/hooks.json を登録するのは、インストール済みで有効なプラグインに限られます。

claude plugin details patricia で、インストールされた内容を確認できます。

Component inventory
  Skills (5)  delegating-work, integrations, memory-bridge, onboard, using-patricia
  MCP servers (1)  patricia
  Hooks (5)  SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop

MCP サーバーにサインインする

このプラグインは、保存済みヘッダーなしで MCP サーバーを設定します。初回使用時に /mcp を実行し、Patricia を選択してください。ターミナルから OAuth フローを開始することもできます。

claude mcp login plugin:patricia:patricia

MCP の OAuth サインインと、フックで使う pat_mcp_ 個人トークンは別々の認証情報です。OAuth だけでは、トークンを必要とするフックは有効になりません。

OAuth が適さない場合は、代わりにトークンを使用してください。

claude mcp add --transport http patricia https://api.patricia.app/v1/mcp \
  --header "Authorization: Bearer $PATRICIA_MCP_TOKEN"

pat_mcp_ 個人トークンは責任者を特定し、書き込みができます。pat_live_ テナント API キーは利用者を特定しないため、読み取り専用であり、list_skills や list_integrations に応答できません。

ローカルフックに個人トークンを設定する

ローカルフックを使うには、python3 コマンドで Python 3 を利用できる必要があります。

Patricia の Settings > AI tools > Advanced > API keys で pat_mcp_ 個人キーを作成し、次のいずれかの方法で設定してください。

export PATRICIA_MCP_TOKEN="pat_mcp_..."

または、~/.claude/patricia.json に次のファイルを作成してください。

{
  "token": "pat_mcp_..."
}

PATRICIA_MCP_TOKEN はファイルより優先されます。PATRICIA_MCP_TOKEN が空の場合、ファイルへのフォールバックは無効になります。 これは意図した動作です。ファイルを移動せずに、認証が必要なフックを一時停止できます。

ワークスペースファイルを転送する

サーバーは39個のツールを公開しています。ファイル転送では、create_file、update_file、read_file の各モードを使用します。

• インライン書き込みには content または content_base64 を送信します。
• 直接アップロードには sha256、byte_size、content_type を宣言します。
• 1回限りの upload_id を使ってアップロードを完了します。
• メタデータと一時的な署名付き GET URL を取得するには read_file(as_download_url=true) を読み取ります。

作成の宣言には name と kind も必要です。更新の宣言には file_id が必要です。

宣言結果の JSON を file.pdf と同じ場所に declaration.json として保存します。 Bash、jq、curl を使って、返された upload_headers の各エントリを送信します。 署名は byte_size に紐付いています。Content-Length を指定して、正確にそのバイト数を送信してください。チャンク転送は失敗します。

declaration=declaration.json
file=file.pdf
mode=$(jq -er '
  if (.upload_id | type == "string" and length > 0) and has("upload_url") then
    if .upload_url == null and .already_stored == true then "reuse"
    elif (.upload_url | type == "string" and length > 0) and .already_stored == false
      and (.upload_headers | type == "object" and all(.[]; type == "string")) then "put"
    else error("Invalid upload declaration") end
  else error("Invalid upload declaration") end
' "$declaration") || { printf 'Invalid upload declaration.\n' >&2; exit 1; }
upload_id=$(jq -r '.upload_id' "$declaration") || exit 1
if [[ "$mode" == put ]]; then
  upload_url=$(jq -r '.upload_url' "$declaration") || exit 1
  headers=()
  while IFS= read -r header; do
    headers+=(--header "$header")
  done < <(jq -r '.upload_headers | to_entries[] | "\(.key): \(.value)"' "$declaration")
  status=$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
    --request PUT "$upload_url" "${headers[@]}" --data-binary "@$file") || exit 1
  case "$status" in
    2??|412) ;;
    *) printf 'Upload refused: HTTP %s\n' "$status" >&2; exit 1 ;;
  esac
fi
# A null upload_url skips the PUT and goes straight to completion.
printf 'Complete with upload_id %s before its expiry.\n' "$upload_id"

412 は、このキーへのバイトの保存がすでに完了していることを示します。有効期限が切れる前に upload_id を指定して完了処理を呼び出してください。 412 の後、完了処理で [invalid_arguments] が返された場合は終端状態です。コンテンツをインラインで送信するか、所有者に共有を依頼してください。宣言をやり直さないでください。

チェックサムは、SHA-256 ダイジェストの生バイトを Base64 エンコードしたものです。 アップロード URL が null の場合、Patricia はこの利用者が読み取り可能な有効なファイルのバイトを再利用できます。 完了処理では、アクセス権を再確認し、保存されたバイトを検証します。 作成の完了には upload_id のみを指定します。更新の完了には file_id と upload_id を指定します。 インラインフィールド、宣言フィールド、完了フィールドは分けてください。

完了処理は id、version、byte_size、sha256 と、利用可能な console_url を返します。 作成の完了では sharing_note も返されます。 ダウンロードモードでは id、version、byte_size、sha256、content_type、download_url と有効期限フィールドが返されます。 署名付き GET URL を使って、会話の外部でバイトをダウンロードしてください。 ダウンロード応答には、テキストまたは Base64 のコンテンツフィールドは含まれません。 レガシーのデータベースコンテンツでは [download_unavailable] が返されます。通常のテキスト読み取りは引き続き利用できます。

ローカルフック

5つのフックはすべてデフォルトで有効です。設定ファイルがない場合、またはフックのキーがない場合は、有効のままです。設定が不正な形式または読み取り不能の場合は、無効になります。特定のフックだけを無効にするには、~/.claude/patricia-plugin.json で、そのフックに記載されたキーをリテラル値 false に設定します。

オンボーディング

• 実行タイミングと動作: SessionStart は、新規または再開されたセッションで実行されます。接続中の利用者に挨拶し、プロジェクトごとに一度、オンボードスキルを案内します。
• コスト: トークンがある場合、whoami を1回呼び出します。ネットワークのタイムアウトは3秒、フックのタイムアウトは10秒です。
• 無効化: hooks.onboarding.enabled を false に設定します。
• プライバシー: トークンがある場合、認証済みの whoami リクエストのみがマシンの外部に送信されます。このフックを通じて、プロンプト、トランスクリプト、プロジェクトの内容が外部に送信されることはありません。

リコール

• 実行タイミングと動作: UserPromptSubmit は、送信された各プロンプトの前に実行されます。コマンド、短い返信、確認、コードのみの入力はスキップします。対象となるプロンプトに関連するメモリを追加します。
• コスト: トークンがあり、プロンプトが対象となる場合、search_memory を1回呼び出します。ネットワークのタイムアウトは3秒、フックのタイムアウトは8秒です。
• 無効化: hooks.recall.enabled を false に設定します。
• プライバシー: 折りたたんだプロンプトの最大300文字を Patricia に送信します。このテキストを送信するのは、トークンが設定されている場合のみです。

インテグレーションの事前確認

• 実行タイミングと動作: UserPromptSubmit はプロンプトを確認します。PreToolUse は、ツールの実行前に WebFetch、WebSearch、Bash の入力を確認します。ローカルカタログを使って既知のプロバイダーを特定します。
• コスト: MCP やネットワークの呼び出しは行わず、トークンも不要です。フックのタイムアウトは、プロンプトの場合は8秒、ツール呼び出し前は5秒です。
• 無効化: hooks.integrations_first.enabled を false に設定します。
• プライバシー: マシンの外部に送信されるものはありません。フックはプロンプトまたはツール入力をローカルで確認します。

メモリブリッジ

• 実行タイミングと動作: PostToolUse は、Write、Edit、または MultiEdit の後に実行されます。保存されたローカルメモリノートを検出し、明示的なスコープを指定した remember を提案します。
• コスト: MCP やネットワークの呼び出しは行いません。フックのタイムアウトは5秒です。
• 無効化: hooks.memory_bridge.enabled を false に設定します。従来の ~/.claude/patricia-memory-bridge.json ファイルで enabled を false に設定することもできます。
• プライバシー: スクリプトは保存されたノートをローカルで読み取り、ネットワーク経由では何も送信しません。ノートの内容は含めず、ノートのパスとリマインダーテキストを Claude Code に返します。

プッシュのリマインダー

• 実行タイミングと動作: Stop はエージェントの終了時に実行されます。ローカルメモリへの書き込みがあった場合、または Patricia へのメモリ書き込みがないままツールを使う実質的なセッションが行われた場合に、remember を提案します。
• コスト: MCP やネットワークの呼び出しは行いません。フックのタイムアウトは8秒です。
• 無効化: hooks.push_reminder.enabled を false に設定します。
• プライバシー: ローカルトランスクリプトを最大5 MBまで読み取りますが、何も送信しません。トークンが設定されている場合にのみ実行されるため、利用者が同意した後にメモリ呼び出しを実行できます。

ネットワークと認証情報

このプラグインは Streamable HTTP 経由で https://api.patricia.app/v1/mcp に接続します。

Patricia は PKCE S256 を使った OAuth 2.1 を使用します。OAuth フローが完了すると、クライアントに個人用の pat_mcp_ ベアラートークンが付与されます。

プラグインマニフェストに認証情報は含まれません。サインイン後、クライアントはベアラートークンを api.patricia.app に送信します。

その他のマーケットプレイス

• Cursor は、このパッケージの plugin.json と mcp.json を読み取ります。
• OpenAI Codex と ChatGPT は .codex-plugin/plugin.json を読み取ります。
• リモートソースのエントリにマニフェストは不要です。xAI は、存在する場合に .claude-plugin/plugin.json を読み取ります。

すべてのマーケットプレイスパッケージは、このパッケージ内の単一の skills/ ツリーを参照します。

assets/icon.png は、Patricia の公式ブランドアセットです。

メモリブリッジは提案するだけで、書き込みはしない

フックはシェルコマンドです。MCP クライアントを持たず、誰からも同意を得ておらず、ノートを読んでチームの情報と個人情報を区別することもできません。ローカルのノートをすべて共有ワークスペースに送るフックを配布すれば、マシン固有の使い捨てノートや個人的なノートが、何も知らせずにチーム全体に公開されてしまいます。メモリブリッジは、この問題を避けるために作られたものであり、後回しにした機能ではありません。

そのため、フックが行うのは1つだけです。ノートはローカルにのみ存在し、remember には scope が必要だとエージェントに伝える hookSpecificOutput.additionalContext を挿入します。エージェントがスコープを判断し、利用者に確認してから呼び出しを行います。判断と書き込みは、同じ場所にとどまります。

4つのゲートによって、不要な通知を防ぎます。

ゲート	効果
いずれかの対応設定で、ブリッジの enabled 値が false に設定されている	通知しません。この値がなければ、ブリッジは有効です。
書き込み先のパスがメモリディレクトリの外にある	通知しません。
書き込みが完了していない、またはファイルが空である	通知しません。
ノートのフロントマターに patricia: skip がある	通知しません。

また、同じノートをセッションごとに最大1回だけ提示します。そのため、Write の後に Edit が連続して呼び出されても、リマインダーは4回ではなく1回だけ表示されます。この記録は ~/.claude/patricia-memory-bridge-state/ に保存され、セッションごとに1ファイルが作成され、7日後に削除されます。

この処理には CLAUDE_PLUGIN_DATA を使いません。この変数はフックの環境に存在しますが、実行中のプラグイン自身のディレクトリを確実に示すものではありません。このマシンでは、プロジェクトレベルのフックでこの変数が無関係な別のプラグインのデータディレクトリである ~/.claude/plugins/data/codex-openai-codex に設定されていることが確認されました。

メモリ書き込みで実際に使われるツール

Claude Code 2.1.238 では、memory_list、memory_read、memory_write という名前のツールが宣言されています。このプラグインの開発対象となったマシンでは、メモリノートの書き込みにこれらのツールは使われていません。直近120件のセッショントランスクリプトを調べたところ、~/.claude/projects/*/memory/ への Write 呼び出しが49件、Edit 呼び出しが35件あり、memory_write の呼び出しは0件でした。

そのため、マッチャーは Write|Edit|MultiEdit です。memory_write は意図的に対象外にしています。ペイロードの形式が検証されていないツール用のマッチャーを追加しても、フックがひそかに一度も実行されず、正常に動作している場合と見分けがつかなくなるだけです。実際の memory_write ペイロードを確認したら追加してください。

ガイダンスとサーバーの恒常的なルールは、二重ではなく一つのコピー

start_onboarding_import は、ask_first、instruction、および他の誰かの CLAUDE.md に収まるサイズの markdown ブロックを含む standing_rule_to_offer を返すことがあります。スキルはそのブロックを繰り返しません。エージェントにツールを呼び出して返された内容を使うよう指示することで、その文言の管理元をサーバーに一本化しています。

インストール時に取得する方法も検討しましたが、うまくいきません。プラグインの SKILL.md はコンテンツアドレス指定キャッシュ内の静的テキストであり、インストール時に書き換える手順はありません。また、Patricia のセットアップを担うプラグインが、自身の説明を表示するために、認証済みの Patricia 接続が機能していることを前提にすることもできません。使用時にツールを読み取れば、こうした問題なしに同じ内容を一元管理できます。

ここに記載されているツール名はすべて実在するツールです

このプラグイン内のバッククォートで囲まれたすべてのツール識別子は、サーバー独自のツールレジストリ（サーバーが tools/list から構築する一覧）と照合されます。同じチェックでは、識別子が空でないことも確認するため、抽出処理が壊れて何も見つからなかった場合にチェックを通過することはありません。

コントリビューター向けメモ: このチェックはPatriciaのモノレポで backend/api/tests/test_patricia_claude_plugin.py され、このプラグインに変更があるたびに実行されます。

設定とファイルの検出

ツール	用途
get_settings	設定を一覧表示するか、選択したキーまたはグループについて、意味、値、権限を読み取ります。どちらの認証情報でもワークスペースのグループを読み取れます。
update_settings	ダッシュボード操作を通じて、許可されたグループを1つ変更します。個人用トークンが必要です。
list_files	ファイルを一覧表示します。最初のページにはフォルダーと、表示権限で絞り込まれた件数が含まれます。
get_brand_kit	ブランドカラー、タイポグラフィ、ロゴを読み取ります。

会社プロフィールには get_settings(keys=["company_profile"]) を使用してください。 設定ツールは、Patriciaがチャットで使用するカタログと操作を共有します。 チャットで設定を変更するには、依頼した人によるクリックが必要です。 承認ポリシーの変更はコンソールでの実行に影響します。重要な操作とプロバイダーが必須とする操作には承認の下限が維持され、Patriciaがすでに確認を求めている操作では、対象者向けおよびクリック必須の下限も維持されます。

同じ人に対して別のタスクが実行中の場合、インテグレーションの読み取りはそのタスクが終わるまで待機します。そのタスクを get_task_status でポーリングするか、完了するまで待ってください。 インテグレーションの承認が直接行われた後は、decide_approval が返す next の文に従ってください。 結果を取得するには、タスクIDを指定して get_task_status をポーリングしてください。ツールを再度呼び出さないでください。Patriciaは承認された操作を1回だけ実行します。完了後の呼び出しは新しいリクエストとなり、その時点の承認ルールに従って、先に確認が求められるかどうかが決まります。next の指示に従ってください。保存済みのレビューや承認に依頼者の識別情報が保存されていないBillitでは、同じ呼び出しを再度行う必要がある場合があります。