Manage sessions

原典: Manage sessions ／ 日本語版

一行要約

会話をプロジェクトディレクトリに紐づけて保存し、再開・分岐・切り替えを可能にする仕組みで、実務で効くのは「再開で何が戻り、何が戻らないか」の境目（起動フラグと permission mode は戻らないものが多い）。

要点

何が保存されているか

A session is a saved conversation tied to a project directory. Claude Code stores it locally as you work, so you can resume where you left off, branch to try a different approach, or switch between tasks.

セッションとは、プロジェクトディレクトリに紐づけて保存された会話である。作業しながらローカルに保存されるので、中断したところから再開したり、別のやり方を試すために分岐したり、タスクを切り替えたりできる。

入口	何をするか
claude --continue	そのディレクトリの直近の対話セッションを再開
claude --resume	セッションピッカーを開く
claude --resume <name> / <session-id>	名前または ID で直接再開
claude --resume <transcript-path>	.jsonl の transcript ファイルを絶対パスで指定して再開
claude --from-pr <number>	その PR に紐づくセッションに絞ってピッカーを開く
/resume	セッション中に別の会話へ切り替える

claude -p と Agent SDK のセッションはピッカーにも --continue にも出てこない。 ID を渡せば再開できる。--continue は最初のプロンプトが /loop だったセッションも飛ばす（途中で /loop を走らせたセッションは隠れない）。claude -p --continue の場合だけは、-p・SDK・/loop のセッションも対象に入る。

background セッションは、終わったものなら --continue で開く（v2.1.257 以降）。直近の会話が background でまだ走っている場合は開かず、Your most recent conversation is running in the background とその ID を出して終了する。claude agents から attach するか、claude --resume で別のものを選ぶ。

claude --resume <session-id> はどのディレクトリからでも動く。現在のプロジェクトとその worktree を先に探し、次にマシン上の他の全プロジェクトを探す。ただし他プロジェクトでの解決は、該当する transcript がちょうど1つのときだけ —— 手でコピーした複製があると、任意のコピーを再開せずに not-found と報告する。

まだ走っている background セッションを --resume / /resume で選ぶと、transcript を読み込まずにそのセッション自体を開く（v2.1.285 以降。それより前は拒否して claude attach <id> か claude stop <id> を促した）:

• シェルから: claude --resume <session> は同じ端末で claude attach を走らせる。コマンドラインのプロンプトは次のターンとしてそのセッションに送ってから開く（claude -p --resume <session> "prompt" を端末で打っても同じで、-p でも非対話のままにはならない）。パイプやリダイレクト、--permission-mode / --model / --settings のようにセッションを設定するフラグ、--output-format json のように出力を読むフラグ、--max-turns のように実行を縛るフラグがあると、何も送らず終了コード1で終わる（agent view を切っている場合も）。会話のコピーを再開するなら --fork-session、自分のフラグで会話そのものを続けるなら claude stop <id> してからやり直す。/ や ! で始まるプロンプトと、セッションが質問への答えを待っている間のプロンプトは送られない
• セッションの中から: /resume はいまの会話を background に回し、この端末を走っているセッションにつなぐ（空のプロンプトで ← を押すと agent view に戻る）

再開で戻るもの / 戻らないもの

戻るもの:

• 会話履歴（ツール呼び出しと結果を含む）。ただし前のプロセスが落ちた時点で実行中だったツールは、再開しても完了も再実行もしない —— Claude にはその呼び出しが「結果が記録される前に切れた」ものとして見え、もう一度走らせる前に効いたかどうかを確かめるよう指示される（CLAUDE_CODE_RESUME_INTERRUPTED_TURN を設定していない場合。v2.1.281 より前は、会話から落とすか、あなたが中断したものとして見せていた）。前のプロセスと一緒に終わったバックグラウンドの作業（background subagent・background Bash・workflow）は、再開した transcript に「終わらなかった」という注記として出る。Claude Code はその注記からターンを始めず、Claude は次のプロンプトと一緒に読む
• モデル。ただし次のときは戻らない: 退役した／availableModels で許されていない／起動時に --model や ANTHROPIC_MODEL 系の環境変数でモデルを指定した／Bedrock・Agent Platform・Foundry のようにプロバイダ固有のデプロイ ID を使う
• --agent（または agent 設定）で始めたならその agent（ツール制限とモデルごと）。再開時に --agent を渡せば別の agent にできる。agent は元のディレクトリ（信頼済みのワークスペースなら）→ 再開したディレクトリの順に探し、どちらにも無ければ既定のツールで再開して警告を出す
• permission mode（ターミナルから ID か一意の名前で再開した場合。例外は下の表）
• 有効だった goal（ターン数・タイマー・トークン基準はリセット）
• 期限切れでない scheduled task。background の Bash と monitor task は戻らない

