Claude Media
CLAUDE_CODE_TMPDIRで内部一時ファイルの置き場所を変える
Claude CodeTips

CLAUDE_CODE_TMPDIRで内部一時ファイルの置き場所を変える

CLAUDE_CODE_TMPDIRはClaude Codeが内部で使う一時ファイルの置き場所を変える環境変数です。末尾に付くディレクトリ名、サンドボックス内Bashとの関係、設定できる場所の制限をまとめます。

読了目安 約9分

CLAUDE_CODE_TMPDIRは、Claude Codeが内部の一時ファイルに使うディレクトリを差し替える環境変数です。/tmpの容量が足りない環境や、一時領域の置き場所を管理者が決めている環境で使います。

効くのはClaude Code自身の一時ファイルです。ここで混乱しやすいのが、Bashで走るコマンドから見える$TMPDIRとの関係でした。既定値、実際に作られるパス、サンドボックスとの関係、設定できる場所の制限を、この順に扱います。

CLAUDE_CODE_TMPDIRは何を変えるのか

この変数は、内部の一時ファイル用ディレクトリを上書きします。既定値はOSで異なります。

OS既定の一時ディレクトリ実際に使われる末尾
macOS既定の一時ディレクトリ/tmp実際に使われる末尾/claude-{uid}/
Linux既定の一時ディレクトリos.tmpdir() の戻り値実際に使われる末尾/claude-{uid}/
Windows既定の一時ディレクトリos.tmpdir() の戻り値実際に使われる末尾/claude/

指定したパスそのものではなく、その下にClaude Code専用のサブディレクトリが作られます。CLAUDE_CODE_TMPDIR=/data/cc-tmpと設定したUnix系環境なら、実体は/data/cc-tmp/claude-<自分のuid>/です。uidを含むので、複数ユーザーが同じ親ディレクトリを共有しても名前がぶつかりません。

Claude Codeがここに置くものの例は、既存の記事で確認できます。セッションごとのスクラッチパッドや貼り付けた画像は、この一時ディレクトリ配下です。置き場所の全体像はClaude Codeが保存するデータの一覧に、スクラッチパッドを片付けさせる書き方は一時ファイルを片付けさせるプロンプトにあります。

設定する場所と、効かない場所

設定できるのは、シェル、ユーザー設定、管理設定の3つです。プロジェクト設定とローカル設定では無視されます。

settings-referenceには、プロジェクト設定とローカル設定のenvに書いても落とされる変数の一覧があります。そこには「Claude Code自身が使うファイルの置き場所を決める変数」が含まれ、CLAUDE_CONFIG_DIRとCLAUDE_CODE_TMPDIR、そしてHOME・TMPDIR・TMP・TEMP・XDG_*系が名前で挙がっています。リポジトリを取得しただけで、書き込み先を外部に向けられないようにするための扱いです。この挙動はv2.1.251で入っています。

落とされた変数は警告としてログに残り、claude --debugで見られます。リポジトリの.claude/settings.jsonに書いたのに効かないときは、まずここを疑います。

シェルの設定例です。

# ~/.zshrc や ~/.bashrc に追記する例
export CLAUDE_CODE_TMPDIR="$HOME/.cache/claude-tmp"
mkdir -p "$CLAUDE_CODE_TMPDIR"

ユーザー設定に置くなら、~/.claude/settings.jsonのenvに書きます。

{
  "env": {
    "CLAUDE_CODE_TMPDIR": "/data/cc-tmp"
  }
}

シェルで設定すると、Claude Codeを起動するターミナルごとに引き継がれます。ユーザー設定なら起動元のシェルを問いません。IDE拡張やランチャーから起動する運用が混ざるなら、ユーザー設定のほうがぶれません。

末尾のディレクトリは自動で作られるか

env-varsページには、親ディレクトリの自動作成も、書き込めないパスを指定したときの挙動も記載がありません。上の例のように、親は先に作っておくのが安全です。changelogには、一時ディレクトリが満杯・書き込み不可・他ユーザー所有のとき、claude agentsが空白画面のまま反応しなくなる不具合の修正(v2.1.280)が載っています。

権限は次のように確認できます。

ls -ld "$CLAUDE_CODE_TMPDIR"
# Claude Code起動後に、末尾のディレクトリができたか確かめる
ls -ld "$CLAUDE_CODE_TMPDIR"/claude-"$(id -u)"

Windowsでは末尾が/claude/でuidは付きません。上のコマンドはUnix系向けです。

サンドボックス内のBashは別の$TMPDIRを持つ

ここが一番の落とし穴です。CLAUDE_CODE_TMPDIRが変えるのはClaude Codeの内部一時ファイルで、Bashコマンドが見る$TMPDIRは条件で変わります。Bashから見える$TMPDIRは、サンドボックスの内外で次のように決まります。

くらべる

Bashから見える$TMPDIRの決まり方

macOS・Linux

サンドボックス内のBash

サンドボックス内のBashには、書き込み可能なユーザー別の一時ディレクトリが$TMPDIRとして渡されます。上書き先が長いパスのときは、システム既定の下にある短いフォールバックが使われます。一部のツールは一時パスが長いと失敗するためです。

素のシェル

サンドボックス外のBash

シェルの$TMPDIRが設定されていれば、それを引き継ぎます。シェル側で未設定か空のとき、$TMPDIRを参照するコマンドにはCLAUDE_CODE_TMPDIRの値が渡されます。未設定、または上書き先が長いパスなら、OSの一時ディレクトリです。

