Clotr Guard

Clotr Guard

Clotr Guard は、対応する AI コーディングアシスタントのフックを通じて、プロンプトとファイルの読み取りをチェックします。テキストファイルを自分でチェックしたり、Git の pre-commit チェックを設定したりすることもできます。Clotr のほかのアプリと同じオンデバイスエンジンを使用します。問題のないプロンプトはそのまま通過します。中程度または高程度の検出結果がある場合、そのプロンプトを一時停止し、種類とマスクされた形式を表示します。低程度の検出結果は、stderr に短いメッセージを 1 行表示して通過します。デフォルトでは、メールアドレス、ナンバープレート、ゲーマータグ、共有リンクは許可されます。同じプロンプトを 2 分以内にもう一度送信すると、そのまま送信されます。新たな検出結果がある場合は、再び一時停止します。

Clotr Guard は、macOS と Linux 上で Claude Code、Cursor、Gemini CLI、Codex CLI、Windsurf Cascade、Cline のフックに対応しています。チェックはお使いのコンピューター上で実行されます。Clotr Guard はネットワーク接続を行わず、テキストを Clotr サーバーに送信することもありません。アシスタントによる送信が許可されたプロンプトは、通常どおりそのアシスタントの AI サービスに送信されます。Guard には Node.js 20 以降が必要です。

ローカルで実行

clotr-mcp サーバーを含む Guard は、お使いのマシン上で AI クライアントの子プロセスとして実行され、stdio（標準入力と標準出力）を介してクライアントと通信します。ネットワーク接続は開かず、スキャンしたテキストを保存することもありません。一時停止されたプロンプトを再送信できるよう、プロンプトフックは検出した内容のソルト付きフィンガープリントを 2 分間保持しますが、テキストそのものは保持しません。MCP では、ツールを提供する側をプロトコル上の役割名として「サーバー」と呼びます。リモートマシンであることを意味するわけではありません。

安定機能とプレビュー機能

安定機能には、変更のたびに実行されるテストがあり、このページの説明どおりに動作します。プレビュー機能もテストされていますが、まだ変更される可能性があり、その理由は表の下に記載されています。

機能	状態	テスト
Claude Code、Cursor、Gemini CLI、Codex CLI、Windsurf Cascade、Cline でのプロンプトチェック	安定	guard.test.js
停止されたプロンプトを 2 分以内に再送信	安定	guard.test.js
Claude Code、Cursor、Gemini CLI、Windsurf Cascade、Cline でのファイル読み取りチェック	安定	guard.test.js
各ファイル読み取りチェックによる秘密ファイルのブロック	安定	guard.test.js
Claude Code と Cursor での MCP ツール呼び出しチェック	安定	guard.test.js
Claude Code と Cursor でのシェルコマンドチェック	プレビュー	guard.test.js
setup と remove（--project と --dry-run を含む）	安定	guard.test.js
macOS と Linux での Cline フック	安定	guard.test.js
check、commit-check、Git pre-commit フック	安定	guard.test.js
clotr-mcp（または clotr-guard mcp）と 3 つのツール	プレビュー	mcp.test.js
アシスタントのスキル	プレビュー	guard.test.js
ネットワーク接続を行わないこと	安定	rules.test.js

シェルチェックがプレビュー機能なのは、ファイルや環境の内容を表示する一般的な方法には対応していますが、認識できないコマンドでも内容を表示できる場合があるためです。clotr-mcp は、アシスタントが呼び出すと判断した場合にのみ実行され、そのツールはアシスタントの利用状況に応じて変更される可能性があります。スキルは新しく、各アシスタントはそれぞれ独自のフォルダー内でスキルを検索します。

インストール

グローバルにインストールします。

npm install -g clotr-guard

フックのセットアップと clotr-mcp --print-config は npx 経由で実行すると停止し、先に Guard をグローバルにインストールするよう案内します。MCP サーバーは npx から直接実行できる唯一の部分で、npx -y clotr-guard mcp として実行します。

クローンからインストールする