Not every configuration flag from the original launch is restored.

起動時の設定フラグが全部復元されるわけではない。

渡し直しが要るもの: --mcp-config / --settings / --plugin-dir / --fallback-model / --add-dir。セッション中に /add-dir で足したディレクトリも戻らない（ただしピッカーがセッションを探す手がかりには使われる）。settings.json などの設定ファイルは起動時に読み直されるので、そこに書いてあるものは渡し直さなくてよい。

permission mode は「戻ることを期待してはいけない」

再開の仕方によって開始モードが変わる。危険な側に倒れないよう設計されている。下の表は transcript から読み込む場合の話で、走っている background セッションを開いたときは、そのセッションのいまのモードのまま。

終了時のモード	再開の仕方	再開後
bypassPermissions	ターミナル	新規セッションと同じモード（復元されない。使うなら起動フラグか defaultMode で明示する）
plan	ターミナル	新規セッションと同じモード
auto	ターミナル	auto。ただしアカウントが auto mode の要件を満たしている場合のみ
Manual	ターミナル	既定が auto のときは Manual。設定ファイルの defaultMode が効くならそちら
plan	非対話（条件つき）	plan mode
どれでも	非対話（その他）	新規の claude -p と同じモード

セッションピッカーから選んだ場合と /resume で切り替えた場合は、保存されたモードを復元しない。前者は新規と同じモード、後者は今のセッションのモードを引き継ぐ。claude --resume <name> でも、名前が複数に当たってピッカーが開いたら前者の扱いになる。 ターミナルから再開するときは --permission-mode / --dangerously-skip-permissions を渡せば復元されたモードより優先する（/resume はセッション内の切り替えなので、起動フラグを渡す口が無い）。

VS Code 拡張から plan mode で終わった会話を再開すると plan mode に戻る（非対話と VS Code で plan を戻すのは v2.1.246 以降）。

非対話で plan mode を再開するには次の条件すべてが要る（--permission-prompt-tool を渡し、--permission-prompts none は渡さない／--permission-mode と --dangerously-skip-permissions を渡さない／--fork-session を渡さない／channels 経由でない）。

要約から再開するダイアログ（費用の分岐点）

Pro / Max で、1時間以上放置され 100,000 トークンを超えたセッションを再開すると、最初のメッセージを送る前にダイアログが出る。この時点で prompt cache は失効しているので、どれを選んでも次のリクエストは全履歴を一度処理する。

Resuming as-is keeps every detail of the conversation available, at a per-request cost that scales with the conversation’s size. Resuming from the summary costs less on each later request because it carries the summary instead of the full history, but whatever the summary leaves out is no longer in Claude’s context.

そのまま再開すれば会話の細部がすべて残るが、1リクエストあたりの費用は会話の大きさに比例する。要約から再開すれば以降のリクエストは安くなる（全履歴ではなく要約を運ぶため）が、要約が落としたものは Claude の context にもう無い。

選択肢は3つ。Resume from summary（即座に /compact を走らせ、履歴を「要約＋直近のやりとり＋最近読んだファイル最大5つ」に置き換える）／Resume full session as-is（そのまま読み込み、再キャッシュする）／Don’t ask me again。

分岐は「プロセスを乗り換えない」

/branch は会話の複製を作ってそちらへ切り替える。元のセッションはディスク上でそのまま残り、ピッカーにも出る。

状態	/branch の後
会話履歴	/branch を実行した時点までコピーされる
「このセッションでは許可」の承認	引き継がれる（同じプロセスで走るため）。--fork-session で別プロセスに分ければ承認は消え、取り直しになる
実行中の background subagent / Bash	走り続け、出力は切り替えた先の分岐に出る（元のセッションではない）
Remote Control の接続	繋がったまま分岐に付いてくる

⚠️ フォークせずに同じセッションを2つのターミナルで再開すると、両方のメッセージが1つの transcript に混ざる。

書き出しと、スクリプトからの参照

