signal-tools

signal-tools

コーディングエージェント向けのSignalツール：チャット、メッセージ、連絡先、受信ファイル、送信。

ハーネス	提供方法	固定方法
OpenCode V2	ネイティブプラグイン（npm パッケージ、スキル付き）	パッケージ内のバージョン
OpenCode V1	ネイティブプラグイン（npm パッケージ、スキルなし）	パッケージ内のバージョン
Claude Code	プラグイン：MCP サーバーとスキル	リリースタグを ref として使用
Codex	プラグイン：MCP サーバーとスキル	リリースタグを ref として使用
Grok Build	プラグイン：MCP サーバーとスキル	リリースタグを @ref として使用
Antigravity	プラグイン：MCP サーバーとスキル	リリースタグのツリー URL
Hermes Agent	ネイティブプラグイン（Python、コマンドラインを呼び出し）	リリースコミットを SHA として使用
その他の MCP ホスト	npm の MCP サーバー	パッケージ内のバージョン

ツールには Node.js 24 以降が必要です。 docs/conventions.md では、ツールの命名方法と 動作について説明しています。

インストール

デフォルトブランチではなく、必ずリリースからインストールしてください。リリースは、ビルド済みの dist/ を含むコミットを指すタグであり、デフォルトブランチには含まれていません。以下のコマンドで、<version> はリリースのバージョン（1.2.3）、<sha> はそのタグが指すコミットです：

gh api repos/craft-agent/signal-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 では、パッケージとそのオプションを opencode.json に指定します：