リポジトリのルートから、まず node tools/engine-bundle.js --out apps/guard/dist/clotr-engine.js でエンジンバンドルをビルドし、次に npm link ./apps/guard を実行して、 clotr-guard と clotr-mcp コマンドを PATH に追加します。代わりに node apps/guard/bin/clotr-guard.js を実行することもできます。この バンドルはチェックイン済みのエンジンファイルからビルドされますが、バンドル自体はチェックインされていないため、ビルドするまでは、どのチェックでも Clotr はテキストをチェックできなかったと応答します。エンジンを変更した後は再度ビルドしてください。古いコピーを使っていると npm test が失敗します。

アシスタントに Clotr MCP を追加する

MCP サーバーは Guard パッケージに含まれており、そのエンジンとシークレットファイルのルールを使用します。clotr-mcp または clotr-guard mcp で起動でき、どちらも同じサーバーを実行します。Guard をインストールした後、使用するアシスタント向けの設定スニペットを表示します。

clotr-mcp --print-config claude
clotr-mcp --print-config cursor
clotr-mcp --print-config gemini
clotr-mcp --print-config codex
clotr-mcp --print-config windsurf
clotr-mcp --print-config cline
clotr-mcp --print-config vscode

スニペットを、Claude Code の .mcp.json または MCP 設定、Cursor のプロジェクトまたはユーザーの MCP 設定、Gemini CLI の ~/.gemini/settings.json またはプロジェクトの .gemini/settings.json、Windsurf の MCP 設定、Cline の MCP サーバー設定 または CLI 用の ~/.cline/data/settings/cline_mcp_settings.json、VS Code の servers 配下にある .vscode/mcp.json、または Codex CLI の [mcp_servers.clotr] 配下にある ~/.codex/config.toml に追加します。 Gemini CLI の MCP ガイドでは、mcpServers の設定について説明しています。

グローバルインストールを省略するには、代わりにアシスタントの接続先として npx を指定します。サーバーの初回起動時に、npm が Guard をキャッシュにダウンロードします。

{
  "mcpServers": {
    "clotr": { "command": "npx", "args": ["-y", "clotr-guard", "mcp"] }
  }
}

サーバーはこのコンピューター上で、標準入力と標準出力を介して実行されます。アシスタントから呼び出されたときだけチェックを行い、検出項目の種類とマスクされた形式を返します。include_personal_details を有効にすると、check_text と clean_text に個人情報が追加されます。どちらの場合も、認証情報はチェックされます。

アシスタントに Clotr スキルを設定する

このパッケージには、コーディングアシスタント向けのスキルファイル skills/clotr/SKILL.md が含まれています。このファイルは、Clotr が何かを止めたとき、同じテキストを取得する別の方法を試すのではなく、何が止められたのかを伝え、選択をユーザーに委ねるようアシスタントに指示します。また、MCP ツールの呼び出し方も説明しています。skills/clotr フォルダーを、Claude Code の場合は ~/.claude/skills/clotr に、Codex CLI、Gemini CLI、Cursor の場合は ~/.agents/skills/clotr にコピーします。インストールされたコピーは、npm root -g が出力するフォルダー内の clotr-guard/skills/clotr にあります。

フックを設定する

使用するアシスタントごとに、コマンドを 1 つ実行します。

clotr-guard setup claude
clotr-guard setup cursor
clotr-guard setup gemini
clotr-guard setup codex
clotr-guard setup windsurf
clotr-guard setup cline
clotr-guard setup git

