CLAUDE_CLIENT_PRESENCE_FILEで画面ロック解除中のpushを止める

Claude Codeの画面ロック中だけモバイルpushを止める仕組み

Claude Code Remote Control接続中、長時間タスクの完了時や判断が必要なときにスマホへpush通知を送ります。ターミナルに向かって操作している間は、Claude Codeが直近のキー入力やフォーカス状態を検知して自動でpushを止めます。

問題は、机の前にいてもターミナル以外のウィンドウを見ている在席中の時間です。ドキュメントを読んでいる、他のアプリで打ち合わせのメモを取っているといった時間帯は、キー入力とフォーカスによる検知では「操作中」と判定されず、pushが届いてしまいます。CLAUDE_CLIENT_PRESENCE_FILEは、この「フォーカスは外れているが在席している」時間帯までpush抑制の範囲を広げるために追加された環境変数です。この機能はClaude Code v2.1.181以降が対象です。

外部の画面ロック監視ツールが画面ロック解除時に作成し、ロック時に削除するマーカーファイルのパスを指定します。ファイルが存在する間はRemote Controlのモバイルpushをスキップし、ファイルが存在しない、または読み取れない場合は通常どおり通知が届きます。Claude Codeはこの判定をポーリングではなく、push発生イベントごとに1回だけ行います。バックグラウンドで常時ファイルを監視する処理はありません。

設定手順

ステップ1: マーカーファイルのパスを決める

任意の場所にファイルパスを決めます。ファイルの中身は使われないため、存在の有無だけが判定材料になります。

export CLAUDE_CLIENT_PRESENCE_FILE="$HOME/.claude/presence.lock"

ステップ2: シェルの設定ファイルに追記する

毎回のセッションで有効にするには、シェルの設定ファイルに書き込みます。設定方法は環境変数全般と共通です。bashを使っている場合は~/.bashrc、fishの場合は~/.config/fish/config.fishに、それぞれのシェルの文法で追記します。Windowsではsetx CLAUDE_CLIENT_PRESENCE_FILE "%USERPROFILE%\.claude\presence.lock"のようにコマンドプロンプトから設定すると、次回以降のセッションでも値が引き継がれます。

echo 'export CLAUDE_CLIENT_PRESENCE_FILE="$HOME/.claude/presence.lock"' >> ~/.zshrc

ステップ3: 画面ロック解除・ロックにファイル作成・削除を紐づける

CLAUDE_CLIENT_PRESENCE_FILE自体はファイルの生成・削除を行いません。OS側の画面ロックイベントを検知して、指定したパスにファイルを作る・消す処理は、別の外部ツール(画面ロックリスナーやログイン/ログアウトフックのスクリプト)で用意する必要があります。

具体的な紐づけ方はOSごとに異なります。公式ドキュメントの記述も「screen-lock listener or similar tool(画面ロックリスナーなどの外部ツール)」までで、具体的な実装は指定していません。以下は一般的な仕組みを組み合わせた例であり、Claude Code公式が保証する手順ではありません。

macOS: 画面ロックの状態を監視するスクリプトを用意し、ロック解除時にtouch、ロック時にrmを実行させる方法があります。ロック・解除イベントの検知方法はlaunchdエージェントやログイン/ログアウトフックなど複数の選択肢があり、具体的な組み方は環境によって異なるため、手元の環境で動作を確認してください。

Linux(systemd環境): org.freedesktop.ScreenSaverインターフェースを実装するデスクトップ環境(KDEなど)であれば、loginctl lock-session / unlock-sessionに連動するD-Busシグナルを監視するユーザーサービスを用意し、シグナル受信時にマーカーファイルの作成・削除を行う方法があります。GNOMEは別インターフェース(org.gnome.ScreenSaver)を使うため、環境によっては同じ方法が動作しない場合があります。

Windows: タスクスケジューラで「ワークステーションのロック解除時」「ロック時」のトリガーを持つ2つのタスクを登録し、それぞれNew-ItemとRemove-Itemを実行するPowerShellスクリプトを紐づけます。

外部ツールを作り込む前に、CLAUDE_CLIENT_PRESENCE_FILE自体が想定どおり効くかを手動で確認しておくと、後の切り分けが楽になります。マーカーファイルをtouchで作成した状態で長時間タスクを完了させてpushが来ないことを確認し、次にrmで削除した状態で同じ操作を行いpushが届くことを確認します。この2ステップが通れば、あとは画面ロックのイベントに合わせてファイルの作成・削除を自動化するだけで済みます。

以下はorg.freedesktop.ScreenSaverを実装する環境(KDEなど)でのミニマム構成の例です。

