Claude Codeの--session-idと--no-session-persistenceの使い方

--session-idは起動する会話にUUID形式のセッションIDを自分で割り当てるフラグです。--no-session-persistenceは会話をディスクに保存せず、あとから--resumeや--continueで呼び出せない状態で実行するフラグです。どちらもインタラクティブな日常利用ではまず触りませんが、CIやスクリプトからclaudeを呼び出す場面では挙動を左右します。

このTipsでできること

このTipsでは、--session-idでセッションIDを外部から固定する方法と、--no-session-persistenceで永続化を止める方法を扱います。CLAUDE_CODE_SESSION_IDのような関連する環境変数と組み合わせるときの制約もあわせて見ます。

--session-idと--no-session-persistenceの使い方

2つのフラグは役割がはっきり分かれています。--session-idはセッションを識別する値を決める側、--no-session-persistenceはセッションを記録するかどうかを決める側です。単体の挙動から順に押さえます。

--session-id: セッションIDをUUIDで固定する

--session-idは会話に使うセッションIDを指定するフラグです。値は有効なUUID形式でなければなりません。指定しなければ、Claude Codeが起動のたびに自動でIDを発行します。--session-idはこの既定のIDを、あらかじめ決めた値に置き換えるためのフラグです。

claude --session-id "550e8400-e29b-41d4-a716-446655440000"

ランダムなUUIDを都度発行するより、uuidgenなどで生成した値を渡すほうが、後段の処理と対応付けやすくなります。デプロイスクリプトからClaude Codeを呼ぶ場合、発行したIDをジョブのログにも書き出しておけば、実行結果とセッションIDをあとから突き合わせられます。

claude -p --session-id "$(uuidgen)" "デプロイログを要約して"

テスト自動化でも同じ発想が使えます。E2Eテストのシナリオごとに固定のUUIDを渡しておけば、失敗時にclaude --resume <同じUUID>でそのときの会話をそのまま開けます。

IDで呼び出すときの検索範囲も押さえておくと安心です。Claude Codeは、まず今のプロジェクトディレクトリとそのgit worktreeの中を探し、見つからなければマシン上の他の全プロジェクトへ探索を広げます。バージョン2.1.223より前は、検索範囲が今のプロジェクトディレクトリとworktreeに限られていました。複数のリポジトリをまたいで同じUUIDを使い回しても、今のバージョンなら取りこぼさず見つけ出せます。

--no-session-persistence: 履歴を残さず実行する

--no-session-persistenceを付けると、セッションの会話内容がディスクに保存されなくなります。保存されないので、--resumeや--continue、上矢印キーの入力履歴からも呼び出せません。

公式ドキュメントではprint modeのみ対応と明記されています。インタラクティブセッションでの効果は保証されないため、-p(--print)と組み合わせて使います。

claude -p --no-session-persistence "一時的な質問"

print modeのセッションは、このフラグを付けなくても既定では--continueの対象から外れます。呼び出すにはclaude -p --continueのように明示が必要です。--no-session-persistenceはここからさらに踏み込み、ディスクへの保存そのものを止めます。そのため、明示的な-p --continueはもちろん、IDを直接指定する--resumeでも見つからなくなります。「一覧に出ないだけ」と「そもそも残らない」は別の状態です。

関連する環境変数とセッションIDの流れ

--session-idと--no-session-persistenceは、Claude Codeが内部で使っている複数の環境変数とつながっています。フラグだけを覚えるより、周辺の変数まで押さえておくと応用が利きます。

CLAUDE_CODE_SKIP_PROMPT_HISTORYは全モードで効く

CLAUDE_CODE_SKIP_PROMPT_HISTORYを1に設定すると、プロンプト履歴とセッションのトランスクリプトをディスクに書き込まなくなります。効果は--no-session-persistenceとほぼ同じですが、適用範囲が違います。フラグはprint modeに限られますが、この環境変数はどのモードでも効きます。

使い捨てのスクリプトセッションで履歴を残したくないならCLAUDE_CODE_SKIP_PROMPT_HISTORY=1。print modeの1回きりの呼び出しだけを対象にするなら--no-session-persistence。用途で選び分けます。

CLAUDE_CODE_SESSION_IDでサブプロセス側からIDを参照する

CLAUDE_CODE_SESSION_IDは、BashやPowerShellツール、hookコマンド、stdio接続のMCPサーバーの各サブプロセスに自動でセットされる環境変数です。Bash・PowerShell・hookでは、hookのJSON入力に含まれるsession_idフィールドと一致し、/clearのたびに更新されます。

MCPサーバーのサブプロセスだけは起動時に渡されたIDを保持し続けます。--resume <session-id>で再開した場合はそのIDを受け取りますが、IDを指定しない--continueや--resumeでは起動時点のIDのままになることがあります。スクリプトや外部ツール側からセッションを追跡したいときに使う変数です。

