音声入力とWeb Push

両機能ともデフォルトでは無効です。コンポーザー内のマイクボタンや、エージェントが入力を待っているときに発火するブラウザ通知を有効にできます。

音声入力（任意）

入力欄のマイクボタン、および 設定 → 音声 の ハンズフリースイッチ。ボタンをタップして話すと、メッセージボックスに文字起こしが入力され、内容を確認して送信できます。ハンズフリーがオンの場合、入力されたメッセージと同じ保護された返信経路を通って自動で送信され、経路を迂回することはありません。入力欄が空の間は、行末の丸いボタンがマイクの となります になります。1文字でも入力すると「送信」に戻ります。メッセージを口述するか入力するかのいずれかであるため、フィールドの幅を奪い合う2つのアクションではなく、主要なアクションは常に1つになります。

話している間は、レコーダーがコンポーザー、ベルト、入力欄の全体を覆います。高さは増えないため、上の画面が動くことはありません。マイクがあった位置に OK が表示され、タップすると録音を完了します。末尾の ゴミ箱 は録音を破棄し、文字起こし中であってもキャンセルできます。発話が終わると、2秒間の無音で自動的に録音が終了します。OKボタンの周りに円が描かれてそれを示し、再び話し始めるとカウントはリセットされます。最初の単語を発するまでは、勝手に終了することはありません。

プロバイダーをセットアップするまで、これは存在しません。 collie stt setup を実行するか、Whistle（下記）をセットアップしてください。ボタンは表示されず、音声がスマートフォンから外に出ることもなく、認証情報は保持されず、子プロセスも実行されません。無効化されているのではなく、存在しない状態です。プロバイダーは4つあります:

セットアップがCLI操作になっている理由は、ペアリング と同じです。この画面は認証情報を受け付けるため、ホストのキーボードで操作すべきだからです。キー、エンドポイント、コマンド用のWebフォームはありません。これらを一切必要としない2つの例外。 Whistleは認証情報を保持せず、指定されたコマンドを実行せず、ホスト外に音声を送信しないため、書き込み権限のあるデバイスであれば設定 (理由) からセットアップできます。また 設定 → 音声 → ホスト音声 では、書き込み権限のあるデバイスから、ホストの設定をWhistle、ChatGPTサブスクリプション（codex プロバイダー）、オフの間で切り替えることができます。ChatGPTは、ターミナルに表示されるのと同じ同意を確認し、同意する (以下) をタップした後にのみ有効になります。キーやコマンドを使ってターミナルでセットアップしたプロバイダー、または環境で指定されたプロバイダーはそこに表示され、アプリから変更されることはありません。これら2つについては、フォームではなく、ホスト上で実行するコマンドが コピー および 再確認 とともにページに表示されます。

$ bin/collie stt setup
Which speech-to-text provider?
  openai-compatible  any endpoint that speaks POST /audio/transcriptions —
                     the public OpenAI API, or a local whisper.cpp / parakeet.cpp
                     server, which is the zero-egress choice and the one to prefer.
  codex              borrow your own `codex` sign-in. No new key, no new account —
                     and a private endpoint that may break without notice.
  local-cli          run a transcription command already on this machine, such as
                     whisper-cli or muesli-cli. Its stdout is the transcript.
provider [openai-compatible]:
The API base, INCLUDING its version prefix — the provider appends /audio/transcriptions.
  local  http://127.0.0.1:8080/v1     (whisper.cpp / parakeet.cpp — nothing leaves the host)
  cloud  https://api.openai.com/v1    (room audio leaves this machine)
base URL: http://127.0.0.1:8080/v1
The model the endpoint understands. Empty takes Collie's default, gpt-transcribe.
model [gpt-transcribe]: whisper-1
API key [none]:
The language you speak, as a two-letter ISO-639-1 code — en, de, tr, ja.
LEAVE IT EMPTY to let the model detect it, which is what you want if you mix languages in one
sentence. Name one only if short clips keep coming back in a language you did not speak: a few
seconds of accented audio is too little for the model to detect from, and it guesses.
spoken language [auto-detect]: en
✓ speech-to-text configured — /home/you/.local/state/collie/stt.json (owner-only)
  Live immediately — no restart needed. The bridge re-reads this file per request.
  Check it end to end with `collie stt test`.

上記の各項目にはフラグが用意されているため（--provider · --url · --model · --key · --lang）、プロビジョニング実行時にターミナル操作は不要です。キーを空にしておく設定もサポートされています。キーのないエンドポイントに対しては、空のAuthorizationヘッダーではなく、ヘッダー自体を送信せずに接続します。

音声言語の設定が必要になるのは、特定の認識失敗が起きる場合のみです。 空欄（デフォルト）の場合、モデルが言語を自動検出します。これは1文の中で2言語を混ぜて話す場合に必要な挙動です。短いクリップで話していない言語が頻繁に返ってくる場合にのみ設定してください。アクセントのある数秒の音声では検出材料が不足し、モデルが誤認することがあります。2文字の言語コード、またはCollieが簡略化する地域タグ（en-GB → en）を指定します。これはopenai-compatibleプロバイダでのみ有効です。codexエンドポイントは言語設定を受け付けず、collie stt statusでもその旨が表示されます。

長い録音には長い制限時間を割り当てます。 1つのクリップに対するブラウザの処理制限時間は固定値ではなく、クリップのサイズに応じて決まります。上り速度を256 kb/sと想定し、ブリッジ自体のプロバイダ制限時間を加算するため、上限の8 MiBの場合は約6分弱が割り当てられます。Collieが録音を受け付けたクリップであれば、その完了まで待機します。アップロード中はポーリングを停止し、接続バナーの警告レベルも引き上げません。音声データによる上り帯域の逼迫は障害ではないため、障害として報告すべきではありません。

録音は5分で停止します。Whistleを実行するホストでは、スマートフォンから圧縮された録音の約4倍のサイズであるWAVファイルが送信されるため、上限は4分になります。レコーダーには適用される上限が表示されます。

動作確認 stt test は、スマートフォンが録音可能なコンテナごとに、生成した0.2秒間の無音データを実際のプロバイダーに1回ずつ送信します。

