Claude Codeでfseventsdが暴走するとき — macOSの症状と確認手順

Macでclaudeを起動した直後、数秒から十数秒キーを受け付けない。そのときmacOSのシステムデーモンfseventsdが1コアを使い切っているなら、原因はClaude Code本体ではなく、ファイル変更を知らせる側にあるかもしれません。

この症状はGitHubのanthropics/claude-codeのissue #98769で報告されています。2026年10月13日の取得時点でissueはopenで、修正は入っていません。この記事では、報告された症状、自分のMacで確かめるコマンド、再起動の手順、報告者のデータから言える範囲と言えない範囲をまとめます。

fseventsdとClaude Codeの関係

fseventsdは、ファイルの作成・変更・削除をアプリへ通知するmacOSのデーモンです。アプリはFSEventsという仕組みでここに監視を登録します。

Claude Codeもその利用者です。公式ドキュメントは、~/.claude/agents/ と .claude/agents/ を監視し、サブエージェントの定義ファイルが変わると数秒以内に検知すると説明しています。issueの報告者は、スキル、コマンド、設定ファイルにも監視が張られていると述べています。

つまり、Claude Codeを起動するたびにfseventsdへの登録が走ります。fseventsdが詰まっていれば、その登録が待たされます。

報告されている症状

issue #98769の報告者は、MacBook Pro 14インチ(M3 Pro、メモリ18GB、macOS 27.0)で、数日にわたり複数のClaude Codeセッションとサブエージェントを動かしていました。見えた状態は次のとおりです。

ファイルイベントの量が減っても、デーモンのCPU使用率は下がりませんでした。報告者のsampleでは、ディスクログを扱うスレッドが約93%のサンプルを_platform_strncmpに費やしていました。イベントの流入ではなく、デーモン内部に溜まった状態が重いという読みです。

Claude Code側で起きること

別の利用者(コメント投稿者)は、macOS 26.7、Claude Code 2.1.295で次の症状を報告しています。

• claudeの起動後、数秒間タイプできない
• そのときfseventsdは稼働11日、CPU 98.4%、RSS 8.2GB
• デバッグログに[event-loop-stall]が3回、累積17.3秒
• [settings] native file watching is not delivering events on this hostと出て、設定ファイルを2秒ごとのポーリングへ切り替えた

sampleでは、監視を始めるFSEventStreamStartがfseventsdの応答を待ち、JavaScriptのメインスレッドがその裏のロックで待たされていました。sudo killall fseventsdで、固まりはすぐ消えたそうです。

なお、ログの最初の2回の停止には[likely sleep/wake](スリープ復帰の可能性)というラベルが付いていましたが、コメント投稿者はマシンがスリープしていないと書いています。このラベルを鵜呑みにしないほうがよさそうです。

自分のMacで確認する

症状が当てはまるかは、メモリとCPUを予算と並べれば分かります。次のコマンドは、いずれも報告者が使ったものです。

# fseventsdのCPUとメモリ(RSSはKB単位)
ps -axo pid,etime,%cpu,rss,command | grep '[f]seventsd'
 
# launchdが決めているメモリ上限(正常時は30MB)
launchctl print system/com.apple.fseventsd \
  | grep 'jetsam memory limit (active'
 
# 詳細なフットプリント(root権限が必要)
sudo footprint $(pgrep -x fseventsd)

目安は上限との差です。報告者の正常時は5〜13MB程度で、問題の状態は数GBから24GBでした。数十MBを少し超える程度なら、この記事の症状とは別物の可能性が高いでしょう。

Claude Code側の証拠を取るなら、デバッグログをファイルに出してevent-loop-stallを探します。

claude --debug-file /tmp/claude-debug.log
# 起動後に別のターミナルで
grep -E 'event-loop-stall|fs_watch_silent' /tmp/claude-debug.log

起動直後に数秒単位の停止が並び、fs_watch_silentが出ていれば、報告と同じ型です。

暴走したfseventsdを再起動する

報告者が効果を確認した手順は、SIGTERMを送ってlaunchdに再起動させる方法です。

# 1. 再起動するとイベント履歴が消えるので、先に控える
sudo ls -laT /System/Volumes/Data/.fseventsd
 
# 2. 終了させる(launchdが自動で再起動する)
sudo kill -TERM $(pgrep -x fseventsd)

sudo launchctl kickstart -k system/com.apple.fseventsdは使えません。SIP(システム整合性保護)が有効だと、Operation not permitted(エラー150)で拒否されます。

報告者は、再起動でイベント履歴が消えると明記しています。後で原因を調べたいときだけ、控える手順が意味を持ちます。

何が分かっていて、何が分かっていないか

ここは読み違えやすい箇所です。報告者自身が、次のように線を引いています。

• 分かっていること: 暴走したfseventsdは、Claude Codeの起動時に監視の登録で入力を固まらせる(コメント投稿者のスタックで確認)
• 分かっていないこと: 暴走を引き起こしたのがClaude Codeかどうか。報告者は「Claude Codeが原因とは主張しない。リーク自体はOS側に見える」とし、Appleにも報告するとしています