/export は人が読むための整形済み transcript。スクリプトが解析するなら別の口を使う。

• 1回走らせて結果を取る → claude -p --output-format json / stream-json
• 既存セッションに質問する → claude -p --resume <id>
• セッションのイベントに反応する → hook や statusline が受け取る transcript_path（SessionEnd hook で保管できる）
• アプリに組み込む → Agent SDK

名前: 「表示名」では再開できない

名前を付けなかったセッションにも2種類のラベルが付くが、再開の鍵になるのは生成タイトルだけ。

ラベル	何か	--resume / /resume に渡せるか
自分で付けた名前	-n / /rename / ピッカーで Ctrl+R / claude.ai 側での改名	渡せる
生成タイトル	最初のプロンプトの短い要約（小さく速いモデルが書く）。plan を承認すると plan に基づくタイトルに置き換わる	渡せる
既定の表示名	my-app-3f のような「ディレクトリ名＋2文字」。agent view や claude agents --json の一覧に出る	渡せない（見つからない）

同じマシンで生きている別セッションと同じ名前を付けると、後から来た側が auth-refactor-graceful-unicorn のような別名に変えられる（v2.1.232 以降）。生成タイトル・既定の表示名、起動時の background / -p セッションの --name は検査されないので、一覧に同名が並ぶことはある。

transcript の置き場所と、直接読まない理由

既定では ~/.claude/projects/<project>/<session-id>.jsonl。<project> は作業ディレクトリのパスの英数字以外を - に置き換えたもの（200文字を超えたら切り詰めてハッシュを付ける）。

The entry format is internal to Claude Code and changes between versions, so scripts that parse these files directly can break on any release.

エントリの形式は Claude Code の内部仕様で、バージョン間で変わる。 なので、これらのファイルを直接解析するスクリプトは、どのリリースでも壊れうる。

やりたいこと	設定
保存先を ~/.claude の外に	環境変数 CLAUDE_CONFIG_DIR
<project> の名前を自分で決める	環境変数 CLAUDE_CODE_PROJECT_DIR_NAME（v2.1.234 以降。CLAUDE_CONFIG_DIR と併用しないと無視される。settings の env では設定できない）
保持期間（既定 30 日）を変える	cleanupPeriodDays（settings.json）
transcript を一切書かない	環境変数 CLAUDE_CODE_SKIP_PROMPT_HISTORY
非対話の1回だけ書かない	claude -p --no-session-persistence

早めに消すなら claude purge。claude rm <id> で background セッションを消しても transcript はディスクに残り、claude --resume で開ける。

そのまま使える具体例

claude -n auth-refactor              # 名前を付けて起動
claude --continue                    # 直近を再開
claude --resume <session-id>         # どのディレクトリからでも
claude --continue --fork-session     # 別プロセスとして分岐（承認は取り直し）
claude --from-pr 1234                # PR に紐づくセッションに絞る

コマンド	動作
/rename auth-refactor	セッション中に名前を付ける
/branch try-streaming	会話を複製して切り替える（元は残る）
/clear release-prep	いま離れる会話に名前を付けてから空にする（引数なしの /clear なら、自分で付けた名前は新しい会話に残る。生成タイトルは残らない）
/export	人が読む形で書き出す

セッションピッカー: Ctrl+W でリポジトリの全 worktree へ、Ctrl+A でマシン上の全プロジェクトへ広げる。Ctrl+B で今の git ブランチに絞る。Ctrl+R で名前を付ける。Space で中身をプレビュー。検索欄に PR / MR の URL を貼ると、それを作ったセッションが見つかる。

原典で言及されている関連文書

• worktrees — worktree のセッションを再開したときの戻り先
• permission-modes — 再開後のモードを決める既定
• headless — -p での再開と --output-format
• sub-agents — --agent で始めたセッション、background subagent
• context-window — /compact で何が生き残るか
• costs — 長いセッションで使用量が増える理由
• prompt-caching — キャッシュの寿命（要約ダイアログが出る条件）
• hooks — transcript_path を受け取る
• claude-code-best-practices — clear と compact の使い分け
• cli-reference — フラグの一覧
• env-vars — CLAUDE_CONFIG_DIR / CLAUDE_CODE_PROJECT_DIR_NAME / CLAUDE_CODE_SKIP_PROMPT_HISTORY
• settings — cleanupPeriodDays