これらのコマンドは、プロンプトフックと、サポートされている場合はファイル読み取りフックをユーザー設定に追加します。プロジェクト内で --project を指定してコマンドを実行すると、代わりにそのプロジェクトの設定に追加されます。変更内容を事前に確認するには --dry-run を使用します。Clotr のフックを削除するには clotr-guard remove <tool> を実行します。プロジェクトのフックを削除するには --project を追加します。変更を書き込む前に、Clotr は既存の設定ファイルのコピーを同じ場所に .clotr-guard.bak を末尾に付けて保存します。ユーザー自身の .bak はそのまま残します。setup git は現在のリポジトリにローカルの pre-commit フックをインストールし、remove git はそれを削除するか、以前そこにあったフックを復元します。 Claude Code は ~/.claude/settings.json と UserPromptSubmit フックを使用します。Cursor は ~/.cursor/hooks.json と beforeSubmitPrompt を使用します。Gemini CLI は ~/.gemini/settings.json と BeforeAgent を使用します。Codex CLI は ~/.codex/hooks.json と UserPromptSubmit を使用します。Windsurf Cascade は ~/.codeium/windsurf/hooks.json、pre_user_prompt および pre_read_code を使用します。プロジェクトのセットアップでは .devin/hooks.json を使用するか、既存の .windsurf/hooks.json が 有効な旧形式のファイルであればそれを使用します。Cline は ~/Documents/Cline/Hooks/ にある拡張子のない実行可能フックと、その UserPromptSubmit および PreToolUse イベントを使用します。プロジェクトのセットアップでは .clinerules/hooks/ を使用します。Cline では、Feature Settings で Enable Hooks をオンにしてください。Cline のフックガイドには、サポートされている イベントとプラットフォームが記載されています。Cline のフックは macOS と Linux でのみサポートされています。その他のプロジェクト設定ファイルは、現在のディレクトリにある .claude/settings.json、 .cursor/hooks.json、.gemini/settings.json、.codex/hooks.json です。

プロンプト、ファイル読み取り、コミットのチェックでは、デフォルトで個人情報を除外し、認証情報のチェックは継続します。個人情報も含めるには、Guard フックのセットアップまたは commit-check に --personal-details を追加します。ここでは、内部ネットワークアドレスやホスト名も個人情報として扱います。 このオプションをオンにすると、Guard は短いメッセージでその情報を示しますが、プロンプト、読み取り、コミットは許可します。自分のサーバーについてアシスタントに伝えるのは通常の作業だからです。

プロンプトフックがチェックするのは、各ツールがフックに送信するプロンプトフィールドのみです。Claude Code は mcp__ ツールの引数もチェックし、 Cursor は MCP 引数とシェルコマンドをチェックします。これらのチェックでは、認証情報および中程度または高程度の検出結果をブロックし、ツールが確認をサポートしている場合はユーザーに判断を求めます。 Bash フックとシェルフックは、コマンド、一般的な環境変数のダンプ、秘密ファイルを表示する可能性のあるファイル読み取りツールから認証情報を探します。 読み取りやコミットと同じ秘密ファイルのルールを使用します。通常のコマンド文字列はスキャンしません。ファイル読み取りフックは、Claude Code の Read、Cursor のエージェントによるファイル 読み取り、Gemini CLI の read_file、Windsurf Cascade の pre_read_code、Cline の PreToolUse をチェックします。バイナリファイルとフォルダーは、メッセージを表示せずに通過します。バイトオーダーマークの有無にかかわらず UTF-16 で保存されたテキストや、古いシングルバイト文字コードのテキストも、ほかのテキストと同様にチェックされます。大きなテキストの読み取りでは最初の 256 KiB をチェックし、残りはチェックされていないことを通知します。読み取りフックには、検出の種類とマスクされた形式のみが表示されます。秘密ファイルは、理由をアシスタントに示してすべてのツールで拒否され、ユーザーへの確認は求められません。Claude Code では、認証情報を含む通常のファイルを読み取る際に、許可するかどうかを確認します。ほかのツールでは読み取りを停止します。2 回目の読み取りはユーザーではなくアシスタントが行うため、同じファイルを再度読み取っても許可されないからです。Claude Code には、秘密ファイルを表示したり環境変数をダンプしたりする単純なコマンド用の Bash フックもあります。Gemini CLI はデフォルトで .env ファイルも読み込みます。setup gemini の後、Clotr は Gemini の settings.json で advanced.ignoreLocalEnv を使ってこれをオフにする方法を表示します。Clotr がこの設定を変更することはありません。フックの検出メッセージに値全体が含まれることはありません。Windows では、Clotr は %LOCALAPPDATA%\Clotr\guard に繰り返し検出用の記録を保持します。それ以外のシステムでは、ユーザーごとのアプリケーションデータフォルダーを使用します。この記録はローカルの平文状態であり、同じコンピューターアカウントまたはそのプロセスから読み取れます。Guard が同期することはありません。記録には、ランダムなソルト、検出結果のソルト付きフィンガープリント、最初に警告した時刻が含まれます。 Clotr がプロンプトのテキストやファイルの内容を保存することはありません。読み取り可能な入力をチェック中に Clotr で内部エラーが発生した場合、Guard はチェックされずに通過したことを示す注記を表示して、操作を許可します。Guard は、不正な形式のフック入力やサイズ制限を超えるテキストなど、読み取れない入力を停止します。Claude Code、Gemini CLI、Codex CLI では、各チェックに最大 15 秒が割り当てられます。