つまりファイルシステム分離が有効なあいだは、サンドボックス内とサンドボックス外で$TMPDIRが別のディレクトリを指すことがあります。sandboxingページは、両者の間で一時ファイルを受け渡したいときは作業ディレクトリの下に書くよう案内しています。

ファイルシステム分離を無効にした場合は話が変わります。サンドボックス内のコマンドも、シェルの$TMPDIRをそのまま継承します。Linuxではシェルに$TMPDIRが無いことが多く、その場合はBashツールの案内に従ってClaudeがmktemp -dで作業用ディレクトリを作る、とsandboxingページにあります。分離の外し方はsandbox.filesystem.disabledの解説で扱っています。

長いパスを避けたい理由

env-varsページが長いパスのフォールバックを設けている理由は、「一部のツールは一時パスが長いと失敗する」ことです。changelogにも、上書き先が深いディレクトリだと壊れた例が残っています。

  • v2.1.162: CLAUDE_CODE_TMPDIRか$TMPDIRが深いディレクトリを指すと、セッション間メッセージ(SendMessage)が静かに壊れる不具合を修正
  • v2.1.161: CLAUDE_CODE_TMPDIRが深いパスのとき、$TMPDIR配下にUnixソケットを作るツールでEADDRINUSEが出る不具合を修正

Unixドメインソケットのパス長には、OSごとの上限があります。置き場所は短いパスにしておくほうが、こうした周辺の不具合を踏みにくくなります。セッション間メッセージの仕様はSendMessageの解説にあります。

WindowsではBashの$TMPDIRが少し違う

ネイティブWindowsでは、シェルが$TMPDIRを設定していないとき、$TMPDIRを参照するBashコマンドにはCLAUDE_CODE_TMPDIRの値が渡されます。未設定なら%TEMP%です。Claude Code自身の一時ファイルは、設定の有無にかかわらずCLAUDE_CODE_TMPDIRの値に従います。

CLAUDE_CODE_TMPDIRはサンドボックスとの組み合わせで何度も修正されてきた

changelogでCLAUDE_CODE_TMPDIRに触れている主な版は次のとおりです。

バージョン日付内容
v2.1.5日付2026年1月12日内容CLAUDE_CODE_TMPDIRを追加。一時ディレクトリの要件が特殊な環境向け
v2.1.154日付2026年5月28日内容サンドボックス内外で$TMPDIRが別の場所に解決される問題を修正
v2.1.161日付2026年6月2日内容深いパス指定時のEADDRINUSEを修正
v2.1.162日付2026年6月3日内容深いパス指定時のSendMessage不具合を修正
v2.1.163日付2026年6月4日内容全コマンドの$TMPDIRが/tmp/claude-{uid}に上書きされ、bazelやEDR環境で失敗する不具合を修正(v2.1.154での退行)
v2.1.251日付2026年8月28日内容プロジェクト設定のenvでCLAUDE_CODE_TMPDIRなどを設定できないように変更
v2.1.281日付2026年9月23日内容CLAUDE_CODE_TMPDIR設定時にサンドボックス内Bashが$TMPDIRへ書き込めない不具合を修正

追加以降、この変数はサンドボックスとの組み合わせで何度も修正されてきました。v2.1.281より前のバージョンで挙動がおかしいときは、更新してから確かめ直すのが近道です。

設定がうまくいかないときの切り分け

症状別に、確認する順番をまとめます。

切り分け

症状と最初に見る場所

  • 設定したのに別の場所に作られる

    プロジェクト設定かローカル設定のenvに書いていないか確認します。この2つではCLAUDE_CODE_TMPDIRは無視されます。シェルかユーザー設定に移します。

  • サンドボックス内のコマンドが一時ファイルを書けない

    使っているバージョンを確認します。v2.1.281より前は、上書き時にサンドボックス内Bashが$TMPDIRへ書けない不具合がありました。

  • コマンドごとに$TMPDIRが違う

    サンドボックスの内外で別になるのは仕様です。受け渡したいファイルは作業ディレクトリに置きます。

  • 孤立した一時ファイルが残る

    名前の付いた残留ファイルは別の原因があります。tmpclaude-*-cwdファイルの解説を見ます。

ほかの環境変数と並べたときの違い

CLAUDE_CODE_TMPDIRと似て見える変数にCLAUDE_CONFIG_DIRがあります。設定や履歴など永続データの場所を決める変数で、一時ファイルとは役割が違います。両方ともプロジェクト設定では無視される点だけが共通です。永続データを動かしたいのか、消えてよい作業領域を動かしたいのかで、選ぶ変数が変わります。

設定キーと環境変数を一覧で引きたいときは、Claude Code設定の総合ガイドから探せます。

試すときの手順

安全に確かめるなら、次の順で進めます。

手順

置き場所を変えて確かめる流れ

  1. 1

    変更先を決めて作る

    短いパスで、自分が書き込めるディレクトリを選んで作成します。

  2. 2

    シェルかユーザー設定に書く

    プロジェクト設定には書きません。

  3. 3

    Claude Codeを起動し直す

    実行中のセッションに反映されるかはenv-varsページに記載がないため、起動し直してから確かめます。

  4. 4

    末尾のディレクトリを確かめる

    claude-{uid}ができているか、lsで見ます。

まとめ

CLAUDE_CODE_TMPDIRで動くのはClaude Code自身の一時ファイルで、パスの末尾にはclaude-{uid}/(Windowsはclaude/)が付きます。Bashから見える$TMPDIRは、サンドボックスの内外と上書き先の長さで決まり方が変わります。ファイルを両者で受け渡したいなら作業ディレクトリを使い、置き場所は短いパスにします。プロジェクト設定は無視されるので、書く先はシェルかユーザー設定か管理設定です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →