agent viewのpossibly low memoryとは — 起動前の失敗と対処

agent viewの行にpossibly low memory — free some up and retryと出たら、バックグラウンドセッションのプロセスが、起動を終える前に、エラーを出さずに終了しています。ホストのメモリも、その瞬間に不足を報告していました。ただしこの表示は仮説で、原因の確定ではありません。メモリを空けてからその行にattachするか返信すれば、supervisorが新しいプロセスを立ち上げ直します。

「possibly low memory」の表示が意味すること

agent viewは、バックグラウンドで動く複数のセッションを1画面に並べる画面です。各セッションは、supervisor(常駐のバックグラウンドサービス)の配下で、それぞれ独立したClaude Codeプロセスとして動きます。

そのプロセスが起動を終える前に終了し、しかもホストのメモリが少ないときに、行のステータスへ終了の理由と次の一文が付きます。

possibly low memory — free some up and retry

この一文は、v2.1.199で入りました。それ以前は、メモリ不足のマシンでバックグラウンドセッションが失敗しても、出るのは終了理由だけでした。今は「メモリを疑ってよい失敗」だと行を見ただけで分かります。

「possibly」という語が要です。この注記は仮説であって、確定した原因ではありません。メモリが本当の原因かもしれないし、たまたま同時にメモリが少なかっただけかもしれません。断定しない表示だと覚えておくと、対処の順序も決まります。

注記が付く3つの条件

注記は、次の3条件がすべて揃ったときだけ付きます。

条件2が外れる場合は、別の表示になります。プロセスが終了前にエラーを書き出していたときは、注記ではなくそのエラー自体が行に出ます。

「シグナルで止められていない」という条件は見落としやすい点です。シグナルで終了したプロセスは、エラーを出さずに終わっていても注記の対象になりません。低メモリの疑いが濃くても、注記が付かないケースがあるということです。

注記が出たときの再開手順

メモリを空けてから、失敗した行を開き直します。

シェルから操作するなら、次のコマンドが使えます。

# 状態を確認する(完了済みも含める)
claude agents --json --all
 
# IDを指定してattachする(メモリを空けたあと)
claude attach <id>
 
# 直近の出力を確認する
claude logs <id>

<id>はclaude agents --jsonのid欄で分かる短いIDです。JSONの読み方はclaude agents --jsonの解説にまとめています。

stateの値はworking、blocked、done、failed、stoppedの5つです。再開の候補はfailedかstoppedの行です。--allを付けないと、完了済みのセッションは一覧に出ません。

attachで直らないときの手段

attachや返信を試しても同じ失敗になるなら、claude respawn <id>でセッションを作り直す手があります。v2.1.289で各コマンドの--helpを見ると、説明は次のとおりです。

# claude attach --help
Usage: claude attach <id>
 
  Open the background session in this terminal. ← returns to agent view,
  Ctrl+Z drops back to your shell. The session keeps running either way.
 
# claude logs --help
Usage: claude logs <id>
 
  Print the background session's recent terminal output.
 
# claude stop --help
Usage: claude stop <id>
 
  Stop a background session. Its conversation is kept; resume it later
  with `claude attach <id>`.
 
# claude respawn --help
Usage: claude respawn <id>|--all
 
  Restart a background session (or all of them) so it picks up the
  current Claude binary.

respawnは、保存済みの会話があればそこから再開します。会話がディスクに無いときは、最初のプロンプトを新しい会話として実行し直します。メモリを空ける手順の代わりにはならないので、先に空き容量を確保してください。

メモリが足りないままだと何が起きるか

メモリ不足が続くとき、supervisor側にも自動の逃げ道があります。supervisorは、空き資源を確保するために、待機中のセッションのプロセスを自分で停止します。

その基準は、セッションの状態ごとに決まっています。

メモリが低いままのときは、この自動停止が働きます。他のアイドルセッションを止めても資源が空かなかった場合は、Ctrl+Tでピン留めしたアイドルセッションのプロセスまで止めます。

ピン留めは「プロセスを動かし続ける」ための印ですが、絶対の保証ではありません。ホストのメモリがよほど逼迫しているときは、ピン留めしたセッションも停止の対象になります。

行の見た目から失敗の種類を読む

再開する行を選ぶときは、行頭のアイコンを見ます。色とアニメーションがセッションの状態を、形がプロセスの生死を表します。

失敗系の色は2つです。Failedは赤で、エラーで終わった行です。Stoppedはグレーで、Ctrl+Xかclaude stopで止めた場合、プロセスがClaude Codeの外から終了された場合、バックグラウンドサービスが止まっている間に終了した場合の3通りがあります。メモリを空けてから再開する候補は、この2色の行です。

形は別の軸です。✻か動く✽ならプロセスが生きていて即座に応答します。∙はプロセスが終了した印で、覗き見もattachも返信もできます。/loopのセッションが反復の合間に待っているときは✢です。∙の行に返信すると、Claude Codeが前回の続きから再開します。

覗き見は、行を選んでSpaceを押します。行が端末の端で切っている文を、状態に応じて全部見せてくれます。

• 利用者を待っているセッション: 訊いている質問そのもの(返信欄の上)
• 終わったセッション: その結果
• 作業中のセッション: ステータス文の全体

待機中の行にはwaiting 3mのような経過時間も出ます。失敗した行の原因を、attachせずに先に確かめたいときに向いています。

一覧上の操作にも触れておきます。Ctrl+Tは選んだ行のピン留めと解除で、ピン留めした行は先頭に固定され、アイドル中もプロセスが維持されます。Ctrl+Xは停止で、2秒以内にもう一度押すとセッションを削除します。削除すると、agent viewの行からは再開できなくなります(会話の記録はclaude --resumeで残り、agent viewのdispatch入力で/resume(v2.1.212以降)を打てば、削除した行も戻せます)。失敗した行を再開したいうちは押さないでください。

マシンの再起動後にfailedやstoppedが並ぶとき

メモリ不足とは別に、マシンの停止や再起動でも行は赤やグレーになります。再起動すると、動いていたバックグラウンドセッションは止まります。行の見え方は、最後に進捗があってからの時間で変わります。

入力待ちだったセッションは、再起動後もNeeds inputの下に残ります。スリープでは止まりません。スリープ中もセッションは保たれ、復帰時にsupervisorが再接続します。

possibly low memoryは、起動を終える前に落ちたプロセスだけに付く注記です。再起動後に並ぶ赤やグレーの行は、別の経路で止まったものとして扱います。

稼働中に止まる「low memory」との違い

「low memory」の語は、Claude Codeの別の場面にも出てきます。区別しておくと、原因の切り分けが速くなります。

後者は、WSL2で空きメモリが十分にあっても誤検知として出ることがあり、WSL2のlow memory誤検知の解説に原因と回避策があります。そちらは環境変数で止める性質のもので、ここで紹介した再開手順は当てはまりません。

起動失敗の原因を追うときに見る場所

注記の「possibly」に引きずられず、原因を確かめたいときは、ログと状態を見ます。

# supervisorの稼働状況とセッション数を見る
claude daemon status
 
# supervisorのログを追う(Ctrl+Cで止める)
claude daemon logs

v2.1.289でclaude daemon statusを実行すると、次のように出ました。

pid:     52482
version: 2.1.289
uptime:  49488s
origin:  transient — started on-demand by `claude` (pid 95070) in ~/project
config:  ~/.claude/daemon.json
log:     ~/.claude/daemon.log
 
bg sessions:

originがtransientなのは、supervisorをOSのサービスとして入れず、claudeの起動に合わせて立ち上げているためです。claude daemon --helpにはService install is disabled in this version — the daemon runs on demand and exits when the last client disconnects.とあります。これは--helpの説明です。agent viewを閉じても、dispatchしたセッションは動き続けます。

ログは~/.claude/daemon.logにあり、セッションごとの状態は~/.claude/jobs/<id>/state.jsonに保存されます。ただしstate.jsonは安定したインターフェースではないので、スクリプトから読むならclaude agents --jsonを使います。

低メモリが疑われるのに注記が無いときは、前述の3条件のどれかが外れています。OS側のログも合わせて見ると手がかりが増えます。

起動失敗の理由そのものを機械的に取りたい場合は、CLAUDE_CODE_STARTUP_FAILURE_RESULTSの解説が、別の面(非対話実行の結果ストリーム)の手段を扱っています。

同時に動かす数を絞る

メモリ不足の背景に「同時に動かしすぎ」があるなら、根本の対処は並列数を減らすことです。バックグラウンドセッションは、1本ごとに独立したClaude Codeプロセスです。何本もdispatchすると、そのぶんホストのメモリを消費します。

ワークフローの並列数を抑える手段はMAX_CONCURRENT_AGENTSの解説にあります。今すぐできる手当ては、不要になったセッションを減らすことです。

ピン留めしたセッションを増やしすぎると、その分は動かし続けるプロセスになります。ピンは必要な行だけに絞ると、メモリの余裕を保ちやすくなります。

似た失敗との見分け方

agent viewの失敗行には、possibly low memory以外の表示もあります。行に出た文言で、原因の系統が分かります。

ホストプロセスの死亡や応答なしは、セッションの端末を担うプロセス側の問題で、メモリの注記とは別に表示されます。supervisorが止まっているときは、行の注記ではなく「background serviceが応答しない」という報告になります。

四つとも、会話は保存されており、再開で続きから動く点は共通です。違うのは、再開の前に手を入れる場所です。メモリなのか、端末ホストなのか、supervisorなのかを、表示文言から先に決めてください。

注記が外れていたときの動き方

メモリを空けて再開しても同じ失敗が繰り返されるなら、注記は外れていたと考えて、claude logs <id>やclaude daemon logsで別の原因を探します。