AIに「危険な操作はしないで」と伝えても、実行するコマンドの確認まで任せきりにはできません。Shellfirmは、端末やAIエージェントから出るコマンドを実行前に検査するオープンソースのツールです。たとえばGitの強制pushについて、危険度、影響、代わりの操作を示し、人間には確認を、エージェントには拒否などの判定を返します。
Shellfirmが調べるのは、主に実行前のコマンドや対応するツール入力です。起動したプログラムの内部動作をすべて監視する仕組みではありません。スクリプト内部や実行時に組み立てられる処理には検知できないものがあります。権限の制限、隔離環境、復元できるバックアップも併用してください。
確認日は2026年10月29日。GitHubの公開時刻は0.4.0が10月28日22:58:49 JST、0.4.1が10月29日16:14:50 JSTです。製品自体の新規登場ではなく、既存ツールの更新を扱います。本稿は0.4.1の配布バイナリと版固定の公式資料で確認しています。
今回の更新で何が変わったか
| 版 | 主な差分 | 現場で意味がある点 |
|---|---|---|
| 0.4.0 | プロジェクト・組織ポリシーの強制、エージェントフックの拡張、判定と終了コードの見直し | 個人設定で弱められないルールを共有しやすくなる。既存CIや連携設定の移行が必要 |
| 0.4.1 | キャッシュ削除や通常のGit操作などの誤検知を削減。検知パターンも追加 | 日常作業で不要な警告を減らしつつ、危険な条件は引き続き検査する |
0.4.1では、相対パスで指定するnode_modulesや一部の生成キャッシュ、git worktree addなどの通常操作を見直しています。ただし、絶対パス、変数、途中のシンボリックリンク、sudoなど、条件が違えば同じ扱いにはなりません。誤検知を減らすための限定的な修正であり、「削除コマンドをすべて安全とみなす」変更ではありません。詳細は変更履歴を参照してください。
0.4.0で変わったもう一つの点は、Claude Codeの安全と判定されたコマンドを、フック側が自動承認しなくなったことです。危険なものを止めたうえで、非該当のものはClaude Code自身の権限判定に委ねます。補助ツールが、元からある確認手順を飛ばさない設計になっています。
「人に確認する」と「AIを止める」は別の動作
| 使う場所 | 何をするか | 注意点 |
|---|---|---|
| 人間の対話型ターミナル | シェルフックで入力を検査し、計算問題・Enter・yesなどの確認を出す | 危険度や実行状況で確認が厳しくなる。denyルールは確認で通せない |
| Claude CodeなどのAIエージェント | エージェント用フックでツール実行の直前に判定を返す | 対話シェル用フックを入れただけでは、AIの実行経路を保護したことにならない |
| MCP | 危険性や代替案を問い合わせる道具として利用する | AIが必要なときに呼ぶ相談機能と、自動で毎回検査するフックは役割が違う |
| CI・自作スクリプト | checkのJSONや終了コードで処理を分岐する | 非ゼロ終了の扱いを実装しないと、レポートを出すだけで通過してしまう |
フックとは、決まったタイミングで別の処理を呼ぶ仕組みです。Shellfirmは実行の直前に検査を挟みます。MCPはAIから外部の道具を呼ぶための接続方式で、この製品ではcheck_commandやexplain_riskなどを提供します。基本のルール判定に別のLLM契約は不要です。LLMによる追加分析は実験機能で、設定・有効化が必要な別の経路です。公式README
Macで確認：コマンドを実行せず判定だけ試す
ふくふくではApple SiliconのMacで公式0.4.1バイナリを使い、一時的なGitリポジトリと専用設定ディレクトリで試しました。checkに--no-contextを付け、検査に伴う外部プログラムの呼び出しも抑えています。入力した削除・push・rebase自体は実行していません。
| 検査した文字列 | decision | 終了コード | 読み方 |
|---|---|---|---|
| git status --short | allow | 0 | この条件では危険なルールに該当しない |
| git push --force origin main | deny | 11 | 強制pushを拒否と判定 |
| git rebase -i HEAD~3 | ask | 10 | 人間の確認が必要と判定 |
| rm -rf node_modules | allow | 0 | 相対パスの依存関係フォルダをこの条件では許可 |
| chmod 600 .env | allow | 0 | 所有者だけに権限を絞る指定はこの条件では許可 |
node_modulesには確認用のファイルを置き、検査後も残っていることを確認しました。また、git:force_pushをdenyするプロジェクトポリシーを検証し、模擬のClaude Codeフック入力に対してpermissionDecision: denyが返ることも確認しています。実際のClaude Codeセッションや対話シェルを通した一連の運用は未検証です。速度、誤検知率、事故防止率を測った試験でもありません。
shellfirm --versionshellfirm check --no-context -c 'git status --short' --format json --exit-codeshellfirm check --no-context -c 'git push --force origin main' --format json --exit-code別の一時ディレクトリでの追試では、同じnode_modules削除文字列がask・10になることも確認しました。再現教材の合否判定はGit関連の3ケースに絞っています。同じコマンドでも、設定、現在のブランチ、対象パス、組織ポリシーで結果が変わります。--no-contextも完全な状況無視ではなく、ユーザーID、環境変数、.git/HEADなどは参照されます。結果が表と違う場合はmatched_rules、decision_reason、policy_sourcesを読み、まず違いの原因を調べてください。checkの仕様
導入条件：無料のCLIだが、シェルごとの対応差がある
ライセンスはApache-2.0です。公式リリースにはLinuxとmacOSのx86_64・aarch64、Windowsのx86_64向け配布物があります。npm、Homebrew、Cargoからの導入方法も案内されています。日本語で書いた開発指示に組み込めますが、検査対象はシェルコマンドで、メッセージは主に英語です。今回、日本語UIの提供は確認していません。配布物・ライセンス
| シェル | 0.4.1公式資料の説明 |
|---|---|
| Bash / Zsh / Fish / Elvish / Xonsh | 開発元が一連の動作をテスト済み。ただし関数や動的生成処理に固有の制限あり |
| Nushell | 組み込みrmやmvなどは確認をキャンセルしても止められない。警告として扱う |
| PowerShell / Oils | フックは配布されているが、開発元の一連の動作テストは未実施 |
Windows用バイナリがあることと、あらゆるPowerShell操作が確実に止まることは別です。OS名だけで選ばず、普段使うシェルとAI側の実行ツールをセットで確かめましょう。
まず検査を試し、その後にフックを接続する
- 1公式リリースまたは案内されたパッケージ管理方法で導入し、shellfirm --versionを確認する。この記事の再現対象は0.4.1。
- 2作業用の一時ディレクトリでcheckを試す。自動判定用の小さな教材は下のリンクから取得できる。
- 3人が打つ端末に適用するならshellfirm init --dry-runで変更予定を確認し、対象シェルのinitを実行して端末を開き直す。
- 4Claude Codeを使うならshellfirm connect claude-codeでエージェント用フックとMCPを接続し、セッションを再起動する。既存設定の差分とバックアップも確認する。
- 5shellfirm statusとshellfirm doctorで、導入ファイルがあるだけでなく実際の経路を確認する。隔離した検証用プロジェクトで拒否されるケースと通常作業が通るケースを両方試す。
# Node.js / npmが利用できる場合の、版を固定した導入例npm install -g @shellfirm/cli@0.4.1
# 対話型のZshに接続する場合shellfirm init --dry-runshellfirm init zsh# 新しいターミナルを開いた後shellfirm statusshellfirm doctor
# Claude Codeの実行前チェックを接続する場合shellfirm connect claude-codeClaude Code連携は、Shellfirmの公式変更履歴で2.1.295未満の場合に別オプションが必要とされています。古いクライアントではfail-closed（検査が正常に終わらなければ通さない仕組み）の条件も変わるため、対応版へ更新できるかを先に確認してください。Cursorの連携もありますが、開発元は同じfail-closed状態とは扱っていません。各製品の連携設定を同一視しないことが大切です。
チームでは「お願い」を共有ポリシーにする
たとえば「AIや担当者がmainへ強制pushしない」という方針を、リポジトリ直下の.shellfirm.yamlに記録できます。下の例はブランチに限定せず、ルールgit:force_pushに該当する操作を拒否します。意図より広く止めないか、導入前にチームで確認してください。
version: 1deny: - git:force_pushshellfirm policy validate --strictshellfirm policy show0.4.0以降は、ポリシー側の拒否や強化した条件を個人のignoreなどで弱められません。組織の基準は/etc/shellfirm/policy.yamlなどにも置けます。ただし、そのファイル自体を書き換えられる権限まで消えるわけではありません。組織用ファイルの所有権・書き込み権限も管理し、変更はレビュー対象にします。チームポリシー仕様
0.3.10からの更新は、バイナリ交換だけで終わらない
- 開いているシェルを再起動する。Elvish・Xonsh・Nushellはinitを再実行し、旧式フックから更新する。
- 接続済みAIごとにconnectを再実行する。旧フックのままでは、新しいファイルツール検査などが有効にならない。
- CIの「終了コードが2なら危険」という条件を修正する。0.4系のcheck --exit-codeはaskが10、denyが11。2は使い方のエラー。
- JSONを読む処理はschema_version: 2とdecision: allow / ask / denyに対応する。レポートの出力先は標準出力になった。
- 保存済み設定のenabled_groupsに新グループが含まれないことがある。statusが示す未有効グループを読み、意図して無効にしたものと区別して有効化する。
CIでは「2だけ拒否」より、検査に成功しなかったら処理を止める設計が基本です。ただし--hookモードはJSONで判定を返す専用プロトコルで、正常に拒否結果を返した場合でも通常の終了コードは0です。checkの終了コードとフックの終了コードを混同しないでください。移行手順
教材：実コマンドを動かさず、許可・確認・拒否を確かめる
判定テスト用Python教材をダウンロード。Python 3、GitとShellfirm 0.4.1を使います。専用の一時ディレクトリを作り、コマンドを文字列としてcheckに渡すだけです。削除、push、rebaseは実行せず、普段のシェルやClaude Code設定も変更しません。
python3 shellfirm-check-lab.py /path/to/shellfirm教材はallow・ask・denyと0・10・11の対応を表示し、結果が期待と違えば異常終了します。環境に組織ポリシーがあると結果が変わる場合があります。そのときは制限を外すのではなく、出力された理由を確認してください。教材の成功は、この少数の入力に対する判定確認であり、実際のエージェント連携全体の保証ではありません。
LLMに導入を手伝わせるための日本語指示文
この開発環境へのShellfirm導入案を作ってください。
1. OS・シェル・AIエージェントの版と、既存のフック・権限設定を読み取りで確認する。秘密情報は表示しない。
2. Shellfirm 0.4.1の公式資料と照合し、対応する経路、非対応や未検証の経路、設定変更の差分を示す。
3. 最初は隔離した一時プロジェクトでcheckだけを使い、許可・確認・拒否を確認する。危険コマンドそのものを実行しない。
4. 接続設定の適用前に変更案を提示する。既存の保護設定を削除・弱体化しない。
5. 適用後はstatus・doctorと、検証用プロジェクトでフックの動作を確かめる。未検証の経路は明記する。
6. 警告を消すためだけにignoreや権限緩和を追加しない。誤検知の場合は理由と限定的な修正案を示す。導入判断：小さく試し、止まった理由を読める運用に
Shellfirmは、AIに大きな権限を渡す前に、よくある危険操作を目に見える形で検査したいチームに向いています。まず検査だけを試し、次に少人数の開発環境でフックを接続し、正当な作業がどれだけ止まるかを記録すると判断しやすくなります。
一方、外部スクリプトの内部、一般的な秘密情報の送信、APIを通じた削除など、検知しきれない経路も公式READMEに記載されています。allowは「この検査で該当しなかった」という意味です。隔離環境や最小限の権限を残し、復旧方法まで用意したうえで、実行前の確認を増やす道具として使いましょう。関連するClaude Code連載も参考になります。