$ bin/collie stt test
provider: openai-compatible (http://127.0.0.1:8080/v1, model whisper-1, language en)
sending:  0.2 s of generated silence as audio/wav (the setup probe) … ✓ 214 ms
  transcript: (empty) — expected from silence, and the empty answer still proves the pipeline.
sending:  0.2 s of generated silence as audio/webm;codecs=opus (Chrome, Android, Firefox) … ✓ 198 ms
sending:  0.2 s of generated silence as audio/mp4 (Safari, iOS) … ✓ 190 ms

ホストでWhistleを使用する場合、stt test は1つのクリップ（16 kHz WAV）を送信し、webmとmp4はスキップされたと通知します。これは、スマートフォンがそのプロバイダーに送信する前に、録音を16 kHz WAVに変換するためです。

文字起こし結果が空であれば成功。無音は空のテキストに変換されるため、通信の往復が確認できれば成功です。失敗した場合は、エラーの種類（認証、エンドポイント、レスポンス形式）が表示されます。その後、スマートフォンでCollieを再読み込みすると、入力欄の横にマイクが表示されます。collie stt statusで設定内容と各設定の適用元（設定ファイルか、それを上書きする環境変数か）を確認できます。collie stt offを実行するとstt.jsonが削除され、ボタンは再び非表示になります。どちらの操作も再起動は不要です。

Whistle: スマートフォンまたはホストでの音声テキスト変換

Whistle は、Cactus Computeによる軽量な音声モデルです。ファイルサイズは16.9 MBで、ライセンスはApache-2.0です。英語、ドイツ語、フランス語、スペイン語、イタリア語、オランダ語、ポーランド語に対応し、言語を自動判別します。アカウント、キー、追加プログラムは不要です。Collie自体が実行エンジンを内蔵しているため、Linux、macOS、Windows、NixOSで動作します。

Whistleは2箇所で実行できます。スマートフォンごとに選択します。

どちらのエンジンも同じモデルを読み込みます。ホストが1つのコピーを保持します。スマートフォン側でWhistleを実行したい場合は、インターネットからではなく必ずホストからコピーします。最近のスマートフォンならクリップの処理は約1秒です。

設定からセットアップします。 書き込み権限のある端末（ペアリング済み を保持している端末）が必要です。読み取り専用の端末には「書き込み権限のある端末でセットアップできます」と表示され、ダウンロードを開始できません。

設定 → 音声 は1つのページであり、その下に2つのページがあります。

• —
  音声 は使用中の項目を先頭に表示します。一番上のカードには、設定内容に応じたタイトルが付きます。たとえば、ホストが実行するコマンド（whisper-cli と、その下の モデル ggml-base.bin および ホスト上の独自コマンド など）、音声サービスのモデル（whisper-large-v3 と api.groq.com の音声サービス など）、Cactus Compute 製 Whistle（モデル ca52876 および このスマートフォン または ホスト と併記）、あるいは ChatGPT サブスクリプション (OpenAI)（ホスト上の Codex 経由 と併記）です。コマンドが古い whistle-stt ラッパーの場合はカードにその旨が表示され、「ホストの音声」を開く 内蔵の Whistle に切り替える が提示されます。続いてステータスが表示され、依存関係（例:「準備完了。Whistle ca52876 はこのスマートフォンにあります」「準備未完了。ホスト上でCodexからサインアウトしています」）、音声 の送信先、セットアップ の方法（設定からどの端末がいつ行ったか、またはホスト上のターミナルで行われたか）が示されます。カードの下にはハンズフリースイッチがあります。それ以外の項目はすべて 音声の動作方法を変更 という1つの行の中にまとめられています。音声機能が正常に動作している間、その行はアクセスするたびに閉じた状態になります。正常に動作していない場合（未設定、スマートフォンの一時停止、応答しないホストの選択肢など）は開いた状態になり、一番上のカードには このスマートフォンで音声をセットアップ、復元、または 修正 のいずれか1つのアクションが表示されます。開くと、このスマートフォン自体の選択肢（推奨 とマークされた このスマートフォン、またはエージェントを実行しているマシンである ホスト）が表示され、端末ごとに保持されます。使用中の選択肢には太い枠線、色合い、および 使用中 バッジが付き、この2つを切り替えてもページ上の位置は移動しません。続いてホストが使用する項目の行、5つの選択肢をすべて開く行、モデルの行が並びます。各選択肢には情報ボタンがあり、音声の送信先、オフライン対応の有無、コスト、必要なセットアップ、速度の5つの情報が一覧表示されます。情報ボタンをタップしても何も選択されません。
• —
  ホストの音声 はホストの5つの選択肢を一覧表示します。Whistle と独自コマンドは、音声をローカルマシン内に留めます。音声サービスと ChatGPT サブスクリプションは、音声をホスト外へ送信します。「オフ」はその下に単独で配置されています。ここでの変更は、ホストにペアリングされているすべての端末に適用されます。変更前よりも広範囲に音声を送信する選択肢を選ぶ場合は事前に確認が求められ、送信範囲を狭める変更はタップ時に即座に反映されます。すべての選択肢に セットアップ手順 が用意されており、番号順の手順、コピー用コマンド、アプリ側で操作可能なボタンが含まれます。次に実行する手順には 次へ の印が付きます。動作していない場合のみ、使用中の選択肢で自動的に展開されます。使用中の選択肢には、「設定済み: whisper-cli、モデル ggml-base.bin」のように設定内容も表示されます。
• —
  Whistle モデル は開発元の Cactus Compute やライセンス名を記載し、Hugging Face 上のモデルページへリンクします。ホスト上のコピーとこのスマートフォン上のコピーを、それぞれの状態とともに表示します。

Whistle をセットアップするには:

1. 01
   音声入力がまだ機能していないスマートフォンでは、音声 の一番上のカードにある このスマートフォンで音声をセットアップ をタップします。1 回のタップで全体が完了します。ホストにモデルがなければダウンロードし、このスマートフォンがホストからそれをコピーして、このスマートフォン が選択されます。1 本のバーに進捗が表示され、「ホストへダウンロード中…」または「このスマートフォンへコピー中…」のように実行中のステップが示されます。ステップが失敗すると処理はその場で停止し、理由を表示して 再試行 を提示します。読み取り専用デバイスはコピー（読み取り操作）を行えますが、ホストにダウンロードを要求することはできません。同じ 2 つのステップは 音声の動作方法を変更 にもあります。コピーを持たないスマートフォンでは セットアップ (16.9 MB)、ホストにモデルがすでにある場合は このスマートフォンへコピー と表示されます。
2. 02
   または Whistle モデル を開いて ホストへダウンロード (16.9 MB) をタップします。バーに進捗が表示されます。失敗した場合、ページに理由が表示されます。再試行 をタップしてください。モデルが配置されると、バージョン（Hugging Face のリビジョンの先頭 7 文字およびそのリビジョンへのリンク）とサイズが一覧表示されます。詳細 には短いチェックサムとホストがダウンロードした日時が表示されます。
3. 03
   ホスト経由でディクテーションを行うには、ホストの音声 を開いて ホスト上の Whistle を選択し、次に 全デバイスで変更 を選びます。またはその下の セットアップ手順 を開いて ホストで使用 をタップします。端末内でキーやコマンドを使って別のプロバイダーを設定している場合、ページにはそれが表示され、選択肢は提示されません。その場合の Whistle の手順は、ホスト上の collie stt off、続いて collie stt whistle --host から始まります。
4. 04
   このスマートフォンのコピーについて、Whistle モデル はバージョン名を表示し、このスマートフォンから削除 を提示します。また、ブラウザがコピーの保持に同意したか（「保持済み」）、空き容量が少なくなった際に消去される可能性があるかも表示します。後でホストが新しいモデルを取得した場合、コピー側はその旨を表示し、アップデート を提示します。
5. 05
   音声 で 音声の動作方法を変更 を開き、このスマートフォン または ホスト を選択します。スマートフォンにコピーが保存されるまで このスマートフォン はオフになります。ホストに音声オプションがない間は ホスト がオフになります。選択肢の下の行には、ホストが何を使用しているかが示されます。
6. 06
   ホストからモデルを削除するには、Whistle モデル で ホストから削除 をタップして確認します。Whistle がホストエンジンだった場合、再ダウンロードするまでホストでの音声入力は停止します。

変更者。 ペアリングされたデバイスが「設定」からホストのオプションを変更すると、ホストはそのデバイス名と時刻を記録します。その後 音声 と ホストの音声 には「最終変更: Pixel 8」と時刻が表示されます。端末側で変更を行うと、この記録はクリアされます。

または端末内でセットアップします。

$ bin/collie stt whistle                 # fetch the model once
$ bin/collie stt whistle --host          # also make Whistle this host's engine
$ bin/collie stt whistle --from <path>   # use a copy you already have, same hash check
$ bin/collie stt whistle --remove        # remove the model, and the host engine if it is Whistle
$ bin/collie stt status                  # shows the model line

--host は、意図して設定されたプロバイダーを置き換える前に確認を求めます。--yes は、端末を介さない実行時にその確認へ応答します。確認はダウンロード前に行われるため、拒否された実行では何も取得されません。--remove は別種のプロバイダーには手を加えません。collie stt off はプロバイダーを削除し、モデルが残る旨を伝えます。collie doctor は、ホスト上のモデルが本リリースで受け入れ可能なものではない場合に警告します。エンジンは再起動なしですぐに有効になります。collie stt test で確認してください。

ダウンロードされる対象とその取得元。 ホストは固定された単一の Hugging Face アドレスから whistle.cact を取得し、その CDN へのリダイレクトを追跡します（最大 5 回、HTTPS のみ、ローカルやプライベートアドレスへは接続しません）。そして sha256 が本リリースに含まれるハッシュと一致する場合にのみファイルを保持します。不一致の場合はファイルを削除し、両方のハッシュを報告します。ダウンロード上限は 32 MiB で、10 分の期限があります。ファイルはステートフォルダー内の whistle フォルダーに配置されます。エンジンコード（約 1 MB）は Collie の全リリースに含まれており、Collie 自体のファイルから提供されます。

勝手にダウンロードされることはありません。 インストール時にも、アップデート時にも、エンジンの選択時にも行われません。モデルが取得されるのは、ユーザーが ホストにダウンロード や セットアップ をタップするか、collie stt whistle を実行したときです。スマートフォンがホストからモデルをコピーするのは、所有者が セットアップ、このスマートフォンへコピー、または 復元 をタップしたときのみであり、それ以外の場所から取得することはありません。ホストが同時にモデルを送信できるスマートフォンは最大 2 台です。3 台目には「しばらくしてから再試行してください」と表示されます。

制限事項。 WAV は圧縮された音声クリップの約 4 倍のサイズになり、アップロード上限が 8 MiB であるため、ホストエンジンの録音時間は最大 4 分です。レコーダーにはその上限が表示されます。スマートフォン側のエンジンは最大 5 分まで処理できます。ホストの子プロセスには音声クリップの長さの半分（最低 60 秒、最大 3 分）の期限が設定されており、ホスト上で同時に実行できるクリップは最大 2 件です。スマートフォン側には、モデル用の空き容量（ファイルサイズの 2 倍を要求）とセキュアな接続（tailscale serve が提供するような HTTPS）が必要です。

スマートフォン側で処理できない場合。 クリップの処理中に このスマートフォン が失敗した場合、ホストに機能する音声プロバイダーがあるときに限り、音声画面に理由が表示され ホストへ送信 が提示されます。クリップは「ホストへ送信」をタップするか破棄するまで、失敗した状態のままメモリ内に残ります。音声を端末内に留めることが目的のエンジンを選択しているため、Collie が勝手に送信することはありません。同一セッション内でエンジンが 2 回クラッシュすると、アプリを再読み込みするまで このスマートフォン はオフになります。

スマートフォンのコピーが消去された場合 空き容量を確保するために、ブラウザがコピーを消去することがあります。設定はこのスマートフォンに残りますが、音声入力は一時停止されます。音声 に「音声入力は一時停止中」と表示され、ホストからモデルを再コピーする 復元 が選べるようになります。マイクの録音は継続し、音声クリップは上記と同様に ホストへ送信 のまま端末内に残ります。Collie が自動でホストへ切り替えることはありません。ホストを使うには、ホスト を選択してください。

対応ブラウザ このスマートフォン には、音声ワーカに独自のセキュリティポリシーを付与できるブラウザが必要です。Android 版 Chrome でテスト済みです。WebKit は WebKit ビルド環境でテストされています。iPhone 版 Safari は実機での検証がまだ完了していません。実行できないブラウザでは理由とともに このスマートフォン がオフと表示され、ホスト は引き続き利用できます。

以前のラッパーを使用していた場合 このページの旧バージョンでは、ネイティブランナーをラップする local-cli、ffmpeg、jq を案内していました。この構成は廃止されましたが、既存のセットアップが変更されることはなく、そのまま動作し続けます。内蔵エンジンに移行するには、bin/collie stt whistle --host --yes を実行するか、collie stt off を実行してから bin/collie stt whistle --host を実行してください。ラッパーを使い続けることも可能です。ラッパーのモデルファイルは自動的には再利用されません。ダウンロードをスキップするには、--from <path> でモデルファイルを指定してください。

このエンジンのセキュリティ面や、Settings からのセットアップが許可されている理由については、セキュリティ と ADR 0096 を参照してください。

コンテナの対応状況はプロバイダーによって異なります

スマートフォンはWAV形式で録音しません。Chrome、Android、FirefoxではWebMコンテナのOpus、SafariやiOSではMP4コンテナのAACで録音し、そのバイトデータをそのまま送信します。WAVを文字起こしできるプロバイダーであっても、これら両方に400エラーを返す場合があり、その際stt testが正常に見えてもディクテーションはすべて「refused」で失敗します。stt testが3種類すべてのクリップを送信するのはそのためです。拒否される問題をスマートフォン上ではなくセットアップ時に検出します。

2026-09-01にOpenRouterのPOST /v1/audio/transcriptionsで確認した例:

回避策はキーではなくモデルの変更です。同じOpenRouterキーの接続先を、4種類すべてを受け付けるopenai/whisper-large-v3-turboに設定してください。

bin/collie stt setup --provider openai-compatible \
  --url https://openrouter.ai/api/v1 --model openai/whisper-large-v3-turbo --key <key>

文字起こしが拒否された場合、アップストリームのステータスと送信時のコンテナ名が表示されるようになり、プロバイダーがどのフォーマットを拒否したかがスマートフォンのエラーに表示されます。( #148、@drewbitt に感謝します)

外部送信ゼロ: 自前のエンジンを指定する

openai-compatibleを選択すべき理由: ローカルのベースURLと周囲の音声がホスト外へ送信されることはありませんを指定します。OpenAI互換の文字起こしエンドポイントを提供するエンジンは2つあります。whisper.cppに同梱されるserver、およびmudler/parakeet.cpp（MIT）です。それぞれの説明書に従ってビルドまたはインストールし、ループバックで実行して、--urlをそのアドレスに設定してください:

bin/collie stt setup --provider openai-compatible --url http://127.0.0.1:8080/v1

連携に必要なのはこれだけです。Collieはどのエンジンが応答するかを関知しません。

MistralのVoxtralに専用のサポートは不要。この規約に準拠する他のコンポーネントも同様です。この境界設計の利点はそこにあります。vLLMはオープンウェイトのVoxtralモデルを/v1/audio/transcriptionsで配信するため、ローカルモデルも他のエンジンと同じ--urlで扱えます。ホスト型モデルも、Mistral独自のエンドポイントに対して同じリクエストを送るだけです。

bin/collie stt setup --provider openai-compatible \
  --url https://api.mistral.ai/v1 --model voxtral-mini-latest --key <key> --lang en

Voxtral Mini Transcribeは13言語に対応し、Collieがすでに送信しているものと同じISO-639-1のlanguageフィールドを受け取ります。信頼する前にcollie stt testで動作を確認してください。「OpenAI互換」は各エンドポイントが独自に主張しているに過ぎず、このコマンドはその検証のために用意されています。

Codexプロバイダ: 同意事項

collie stt setup --provider codexは同意確認ブロックを表示し、yesと入力するまで処理を停止します。正確に言えば、録音データは現在のサインインで認証された文書化されていない非サポートのChatGPTエンドポイントに送信されるため、ChatGPTアカウントがレート制限や利用停止のリスクを負うことになり、予告なしに動作しなくなる可能性があります。

Collieはまずまず独自の名前で問い合わせるそのエンドポイントに問い合わせます。自身のアイデンティティが拒否された場合にのみCodex CLIのヘッダーへフォールバックします。そのフォールバックは設定に明記され、collie stt statusによって表示されます。Collieが~/.codex/auth.jsonを読み取ったり保存したりすることはありません。すでに信頼しているバイナリのみがそれにアクセスします。

Settings でも選択可能 書き込み権限のある端末で 設定 → 音声 → ホスト音声 を開きます。ページにはホストが現在使用している設定が表示されます。ChatGPT サブスクリプションの場合は、記録された識別情報（honest、またはフォールバックが必要だった場合は codex-cli）も表示されます。ChatGPT サブスクリプション 行が有効になるのは、ホストに codex がインストールされ、ChatGPT にサインインしている場合のみです。Collie は確認のために codex login status を照会します。それ以外の場合は行内に理由が 1 文で表示され、セットアップ手順 に次の手順（ホストに Codex をインストールし、codex login でサインインした上で ChatGPT サブスクリプションを使用 をタップする）が示されます。その行をタップすると、ホストにペアリングされたすべての端末に変更が適用される旨の注記の下に、一字一句同じ同意事項を示すシートが表示されます。同意する をタップするまで、ホストには何も送信されません。タップすると、ホストは collie stt setup と同じプローブを正しい識別情報を優先して実行し、同一の設定を書き込みます。プローブが失敗した場合、設定は書き込まれず、シートに理由が表示されます。同じページの 無効 でプロバイダを削除できます。ターミナル側もこれまで通り動作します。

独自のコマンドを実行: local-cliプロバイダー

local-cliは、HTTPサーバーを介さず、既存の文字起こしコマンドを録音ごとに1回実行します:

bin/collie stt setup --provider local-cli \
  --command /Applications/Muesli.app/Contents/MacOS/muesli-cli --args transcribe
bin/collie stt test

Collieは録音を専用の一時ファイルに書き込み、<command> [args…] <file>を実行します。ファイルパスは常に最後の引数になります。コマンドの標準出力をトリムしたものが文字起こし結果となります。

プレーンな名前はsetupの実行時に検索され、フルパスが保存されます。サービスは制限されたPATHで実行されるため、シェルで見つかる名前がそこでは解決されない場合があります。./whisper-cliなどの相対パスは拒否されます。

--argsはスペースで区切られた単語を受け取ります。シェルを経由しないため、引用符は入力されたそのまま保持されます。スペースを含む引数には、代わりにJSON形式を使用してください:

bin/collie stt setup --provider local-cli --command whisper-cli \
  --args '["-m", "/srv/my models/ggml-base.bin", "-nt"]'

コマンドに必要な要件:

• —
  実行ユーザーが実行可能な通常ファイルであること。Collieはシンボリックリンクを追跡するため、通常ファイルへのリンクでも問題ありません。collie stt setupはそれ以外のファイルを拒否し、collie stt statusがエラー内容を示します。
• —
  ステータス0で終了し、標準出力に文字起こし結果を出力すること。それ以外の場合はディクテーション失敗となります。
• —
  60秒以内に終了すること。これを超えるとCollieはコマンドおよびそれが起動したすべてのプロセスをSIGKILLで強制終了します。
• —
  標準出力への出力は最大256 KiBとすること。これを超えた時点でCollieはそのプロセスを強制終了します。
• —
  プロセスを残さないこと。コマンド終了時、Collieはそれが起動して残存しているプロセスをすべて強制終了します。常駐が必要なヘルパーは、setsidなどを使用して独自のセッションを開始する必要があります。

Windowsでは、Collieは同様のタイミングでコマンドのプロセスツリー全体を終了し、正常終了後もコマンドが起動して実行中のままのプロセスを終了します。ただし、すでに終了したヘルパーによって起動されたプロセスは、コマンド終了後も存続する場合があります。

コマンドを同時に実行できるディクテーションは最大2件です。3件目はスマートフォン側が認識可能な「ビジー」応答を受け取り、Collieは何も起動しません。

標準出力が空の場合は入力欄に反映できるものがないため、スマートフォン側では失敗として扱われます。collie stt testではクリップが無音となるため、正常としてカウントされます。

注。 コマンドはbridge自身のユーザー権限で、ディクテーションごとに1回実行されます。シェル、標準入力、およびCOLLIE_*環境変数は提供されません。標準エラー出力は読み取られず、コマンドラインやパスがスマートフォンに渡されることもありません。コマンドの失敗と終了ステータスのみが伝達されます。

一時ファイルは実行ユーザーのみがアクセス可能なディレクトリに置かれ、実行ごとにCollieによって削除されます。実行中にbridge自体が強制終了された場合、次回bridge起動時に1時間以上経過した該当ディレクトリが削除されます。音声データの送信先はコマンドに依存します。ローカルエンジンを使用する場合はホスト内にとどまります。

上記すべての理由（2回却下された背景、変更点、境界がこのように設計された理由）は、ADR 0029に記載されています。

Web Push（任意）

デフォルトでは無効です。セットアップには3つのステップが必要です。送信ライブラリ（web-push）はビルド時にオプショナルな依存関係として含まれます。

collie push-keys     # 1. generate + write the VAPID keys
collie restart       # 2. Collie reads them at start
#                      3. on your phone: Settings → Alerts

push-keys コマンドはキーペアを生成し、パーミッション 600 で COLLIE_VAPID_PUBLIC と COLLIE_VAPID_PRIVATE をアクティブな .env に書き込みます。これはバイナリインストールの場合は ~/.config/collie/.env、Herdr インストールの場合は Herdr のプラグイン設定ディレクトリ内のものです。

RFC 8292のsubjectクレームを設定するには、連絡先URIを引数として渡します。

collie push-keys mailto:you@example.com

Herdrで管理された環境では、両方のステップをアクション（herdr plugin action invoke push-keys --plugin herdr.collieおよびrestart）として利用できます。Herdrのアクションは位置引数を受け取らないため、subjectを設定するにはシェルでコマンドを直接実行する必要があります。

鍵の取り扱いに関する詳細:

このコマンドは、--forceを渡さない限り既存の鍵を上書きしません。鍵を更新すると既存のすべての購読が無効になり、通知を再度受信するには各デバイスで再購読が必要になります。既存の設定に対してsubject引数を指定した場合は、連絡先アドレスのみが更新され、現在の鍵は維持されます。

注。 0.8.0より前のHerdrバージョンでは、アクションはプラグインの初期インストール時にキャッシュされたセットに固定されたままになります（ADR 0006）。push-keys および push-test アクションは、herdr plugin install を実行するまで表示されません。代わりに bash scripts/collie-ctl.sh push-keys を直接実行してください。ラッパースクリプトがコマンドをバイナリへ直接渡します。

購読しているすべてのデバイスへの配信パスをテストします。

collie push-test                     # or: push-test "Title" "Body"

配信には1〜2秒かかります。プッシュが無効であると報告された場合は、サービスを再起動して生成された鍵を読み込ませてください。購読デバイスがないと報告された場合は、スマートフォンのブラウザでステップ3を完了してください。

Web Pushにはセキュアコンテキスト（HTTPS）が必要です。これはtailscale serve（MagicDNS証明書）またはTLSを終端する外部リバースプロキシ（バリアント C）によって提供されます。プレーンHTTP環境（COLLIE_SERVE_MODE=http）にはセキュアコンテキストがないため、ブラウザは「Settings」内の購読コントロールを無効化します。

Collieは、エージェントがblockedまたはdone状態になると通知を送信し、エージェントのメッセージを本文に含めます。通知を選択すると、Web UI上の該当エージェントへ直接移動します。

Collieが送信するアラート

5種類あり、それぞれ設定 → 通知 → 通知の条件に個別のスイッチがあります。

Finishedはエージェントがworkingからidleに移行したときに発火するため、中断したエージェントも完了としてカウントされます。

マシンのページでルールを設定するまで、マシン負荷の通知は送信されません。スイッチを切り替えると、全ルールが一括でオフになります。値が上昇して高い状態が続くたびに1件の通知が送信され、タップするとそのマシンのStatusビューが開きます。Machinesを参照してください。

各デバイスは、アラートのタイトルをそれぞれの言語で表示します。更新後にCollieを開いていないデバイスでは英語で表示されます。本文はブリッジが書き込んだ状態のまま維持されます。

スイッチの設定はすべてブリッジ全体に適用されます。プッシュ通知は登録されたすべてのデバイスに配信されるため、デバイスごとの個別設定はありません。

キャッシュ警告は、対象ペインの設定からペイン単位で有効にすることもできます。ペインを開き、⋮をタップしてペイン設定を選択してください。これらのペインはSettingsのグローバルスイッチの下に一覧表示され、それぞれ「削除」ボタンが付きます。

2つの設定状態は上書きではなく加算されます。グローバルスイッチがオンであるか、またはそのペインがリストに含まれている場合に警告されます。そのため、グローバルスイッチをオフにしても、手動で監視対象にしたペインの通知は停止しません。

監視対象のペインは ウォームサイクルごとに1回 の警告を受けます。エージェントの次のリクエストによって期限が延長され、その後にのみ同じペインで再度警告が発生します。静粛時間も適用されます。スヌーズ中のブリッジは何も送信せず、静粛時間内に終了したスヌーズは引き続き警告を出します。すでに cold 状態のペインには警告が出ません。残り時間がある状態で /model 切り替えによって cold になったペインもこれに含まれます。

COLLIE_CACHE_WARN_SECONDSでウィンドウの長さを変更できます。デフォルトは300秒（configure.md）です。

注。 このアラートにはプロンプトキャッシュの読み取りが必要なため、キャッシュのカウントダウンが表示されているペインのみが対象となります。ハーネスがCollieの読み取れるトランスクリプトを保持しており、かつエージェントが少なくとも1ターン実行されている必要があります。ペインが実際に警告を発するウィンドウは、設定された秒数とそのペイン自体のキャッシュ有効期限の半分のうち、短い方になります。1時間のClaudeキャッシュでは300秒のウィンドウがそのまま適用されます。Codex、OpenCode、pi、ompなどの5分キャッシュでは、期限切れの約2分半前に警告されます。

ホーム画面からの再インストールやService Workerのリセットによって、HTTP 410を返さずに新しいエンドポイントが作成されることがあるため、古い購読情報が蓄積する可能性があります。デバイスが再登録されると、Collieはレコードを更新します。保存されているエンドポイントは直接確認および削除できます。

# one line per device: service, since, user agent, endpoint tail
bin/collie push list
bin/collie push forget <substring>   # or: push forget --all

durable agentからのプッシュ通知

durable agent の質問カードからスマートフォンへプッシュ通知を送信できます。Collie は 1 つの durable agent が送信できるプッシュ通知の数を制限します。

プッシュ通知には「Permission needed in」と指定したペイン名が表示されます。質問に対する durable agent 独自のタイトルが含まれることはありません。durable agent は文言を指定できます。タイトルの内容（最大 60 文字）はペイン名の後にコロン区切りで続き、その行の内容（最大 120 文字）が本文になります。この文言によって変化するのはプッシュ通知の表示内容のみであり、送信頻度には影響しません。

要約には「A durable agent on {host} is raising many asks」と表示され、host にはマシン名が入ります。crew 内では member の名前になります。「Needs input」スイッチやスヌーズによっても要約は保留されます。上限に達しても質問が非表示になることはありません。未完了の質問はすべてスマートフォン上に残ります。

Collie は質問を 1 回プッシュ通知します。マシン、durable agent、ツール呼び出しごとに各質問を記憶するため、durable agent が再起動して同じ質問を再度行っても、スマートフォンには表示されますが 2 回目のプッシュ通知は送信されません。質問はクローズしてから 1 時間後に破棄されます。この記憶データは状態フォルダー内の durable-asks.json です。crew では lead がこれらのルールを実行して該当ファイルを保持し、member は自身の質問に対してプッシュ通知を送信しません（ADR 0100）。