Claude Code フック連携

コマンドを自分で実行しなくても、Claude Codeが今何をしているかをライトがどうやって把握しているのか。

andon-light install-hooks を一度実行すれば、あとはライトが自動的に更新されます。日常的に自分でコマンドを打つ必要はありません。このページでは、その設定が実際に何をしているのか、なぜこの作り方になっているのかを説明します。何か気になる動きがあった時の参考にしてください。

Claude Codeには「フック」という仕組みがあります。これは、Claude Codeの動作の節目節目（「セッションが始まった瞬間」や「あなたの許可を待つ直前」など）で、自動的にコマンドを実行させられる仕組みです。連携をインストールすると、それぞれの節目に対して、適切な色で andon-light を呼び出すよう設定されます。

それぞれの色が呼び出されるタイミング

これらのコマンドは、バックグラウンドではなく、ひとつずつ順番に実行されます：これは見た目以上に重要な設計です（詳しくはバックグラウンドで実行しない理由を参照）。この設定は、インストール時に選んだ範囲に応じて、Claude Codeのグローバル設定か、単一プロジェクトの設定のどちらかに組み込まれます。USB接続の先に何がつながっているかを知る必要はありません。ただ andon-light を呼び出すだけで、あとはファームウェアが処理します。このファイルを編集した場合は、変更を反映させるためにClaude Codeを再起動（または新しいセッションを開始）してください。

いくつかの設計判断について

「ツールを使う直前」が重要な理由

上の表にあるタイミングのほとんどは一度きりです：プロンプトの送信も、通知も、それぞれ一度しか起きません。しかし、Claude Codeからの1つの応答の中で、ツール呼び出し（ファイルの読み込み、コマンドの実行、コードの編集など）が何十回と連続することがあります。その間、他に何もライトに触れるものがなければ、ライトは更新されないままになってしまいます。「すべてのツール呼び出しの直前」にフックを仕込むことで、その間ずっとライトが継続的に更新され続け、作業の途中でウォッチドッグがタイムアウトして「接続が途切れた状態」のパルス表示になってしまうのを防いでいます。これでカバーしきれないのは、ツール呼び出しが一切ない、思考だけのターンです（「まだ文章を生成中」というタイミング用のフックはClaude Codeには存在しません）。ただ、これは30分というウォッチドッグのタイムアウトに比べればずっと短い時間なので、実用上の問題にはなりません。

権限確認だけ、一般的な通知とは別扱いになっている理由

どちらも最終的には同じ黄色になるので、実際にはどちらが発動しても大きな違いはありません。ただ、「権限確認待ち」（コマンドの承認など）専用のフックを用意しておくことで、この特定のタイミングをより正確に、他の通知と混同せずに扱えるようになります。

内部整理だけ専用の見た目がある理由

専用のパターンがなければ、内部整理中はそれまでの色をそのまま表示し続けるか（それが赤・アイドルだった場合、誤解を招きます）、終わった後に元の色へ戻すためだけの追加フックが必要になってしまいます。順次点灯パターンなら、ひと目で「まだ生きていて、片付け作業をしている」と伝わりますし、次のフックが発動すれば自然に次の状態へ移り変わります：「整理完了」を知らせる追加のフックは不要です。

セッション開始時に、あえてアイドルにする理由

これがないと、新しいセッションは前のセッションが最後に残した色をそのまま引き継いでしまいます。通常のセッション終了は問題なくアイドルに戻るので、たいていは問題になりません。ただ、前のセッションが途中でクラッシュしていた場合はその限りではありません。セッション開始時に明示的にアイドルへ設定しておくことで、こうした「毎回きれいに終わってくれるはず」という前提に頼らずに済みます。

セッション終了とターン終了が別扱いになっている理由

Claude Codeを作業の途中で中断した場合（Ctrl+C）、これは通常のターン終了とは異なる止まり方で、「ターンが終了した」フックだけでは拾いきれません。そのままだとライトが最後の色のまま固まってしまいます。「セッションが何らかの理由で終了した」フックは、終了の理由を問わず発動するため、これをカバーします。通常の「ターン終了」フックもそのまま残しているので、よくあるケース（正常終了）では、セッション全体の後始末を待たずに、できるだけ早く反映されます。

バックグラウンドで実行しない理由

もともとは、実際のツール呼び出しに一切遅延を加えないよう、これらのコマンドはすべてバックグラウンドで実行されていました。ですが、そのトレードオフには見合う価値がないとわかりました。バックグラウンド実行が保証するのは、それぞれのコマンドが正しい順番で「開始される」ことだけで、正しい順番で「完了する」ことではありません。andon-light の呼び出しはそれぞれ独立した短命なプログラムで、速いとはいえ瞬時ではありません。そのため、負荷が高い状況（ツール呼び出しが連続するような場面）では、先に始まったコマンドより、後から始まったコマンドの方が先に終わってしまうことがあります。実際に起きた例で言うと、セッションが正しく赤（アイドル）で終わったのに、セッションの途中で発動していた黄色（対応待ち）のコマンドの完了が少し遅れていて、それがちょうど赤の後に完了してしまい、正しい赤を古い黄色で静かに上書きしてしまう、というケースがありました。

ひとつずつ順番に実行するようにすると、Claude Codeは各コマンドの完了を待ってから次に進むため、ライトが常に本当の出来事の順序を反映することが保証されます。1回あたりの待ち時間は、実際のツール呼び出しにかかる時間と比べれば気にならないほど小さいので、バックグラウンド実行で節約できるはずだった遅延は、順序が崩れるリスクに見合うものではありませんでした。

すべてのコマンドが静かに失敗するように作られている理由

ボードが抜けている時や、ボードが接続されていないパソコンでこのツールを実行した時、対策をしていなければ、すべてのフックがプロンプトのたびにClaude Code内で大きなエラーを表示してしまいます。これでは、本来静かに背後で動いているはずのステータスライトとしての意味がなくなってしまいます。この挙動は、ツールが自動的に再接続したり、デバイスが本当に見つからない状態をうまく扱えたりするようになった時点で見直す価値があります。その時点で初めて、本当に切れている接続を、黙って無視するのではなく表に出す価値が出てきます。