# ロック解除でファイル作成、ロックで削除するワンライナー(org.freedesktop.ScreenSaver対応環境向け)
dbus-monitor --session "type='signal',interface='org.freedesktop.ScreenSaver'" |
  while read -r line; do
    case "$line" in
      *"boolean true"*) rm -f "$HOME/.claude/presence.lock" ;;
      *"boolean false"*) touch "$HOME/.claude/presence.lock" ;;
    esac
  done

これをsystemdのユーザーサービスとして常駐させれば、ログインセッション中は自動的にマーカーファイルの作成・削除が続きます。

いずれの構成でも、Claude Code自体はファイルの生成ロジックに関与しません。既存の画面ロック監視ツールを持っていない場合は、上記のいずれかを参考に新規に組む前提になります。ファイルの作成・削除を担う側の実装ミスでファイルが残り続けると、ロック後もpushが止まったままになるため、削除処理が確実に動くかどうかは別途確認が必要です。

似た仕組みとの違い

Claude Codeにはpush抑制に関わる環境変数がもう1つあります。CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECKです。こちらは既定の挙動を無効にする側で、1に設定すると、キーボード操作中やターミナルにフォーカスしている最中でもPushNotificationツールのデスクトップ通知を送るようになります。ただしこの変数はローカルの判定だけを無効化するもので、サーバー側がユーザーの活動を検知してモバイルpushを抑制する処理には影響しません。

つまり前者は「机の前にいる間、範囲を広げて止める」ための変数で、後者は「操作中でも通知を止めない」ための変数です。抑制の方向が逆になっている点に注意します。両方を同時に設定した場合も、それぞれ別の通知経路に働くため動作は競合しません。CLAUDE_CLIENT_PRESENCE_FILEはモバイルpushの抑制範囲を広げ、CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECKはデスクトップ通知側のローカル判定を無効化します。

モバイルpushの前提設定

CLAUDE_CLIENT_PRESENCE_FILEはあくまで抑制条件を追加するものなので、そもそもモバイルpush自体が有効になっている必要があります。Claude公式アプリ(iOS / Android)をインストールし、Claude Codeと同じアカウント・組織でサインインしたうえで、ターミナルで/configを実行して「Push when Claude decides」または「Push when actions required」を有効にします。この設定が入っていない状態では、CLAUDE_CLIENT_PRESENCE_FILEを設定してもpush自体が届かないため、抑制の効果を確認できません。

そもそもRemote Controlに接続できない場合は、Remote Controlに接続できないときの見分け方を先に確認します。接続はできてもセッションが途中で切れる場合は、Remote Controlが20分放置で切断される原因が関係していることがあります。

push抑制の使い分け早見表

Remote Controlのpush抑制には複数の設定が絡みます。どれを使うべきかは状況によって変わります。

ただしCLAUDE_CLIENT_PRESENCE_FILEはpushを完全に無効化する設定ではありません。画面をロックすれば、通常どおりpushが届きます。

通知が届かないときの切り分け

CLAUDE_CLIENT_PRESENCE_FILEを設定した後にpushが来なくなった場合、原因が抑制設定によるものか、別の要因かを切り分けます。

まず/configを実行し、「No mobile registered」と表示されていないか確認します。表示されている場合はスマホ側のClaudeアプリを開いてpushトークンを再取得させると、次回のRemote Control接続時に解消します。iOSではフォーカスモードや通知の要約機能がpushを遅延・抑制することがあるため、設定アプリの通知設定でClaudeアプリを確認します。Androidではバッテリー最適化がpushの配信を遅らせることがあるため、Claudeアプリをバッテリー最適化の対象から外します。

これらのいずれにも該当せず、画面ロックを解除しているのにpushが止まっている場合は、マーカーファイルが意図せず残っていないか(ロック時の削除処理が動いているか)を確認します。念のためCLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECKを誤って設定していないかも見ておくとよいですが、この変数はデスクトップ通知専用でモバイルpushには影響しないため、原因の切り分けとしては別枠です。

よくある質問

Remote Controlが使えない環境では意味がありますか

CLAUDE_CLIENT_PRESENCE_FILEはRemote Controlのモバイルpushに対する設定なので、Remote Control自体がAPIエンドポイントの制約や組織のポリシーで使えない環境では効果がありません。たとえばAmazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundryを利用している場合や、ANTHROPIC_BASE_URLをapi.anthropic.com以外に向けている場合はRemote Control自体が利用できません。まずRemote Controlが使える状態になっているかを確認してから、この環境変数を設定します。