報告者の環境では、暴走の前に1日あたり8,900〜19,500回のツール呼び出しに加え、mutation testingとColima経由のDockerが動いていました。ただし、日々のツール呼び出し数とログファイル数の相関はr = 0.71にとどまります。

追加の観測も2つあります。

1. 別の利用者の2台のMacでは、3.6GBを使う31個の待機プロセスが溜まっていても、fseventsdは約6MBで正常でした。プロセス数だけでは説明できない、という材料です
2. 報告者の再計測では、1時間単位で毎秒9,426件(暴走日の平均5,715件を超える)の時間帯があっても、fseventsdは5〜13MBに収まりました。数日間続くイベントの嵐が必要なのか、まだ分かっていません

要するに、「エージェントを多用すると必ず起きる」という報告ではありません。再現手順は決まっておらず、数日かけて育つ状態として観察されています。

issueが求めているClaude Code側の修正

報告者は、原因がOS側にあるとしつつ、Claude Codeにできることを3つ挙げています。どれも2026年10月13日の取得時点で未着手です。

1. 検知: macOSで/doctorとセッション開始時に、fseventsdの使用量をlaunchdの上限と比べ、大きく超えていれば修正コマンド付きで警告する。報告者は約0.3秒のSessionStartプラグイン(8項目のセルフテスト付き)を自作し、fork上のブランチで提示しています。リポジトリへのPR作成は外部アカウントに許可されておらず、PRにはなっていません
2. メインスレッドを塞がない: FSEventStreamStartをタイムアウト付きで非同期に始め、fseventsdが遅くても入力を止めない。この点は、先に閉じられたissue #96008の残り課題だとされています
3. 登録の頻度を下げる: 1プロセスにつき長寿命のストリームを1本に保つ、頻繁に変わるディレクトリを除外パスに指定する(上限8件)、claude -pやサブエージェントのようにライブリロードが要らないプロセスでは監視を張らない

3つ目の根拠として、報告者は2.1.286のバイナリを調べています。FSEventStreamCreateなどは参照されている一方、除外パスの設定関数FSEventStreamSetExclusionPathsの文字列は見つからなかった、という内容です。

別の利用者は、ヘッドレス実行の--output-format stream-jsonやSDKのプロセスには、設定・スキル・エージェントのライブリロード用の監視が要らないはずだと指摘しています。これが実現すれば、プラグインやオーケストレーターがプロセスを溜め込んでも、fseventsdへの登録者は増えません。

これまでの対応として確認できるもの

changelogの2.1.271(2026年9月14日)には、システムのファイルイベント機構が飽和したmacOSで、設定ファイルの変更が検知されない問題の修正が載っています。監視がポーリングにフォールバックする、という内容です。報告者はこれを、チーム側が飽和状態の存在を把握している証拠として挙げています。ただし利用者への通知はなく、起動時にメインスレッドが待たされる点も、2.1.295で再現したと報告されています。

症状を軽くするために今できること

issueの提案は、Claude Code側の修正(登録を非同期にする、ヘッドレス実行では監視を張らない、除外パスを使う)が中心で、利用者が切れる設定は挙がっていません。以下は報告から読み取れる運用上の手がかりです。効果を保証するものではありません。

• 固まったらfseventsdを上の手順で再起動する。最も確実だったのはこれです
• 使っていないclaudeプロセスを溜めない。別の利用者のケースでは、更新されないままのサードパーティ製プラグインがセッションごとにヘッドレスのclaude --output-format stream-jsonを起動し、終了させずに31個を溜めていました。更新後に解消しています
• 大量にファイルを触る処理(テストランナー、mutation testing、ホームを丸ごとマウントしたコンテナ)の同時実行を絞る。報告者の環境にあった要素ですが、因果は未確認です
• 設定ファイルの変更が反映されないときは、ポーリングへ切り替わっている可能性を疑う。2.1.271のchangelogに、システムのファイルイベント機構が飽和したmacOSでは設定の変更検知をポーリングへ切り替える、という修正が載っています

ヘッドレスのプロセスが溜まっていないかは、次で数えられます。

pgrep -fl 'claude.*stream-json' | wc -l

Claude Code自体のCPU・メモリが高いときの切り分け

fseventsdが正常なのにClaude Codeが重いなら、別の原因です。公式のトラブルシューティングは、/compact、再起動、claude --safe-modeによるプラグイン・MCP・フックの切り分け、/heapdumpでの診断を勧めています。詳しくはClaude Codeの/heapdumpとメモリリークでOOM Killになる原因にあります。環境全体の点検は/doctorのチェックアップから始められます。

判断の早見表

起動時の固まりは、見た目が似ていても原因が複数あります。fseventsdの数字を先に見ておけば、この記事の型かどうかをすぐ切り分けられます。