検索結果

読み取りフックは、一致する行を返す検索もチェックします。Claude Code の Grep では output_mode: "content" の場合のみ、Gemini CLI の search_file_content と grep_search、Cline の search_files、Gemini の read_many_files が対象です。Claude の files_with_matches モードと count モードはパスまたは件数を返すため、チェックを通過します。Guard は検索パスと include glob をチェックし、その後、.git と node_modules をスキップしながら、最大 2,048 件のエントリーまたは合計 250 ms までたどります。Ripgrep と Git の到達可能性プローブも同じ時間制限を共有します。制限に達した場合、検索は通過し、Guard は stderr にメモを書き込みます。

Guard は、見つかったファイルを返せるかどうかを判断する際に、各ツールのフィルターに従います。

• Claude Code の Grep は、隠しパスを有効にして ripgrep を実行します。ripgrep の ignore ルールは引き続き適用されます。Ripgrep の FAQ では、ignore ファイルの動作について説明しています。
• Cline の search_files は --hidden を付けずに ripgrep を呼び出すため、.env などの隠しパスは、ripgrep の通常の無視対象パスとともにスキップされます。ripgrep が利用できない場合、Cline のフォールバックは拡張子の許可リストを使用し、拡張子のないドットファイルをスキップします。Cline の検索エグゼキューターを参照してください。
• Gemini のコンテンツ検索は、まず git grep --untracked を試します。これは Git で無視される未追跡ファイルをスキップしますが、追跡対象のファイルは検索できます。システムの grep によるフォールバックでは、隠しファイルや無視対象ファイルが含まれる場合があります。names_only はパスのみを返し、exclude_pattern はファイル名ではなく一致する行をフィルターします。Gemini の grep ツールを参照してください。
• Gemini の read_many_files は glob パターンを使用し、ドットファイルも含めます。デフォルトの除外対象には、.env、一般的な開発ディレクトリ、バイナリ形式が含まれます。デフォルトでは .gitignore と .geminiignore に従います。useDefaultExcludes: false を指定するか、ignore フィルタリングを無効にすると、ファイルに到達できる場合があります。Gemini の複数ファイルリーダーとデフォルトの除外対象を参照してください。

Guard がコンテンツ検索を停止すると、メッセージにシークレットを含むファイル名と、そのファイルを除外する glob の例が表示されます。

check、setup、hook または read で --min-severity low、medium、high を指定すると、停止する重大度のしきい値を変更できます。デフォルトは medium です。

テキストを自分でチェックする

ファイルを指定するか、標準入力からテキストをパイプで渡します。

clotr-guard check prompt.txt
type prompt.txt | clotr-guard check --json

このコマンドは、マスクされた検出結果を1行に1件ずつ出力し、最小重大度以上の検出結果がある場合は 1 を返します。--json を指定すると、判定とマスクされた検出結果を含む結果オブジェクトが出力されます。何も見つからない場合、ターミナルでは「Nothing found.」と表示し、出力先が別のプログラムの場合は何も出力しません。1 MiB を超えるファイルには、Clotr がテキストをチェックできない場合と同じ短いエラーが返されます。

ステージング済みの Git 変更をチェックする