{
  "plugins": [{ "package": "@craftsamo/signal-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "signal_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 では、パッケージを文字列として指定するか、オプションと組み合わせて指定します：

{
  "plugin": [["@craftsamo/signal-tools@<version>", { "read_only": false }]],
  "permission": { "signal_*": "ask" }
}

OpenCode では、ルールで名前を指定されていないアクションはすべて許可されるため、ルールに ask と指定されていない限り、プラグインのリクエストは通知なしで許可されます。読み取りツールは確認を求めないため、signal_* の glob は安全です。

V1 はスキルを登録しません。パッケージを展開し、skills/* フォルダーを ~/.config/opencode/skills/ にコピーしてください：

npm pack @craftsamo/signal-tools@<version>
tar -xzf craftsamo-signal-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-signal-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/signal-tools#v<version>
claude plugin install signal-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/signal-tools --ref v<version>
codex plugin add signal-tools@craft-agent

Codex はサーバー名の - を _ に変換するため、ツールは mcp__signal_tools__signal_* として表示されます。MCP サーバーはプラグインのインストールディレクトリで起動され、呼び出し元の作業ツリーで起動されることはありません。

Grok Build

grok plugin install craft-agent/signal-tools@v<version> --trust

Grok はセッションの作業ディレクトリで MCP サーバーを起動します。

Antigravity

デフォルトブランチにはビルド済みの dist/ がないため、必ずリリースタグのツリーからインストールしてください。Antigravity はタグを ~/.gemini/config/plugins/signal-tools にクローンします。

agy plugin install https://github.com/craft-agent/signal-tools/tree/v<version>

Hermes Agent

Hermes はタグではなくコミットをインストールし、プラグインは無効の状態でインストールされます：

hermes plugins install craft-agent/signal-tools --ref <sha>
hermes plugins enable signal-tools

Hermes ゲートウェイがすでに実行中の場合は、プラグインを読み込むために再起動してください（hermes gateway restart）。

その他の MCP ホスト

ホストの MCP 設定にサーバーを追加してください。フラグは args に指定します：

{
  "mcpServers": {
    "signal-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/signal-tools@<version>", "--read-only"]
    }
  }
}

ツールとスキル

各ツールセットには、エージェントにツールの使い方を伝えるスキルが付属します。

アカウント（account）

ツール	内容	種別
signal_account_read	各ラベルについて、リンクの有無、同期サービスの状態、最後の受信、次の手順を返します	読み取り

ローカルの状態のみを読み取ります。デーモンもネットワークも使用せず、結果に電話番号、アカウント ID、鍵は含まれません。スキルは signal-account で、Claude Code では signal-tools:signal-account、Hermes では signal-tools:account として 表示されます。

チャット（chats）

ツール	機能	分類
signal_chat_read	method によって、list はチャットを検索し、view は1つのチャットのメッセージを読み取り、search は単語でメッセージを検索し、around はあるメッセージの前後のメッセージを読み取ります	読み取り

アカウントのローカルミラーのみを読み取ります。デーモンもネットワークも使用せず、結果にアカウント自身の電話番号、添付ファイル ID、キーは含まれません。履歴はデバイスがリンクされた時点から始まります。時刻はオフセット付きのローカル時刻で、チャットは常に ID で表されます。長い結果は next でページ分割され、返される内容はすべて他の人が書き込んだデータです。スキルは signal-chats です。Claude Code では signal-tools:signal-chats、Hermes では signal-tools:chats として表示されます。

連絡先（contacts）

ツール	機能	分類
signal_contact_read	ローカルの連絡先を一覧表示するか、Signal で最大3つの電話番号を確認します	読み取り

一覧表示にデーモンは不要ですが、電話番号の確認には実行中の同期サービスが必要です。どちらもミラーには書き込みません。スキルは signal-contacts です。Claude Code では signal-tools:signal-contacts、Hermes では signal-tools:contacts として表示されます。

ファイル（files）

ツール	機能	分類
signal_file_save	1つのメッセージのファイルを保存し、指定された場合はアーカイブを展開します	追加
signal_file_send	キャプションを付けて、1～10個のファイル（合計100 MiB）をチャットに送信します	追加

このツールセットはデフォルトで無効です。ディスクへの書き込み、アーカイブの展開、ファイルの送信を行うためです。toolsets または tools で有効にしてください。ファイルの送信元は作業ディレクトリ（ホームディレクトリまたはファイルシステムのルートの場合を除く）と、send_dirs 設定で指定したディレクトリに限られます。キー、シークレット、プログラム、インストーラーは拒否されます。アーカイブはエントリーごとに検査され、送信するファイルが承認済みのものと同一であることを確認するために、ファイルの sha256 を指定できます。送信には同期サービスの実行が必要です。受信したファイルは download_dir 設定の場所に、メッセージごとのフォルダーへ保存されます。ユーザー専用（モード 700 および 600）で、実行可能にはなりません。既存のファイルが上書きされることはありません。プログラムとインストーラーは決して保存されません。アーカイブ（zip、tar、gzip 圧縮 tar）は内容の検査に合格した後にのみ保存され、その後一覧表示されます。unpack: true の場合は、隣接する <name>.unpacked/ に展開されます。1回だけ表示できるメッセージのファイルは保存されません。macOS では、保存されたすべてのファイルに隔離フラグが付与されます。保存にデーモンは不要です。スキルは signal-files です。Claude Code では signal-tools:signal-files、Hermes では signal-tools:files として表示されます。

送信（sends）

ツール	説明	クラス
signal_message_send	チャットに最大4,000文字のテキストを1件送信します。任意でメッセージを引用できます	追加

チャットは常にそのIDで指定します。ユーザー自身のアカウントIDは「Note to Self」であり、ユーザーが退出したグループへの送信は拒否されます。結果が返された場合、Signal がメッセージを受け付けています。グループの場合は reached と not_reached が返されます。リクエスト送信後にその他の失敗が発生した場合は uncertain となるため、再送信する前に電話を確認してください。メッセージはミラーに記録されます。記録に失敗した場合は、送信を取り消すことなく errors に一覧表示されます。同期サービスが稼働している必要があります。スキルは signal-sends です。Claude Code では signal-tools:signal-sends、Hermes では signal-tools:sends として表示されます。

操作（actions）

ツール	説明	クラス
signal_message_edit	ユーザー自身のメッセージのテキストを置き換えます	上書き
signal_message_delete	ユーザー自身のメッセージを全員から削除します。取り消すことはできません	管理
signal_message_react	メッセージへのユーザーの絵文字リアクションを設定、置換、または削除します	上書き

このツールセットはデフォルトでは無効です。操作によって、他のユーザーがすでに読んだ内容が変更されるためです。toolsets または tools で有効にしてください。編集と削除ができるのは、ユーザー自身のメッセージのみで、送信後24時間以内に限られます。また、メッセージの編集は最大10回までです。編集できるのはテキストメッセージのみです。リアクションは任意のメッセージに設定でき、1人につき1つです。新しいリアクションを設定すると、ユーザーの以前のリアクションが置き換えられます。結果は送信と同じ扱いです。結果が返された場合、Signal がメッセージを受け付けています。グループの場合は reached と not_reached が返されます。リクエスト送信後にその他の失敗が発生した場合は uncertain となるため、繰り返す前に電話を確認してください。各操作は、同期サービスが別のデバイスから記録する場合と同じようにミラーに記録されます。記録に失敗した場合は errors に一覧表示されます。どのツールも既読通知や入力中インジケーターは送信しません。同期サービスが稼働している必要があります。スキルは signal-actions です。Claude Code では signal-tools:signal-actions、Hermes では signal-tools:actions として表示されます。

ツールの追加

1. src/core/<domain>/<verb>.ts に defineTool を使って仕様を記述します。ID <prefix>_<domain>_<verb>、タイトルと説明、Zod の引数および出力スキーマ、ツールセットと書き込みクラス、そして execute(args, context) を定義します。書き込みツールには targets(args, context) も指定します。これは、この呼び出しが何に書き込むかを示すもので、権限ルールではこの対象を指定する必要があります。
2. 仕様の隣にテスト（<verb>.test.ts）を作成し、エントリーポイントと同様に invoke を通して呼び出します。プログラムを実行するツールは、PATH 上に配置したそのプログラムのフェイクを使ってテストします。テストで実際のサービスに接続することはありません。
3. src/tools.ts に追加します。新しいツールセットは src/project.ts の toolsets に追加し、デフォルトで有効にする場合は defaultToolsets にも追加します。
4. ツールセットのスキル skills/<prefix>-<toolset>/SKILL.md を追加または更新します。
5. pnpm run build && pnpm run manifests を実行して、ツールを plugin.yaml に追加し、その後「Tools and skills」の下に説明を記載します。

docs/conventions.md に、各手順で従うルールが記載されています。

読み取りと書き込み

すべての読み取りツールの名前は <prefix>_<domain>_read です。読み取りは確認なしで実行できます。 書き込みはハーネスによって確認されます。

ハーネス	確認なしで実行できる読み取り
OpenCode	常に実行できます。プラグインは書き込みの前にのみ確認を求めます
Claude Code	~/.claude/settings.json の permissions.allow にあるルール mcp__plugin_signal-tools_signal-tools__*_read
Codex	常に実行できます。Codex は読み取りツールと同様に、readOnlyHint を宣言するツールを確認なしで実行します
Grok Build	grok --allow 'MCPTool(signal-tools__*_read)' --allow 'MCPTool(signal_*_read)'（両方のルール。下記参照）
Antigravity	読み取りツールごとに、permissions.allow にルール mcp(signal-tools_signal-tools/<tool id>) を設定します
Hermes	常に実行できます。プラグインは書き込みの前にのみ確認を求めます

書き込みについて確認を求められる場合と、求められない場合は次のとおりです。

• OpenCode はルール名がなくてもあらゆる操作を許可するため、ルールが確認を求めない限り、書き込みは確認なしで実行されます。[OpenCode](#opencode) に示されている signal_* ルールを追加してください。
• Codex は codex exec の実行時に、また Grok Build は grok -p の実行時に、事前に許可されていない書き込みについて確認を求めることができない場合、それを拒否します。
• Grok Build は use_tool ツールを通じてプラグインのツールを呼び出します。エージェントはサーバー名を付けずにツール名を指定することがよくあります。Grok は指定された名前に基づいてルールを照合するため、サーバー名付きのルールだけでは最初の呼び出しに一致しません。2つ目のルールは短い名前に一致しますが、書き込みにはどちらのルールも一致しません。
• Antigravity は、読み取りも含め、どのルールでも許可されていないMCPツールを呼び出す前に確認を求めます。また、プラグインのサーバー名を signal-tools_signal-tools（プラグイン名、続いてサーバー名）として指定します。agy -p は、確認を求めることができないツールを拒否します。
• Hermes は hermes chat -q の実行時に、確認を求めることができない書き込みを拒否します。hermes -z と --yolo は承認をスキップするため、その場合、書き込みは確認なしで実行されます。

設定

すべてのエントリーポイントで同じ設定を使用します。フラグは環境変数より優先され、オプションまたは設定も変数より優先されます。

設定	フラグ	変数	説明
toolsets	--toolsets	SIGNAL_TOOLS_TOOLSETS	有効にするツールセット、または all。デフォルトでは src/project.ts の名前を使用します
read_only	--read-only	SIGNAL_TOOLS_READ_ONLY	書き込みを行うツールを登録しません。他のすべての設定より優先されます
tools	--tools	SIGNAL_TOOLS_TOOLS	ツールセットに関係なく、IDで追加する個別のツール
exclude_tools	--exclude-tools	SIGNAL_TOOLS_EXCLUDE_TOOLS	IDで削除する個別のツール。tools と toolsets より優先されます
confirm	--confirm	SIGNAL_TOOLS_CONFIRM	MCP サーバーのみ：規約に従い、harness（デフォルト）または elicitation
state_dir	--state-dir	SIGNAL_TOOLS_STATE_DIR	各ラベルの状態を保存する場所。デフォルトは $XDG_STATE_HOME/signal-tools
download_dir	--download-dir	SIGNAL_TOOLS_DOWNLOAD_DIR	受信したファイルの保存先。デフォルトは ~/Downloads/signal-tools
send_dirs	--send-dirs	SIGNAL_TOOLS_SEND_DIRS	作業ディレクトリ以外で、ファイルの送信元として許可するディレクトリ

フラグまたは変数で指定するリストは、カンマ区切りです。各ハーネスでの読み込み方法は次のとおりです。

• OpenCode は、上記のプラグイン options を使用します。リストは配列、read_only はブール値、state_dir と download_dir はパス、send_dirs はパスの配列として指定し、設定がない場合は変数を使用します。V2 はプラグインをバックグラウンドサービスで実行するため、サービスの起動時の環境が保持されます。opencode run の起動時に設定した変数は、その環境でサービスを再起動するまで反映されません（opencode service restart）。V1 はプラグインを独自のプロセスで実行します。

• Hermes は、config.yaml の plugins.entries.signal-tools.settings を使用します。

  plugins:
    entries:
      signal-tools:
        settings:
          read_only: false
          exclude_tools: []
  

  プラグインは、実行するコマンドラインに独自の環境を渡すため、変数も使用できます。起動中のゲートウェイは起動時の環境を保持するため、変更後に再起動してください（hermes gateway restart）。

• Claude Code、Grok Build、Antigravity はプラグインのサーバーをフラグなしで起動し、クライアントの環境を渡します。そのため、ハーネスの実行環境で変数を設定してください。

• Codex は、プラグインの MCP サーバーに、PATH や HOME などの基本的な変数と、プラグインのマニフェストに記載された変数（上記の変数）のみを渡します。そのため、Codex の実行環境で変数を設定してください。フラグを渡す場合や、サーバーに必要な別の変数を渡す場合は、プラグインを使用する代わりに、Codex の config.toml の [mcp_servers] の下にサーバーを追加します。フラグは args に指定し、env_vars で Codex の環境から転送する変数名を指定し、env で固定値を設定します。

  [mcp_servers.signal-tools]
  command = "npx"
  args = ["-y", "@craftsamo/signal-tools@<version>", "--read-only"]
  env_vars = ["SIGNAL_TOOLS_STATE_DIR"]
  

アカウントと同期サービス

このツールは、ユーザーのスマートフォンのSignalアカウントにリンクされたデバイスとして、Signal Desktopと同じ方法で、signal-cliを介して利用します。signal-cliはご自身でインストールしてください。ほかのクライアントのデータを読み取ることはありません。

• リンクされた各デバイスにはラベルが付きます。ラベルは、小文字の英字、数字、_を使った1〜24文字です（名前を指定せずにリンクした場合はdefault）。ツールのaccount引数でラベルを指定します。リンク済みデバイスが1台だけの場合は省略できます。
• 各ラベルの状態は1つのディレクトリに保存されます。<state_dir>/<label>/（モード700）に、signal-cliのデータとキー、デーモンのソケット、受信メッセージのミラー、送信するファイルのコピーが保存されます。state_dirの既定値は$XDG_STATE_HOME/signal-tools、または~/.local/state/signal-toolsです。共有するバックアップには含めないでください。キーを使うと、ユーザー自身として読み取りや送信が行われます。
• 同期サービスはラベルごとに受信し、そのミラーを保持します。読み取りツールが読むのはミラーのみです。履歴はデバイスをリンクした時点から始まります。サービス停止中に届いたメッセージは、Signalが未配信メッセージを保持している間、Signalのサーバーで待機します。
• 45日間使用されていないデバイスと、スマートフォンが30日間オフラインの場合は、リンク済みのすべてのデバイスがSignalによってリンク解除されます。サービスを実行していれば、デバイスは使用中として扱われます。リンク解除されたラベルは、スマートフォンから再度リンクします。
• signal-cliのリリースには有効期限があります。リリースから約3か月を超えると、Signalのサーバーで動作しなくなることがあります。最新の状態に保ってください。

デバイスのリンクと同期サービスの実行

このツールはsignal-cli 0.14でテストされています。まずsignal-cliをインストールしてください。macOSの場合はbrew install signal-cliを実行します。それ以外の場合は、リリースを利用してください（JVMビルドにはJava 25以降が必要です）。macOSとLinuxに対応しています。Windowsについては#11をご覧ください。

# Link: on the phone, Signal > Settings > Linked devices > Link new device,
# then scan the code this prints.
signal-tools-cli link --account work

# Start receiving at logon, and restart after a failure.
signal-tools-cli service install --account work
signal-tools-cli service status --account work

ラベルが1つだけの場合は、--accountを省略できます（linkは新しいラベルにdefaultという名前を付けます）。すべてのコマンドで、ツールと同様に--state-dirを指定できます。

コマンド	動作
link [--account <label>] [--device-name <n>]	このマシンをスマートフォンのデバイスとしてリンクし、スキャンするコードを表示します。--show-uriを指定すると、コードが表すアドレスも表示します
sync [--account <label>]	停止するまで、標準エラーにログを出力しながら同期サービスをフォアグラウンドで実行します
service install | uninstall | status	同期サービスをlaunchdエージェント（macOS）またはsystemdユーザーユニット（Linux）として登録、削除、または状態を表示します
remove --account <label> [--yes]	ラベルを再入力すると、サービスをアンインストールし、そのラベルのキー、signal-cliのデータ、履歴、サービスログを削除します

• サービスは、このパッケージのパスを記録します。パッケージを更新した後は、service installを再度実行してください。macOSのログは~/Library/Logs/io.github.craft-agent.signal-tools/<label>.logにあります。Linuxでは、service statusに表示されるjournalctl --user -u <unit>を確認してください。loginctl enable-lingerを実行すると、ログアウト中もサービスが実行されます。
• スマートフォンにリンクできるデバイスは最大5台で、各ラベルがそのうちの1台にあたります。
• ラベルを削除しても、スマートフォン上ではリンク解除されません。リンク済みデバイスは自分自身を解除できないため、「設定」>「リンク済みデバイス」からも削除してください。
• Signalによってリンク解除されたラベルを再度リンクするには、linkを再実行してください。古いキーは別の場所に移され、スマートフォンで同じアカウントを使用している限り、履歴は保持されます。別のアカウントには、専用のラベルが割り当てられます。
• signal_account_readを使うと、ラベルに必要な手順をエージェントに伝えられます。

構成

• src/project.ts — パッケージ名、ツール ID のプレフィックス、設定のプレフィックス、ツールセットです。
• src/core/ — ハーネスやプロジェクト名に依存しない、ツールの契約とツールです。
• src/tools.ts — 各エントリーポイントが登録する、すべてのツールの一覧です。
• src/mcp/ — MCP サーバーです。dist/mcp.js にビルドされ、signal-tools によって実行されます。
• src/opencode/ — OpenCode プラグインです。dist/opencode.js にビルドされます。
• src/cli/ — Hermes プラグインが呼び出すコマンドラインです。dist/cli.js にビルドされ、signal-tools-cli によって実行されます。
• src/hermes/、plugin.yaml、__init__.py — Hermes プラグインです。
• skills/ — ツールセットごとに 1 つのスキルがあります。skills/<name>/SKILL.md は、スキルを利用する各ハーネスによって、パッケージまたはプラグインのルートから読み込まれます。
• .claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、.antigravity-plugin/、mcp_config.json — その他のハーネス用のプラグインマニフェストです。Codex は .codex-plugin/plugin.json を読み込みます。ルートに plugin.json があると、プラグインを Agent Plugin として読み込みますが、そのツール予算では固定サイズを超えるツールが非表示になります。ルートの .mcp.json は Grok Build が読み込む設定です（Grok Build と Claude Code の両方が展開する変数 ${CLAUDE_PLUGIN_ROOT} を使用します）。Claude Code でこのリポジトリを作業する際は、このファイルから提示されるプロジェクト MCP サーバーを拒否してください。

リリースの作成方法については、RELEASING.md を参照してください。

ライセンス

MIT