セッションIDが表に出てくるのはこの変数だけではありません。デバッグログの既定の出力先も~/.claude/debug/<session-id>.txtという形式で、--debug-fileを指定しない限りセッションIDがファイル名に使われます。

--fork-sessionは再開時に新しいIDを作る

--session-idと混同しやすいのが--fork-sessionです。--session-idは新しい会話にIDを割り当てるフラグです。一方--fork-sessionは、--resumeや--continueで既存の会話を再開するときに、元のセッションIDを使わず新しいIDを発行します。両者は逆方向の操作です。元の会話はそのまま残し、そこから分岐した会話を新しいIDで管理したいときに使います。

公式ドキュメントは--session-idと--resumeを同時に指定する組み合わせを説明していません。--session-idは新規セッションへのID割り当て、--resumeは既存セッションの呼び出しなので、目的自体が重なりません。既存セッションのIDだけを変えたい場合は--fork-sessionを使います。

--name/-nは人が読める名前、--session-idは機械向けのID

--session-idが指定するのは処理向けのUUIDです。人が--resumeで選びやすい名前を付けたい場合は--name(-n)を使います。

--nameはセッションの表示名で、/resumeの一覧やターミナルのタイトルに表示されます。同じマシンで同名のセッションがすでに動いていると、Claude Codeは自動で名前の別バリエーションを割り当てます。名前を付けたセッションはclaude --resume <name>でそのまま呼び出せます。

claude -n "auth-refactor"

--session-idと--nameは同時に指定できます。CI側の突き合わせにはUUIDを使い、手元で会話を探すときは名前で探す、という役割分担が現実的です。

既定では--nameを付けるとターミナルのタブタイトルも書き換わります。タブタイトルの変化だけを止めたい場合は、設定ファイルでterminalTitleFromRenameを無効にします。

--session-idと関連フラグ・環境変数の使い分け早見表

CI/CDやスクリプトでこの2つのフラグをどう組み合わせるか

--session-idと--no-session-persistenceは単体でも使えますが、CIパイプラインやバッチスクリプトでは組み合わせて使う場面のほうが多くなります。実行のたびにログへ紐づくIDを発行しつつ、ディスクには会話を残さない構成です。

claude -p --session-id "$(uuidgen)" --no-session-persistence \
  --output-format json "CIログのエラー原因を要約して"

このコマンドは、uuidgenで生成したIDをそのままCIのジョブログへ書き出しつつ、Claude Code側には会話を残しません。障害調査のときは、CI側のログに残るIDと、CLAUDE_CODE_SESSION_ID経由でBashツールやhookに渡るIDを突き合わせれば、どのステップがどのセッションで実行されたかを追えます。

hookを併用すると、さらに細かい単位で追跡できます。PreToolUseやPostToolUseなどのhookには、JSON形式の入力にsession_idフィールドとして今のセッションIDが渡されます。--session-idで固定した値をhook側のログにも書き出しておけば、ツール呼び出し1件ごとの記録とCIのジョブログを同じIDで結び付けられます。

組み合わせるときに見落としやすいのが、--no-session-persistenceがprint mode限定という制約です。インタラクティブセッションに--session-idだけを付けて長時間の作業をIDで追跡したい場合、--no-session-persistenceは効果を持ちません。履歴を残したくない用途にはCLAUDE_CODE_SKIP_PROMPT_HISTORYを使うのが正しい組み合わせです。

もう一つの注意点は、--session-idが受け取るのは有効なUUIDだけだという制約です。ジョブIDやコミットハッシュのような独自の識別子を、そのままこのフラグに渡すことはできません。UUIDとジョブIDの両方をログに残し、あとから紐づける運用が現実的です。uuidgenはmacOSとLinuxの標準コマンドで、Windowsでは代わりにPowerShellの[guid]::NewGuid()でUUIDを生成できます。

どちらのフラグも、モデルの応答内容や利用料金には影響しません。変わるのはセッションの識別方法と、会話をディスクに保存するかどうかだけです。

--session-idはIDを決める側、--no-session-persistenceは保存を止める側です。役割が違う2つのフラグなので、必要なほうだけを単独で使ってもかまいません。この役割分担さえ押さえておけば、CLAUDE_CODE_SESSION_IDやCLAUDE_CODE_SKIP_PROMPT_HISTORYとの組み合わせも迷わず選べます。

起動時オプションの読み方をさらに知りたい場合は、append-system-promptとsystem-promptの違いや、--mcp-configと--strict-mcp-configの使い分けも参考になります。--resumeでセッションが見つからないときの原因は、「No conversation found with session ID」の対処法にまとめました。