コミットする前に、clotr-guard commit-check を実行してステージング済みの変更をチェックします。ステージング済み差分の追加行に加え、ステージング済みのシークレットファイル名もチェックします。シークレットファイルがステージングされていると、Git がそのファイルを無視する設定になっていてもコミットは停止します。強制的に追加されたファイルだからです。代わりに、コミット対象から外してください。認証情報が見つかると、引用符で囲まれたファイル名、行番号、種類、マスクされた値が表示されます。UTF-16 で保存されたファイルは Git にバイナリとして扱われるため、Clotr はそのファイルをステージングエリアから読み込み、直近のコミットになかった行をチェックします。--personal-details を追加しない限り、個人情報が見つかってもコミットは停止しません。作業コピーはスキャンされません。Git で許可されているとおり、git commit --no-verify を指定すると Git フックがスキップされます。

Guard はステージング済みの差分を個別に読み込みます。差分が 1 つでも 16 MiB を超えると、追加テキストの先頭 256 KiB をチェックし、ファイル名と残りの部分がチェックされなかったことを示すメッセージを表示して、コミットを停止します。変更を分割するか、大きな生成ファイルをリポジトリに含めないようにしてください。ファイルの差分を読み取れない場合、Guard はそのファイル名を表示し、ほかのステージング済みファイルをチェックした後、コミットを停止します。Git リポジトリ外での実行や、Git または Guard が見つからない場合など、チェック自体を実行できないときに限り、チェックされなかったことを示すメッセージを表示してコミットを許可します。

clotr-guard setup git は、ローカルの pre-commit フックをインストールします。リポジトリにすでにフックがある場合、Clotr はそれをフックの隣に保存し、ステージング済みの変更チェックに合格した後で呼び出します。Node.js が見つからない場合も、そのフックは実行され、Clotr のチェックがスキップされたことを示すメッセージが表示されます。そのフックを復元するには、clotr-guard remove git を使います。clotr-guard commit-check を実行するように書いたフックなど、Clotr が作成していないフックは変更されません。古いバックアップがフックの隣に残っている場合、セットアップは停止し、先にバックアップを移動するよう求めます。カスタムの core.hooksPath を設定しているリポジトリは変更されません。セットアップを再度実行すると、フックは実行元の Guard を参照するようになります。フックが参照する Guard が削除されている場合、コミットは許可され、チェックを再度セットアップするよう求めるメッセージが表示されます。チェックを実行できない場合も同様です。

pre-commit フレームワークを使う場合は、.pre-commit-config.yaml に次の内容を追加してください。

repos:
  - repo: local
    hooks:
      - id: clotr-guard
        name: Check staged changes with Clotr Guard
        entry: clotr-guard commit-check
        language: system
        pass_filenames: false
        always_run: true

グローバルにインストールした clotr-guard が実行されます。

.clotrignore

Clotr Guard は、すべてのフックと pre-commit チェックで、リポジトリのルートにある .clotrignore を読み込みます。

.clotrignore で Guard の検出結果を抑制できるのは、値のフィンガープリントが完全に一致する場合だけです。パスパターンは無視され、ファイルのチェックを無効にすることはできません。このファイルはコミットされるため、誰かが警告を黙らせるために実際のキーを貼り付けてしまうのを防ぐ目的で、値の行に生の値を記載することはできません。代わりに、clotr-guard ignore-value [--kind <kind>] は標準入力から値を読み込み（引数には指定しないため、シェルの履歴に残りません）、リポジトリごとのソルトを .clotrignore 自体に salt: <random> として保存しながら、fingerprint: <salted SHA-256> を追記します。リポジトリを読める人は誰でもソルトも読み取れ、フィンガープリントに対してありそうな値をすべて試せるため、このコマンドはパスワード、個人情報、長さや文字の多様性が不十分な値を拒否します。呼び出し元が検出結果の種類を把握している場合は、--kind <kind> を渡せます。値は引き続き標準入力から読み込まれます。拒否された値は、ソースから削除するか、エディターで一度だけ無視するようにしてください。ファイル内の生の値（value: ...）は、コマンドを使うよう案内する短いメッセージを表示して拒否されます。

シークレットファイル（共通のシークレットファイル一覧、.env など）は、Guard の個別のシークレットファイルルールで引き続き保護されます。