Sessions and Storage
These variables decide where Claude Code keeps its files and how it handles saved sessions.
They also control installs and auto updates.
CLAUDE_CONFIG_DIR is the most used one. It moves the whole .claude folder.
This page lists 78 variables. Use absolute paths. Set DISABLE_AUTOUPDATER to stop updates. Project and local settings cannot set CLAUDE_CONFIG_DIR. Set these in your shell.
Example
export CLAUDE_CONFIG_DIR="$HOME/.claude-work"
claude
This session uses a separate config folder, so you can keep a work and a personal setup apart.
Variables
The rows are in name order. See Environment Variables for what each column and badge means.
| Variable | Status | What it does | Values and default | Notes |
|---|---|---|---|---|
BUN_ | Undocumented: Only the program shows this item. It can change without notice. | Names the Bun install folder. Claude Code uses it to detect a Bun global install and pick bun or npm as the package manager for update and install-prefix commands. | Text. Checked against <value>/ in the executable path | Auto-update and install detection |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Asks the session logs API for only the lines after the last compaction. | On or off. A truthy value adds the query parameter after_ to the session logs fetch | Remote session log fetch. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Marks that a macOS process already re-executed with disclaimed responsibility. This avoids a second re-exec. | Text. Claude Code sets it to 1 before execve. The new process reads it, then deletes it | MacOS background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Tells a background session that the workspace was already trusted. Project settings env and hooks then stay on. | On or off. The dispatcher sets 1. The session also checks the stored trust record | Background sessions. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Tells Claude Code that the host manages updates. Plugin autoupdate then turns off when the host pin says so. | On or off | Host-embedded sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the git base ref that Claude Code uses in merge- calls for diffs. Claude Code rejects a ref that starts with -. | Text. A per-checkout ref from CLAUDE_ wins | Cloud and repo checkout sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Gives a base ref for each repo checkout. It feeds the same merge- diff logic as CLAUDE_. | Text | Cloud and repo checkout sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Skips the config migrations on a fresh config. It marks them as done. | On or off. Applies only when two further checks about a fresh cloud config pass | Cloud sessions |
CLAUDE_ | Documented: An official docs page names this item. | Marks a session that Claude Code started as a subprocess. Claude Code sets it. | On or off. A nested interactive session skips -- lists. CLAUDE_ overrides that | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Makes the config freshness watcher use file system events instead of interval polling. | On or off, off by default. It takes effect only on Linux. Background sessions unset it | Linux only |
CLAUDE_ | Documented: An official docs page names this item. | Uses only the top admin source env block instead of merging env per key across admin sources. | On or off. Must be in the environment at start | Managed settings |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Turns off the idle accounting that parks session activity while Claude waits for the user. | On or off, off by default | All sessions |
CLAUDE_ | Documented: An official docs page names this item. | Turns off file checkpointing, so / cannot restore code. Overrides file. | On or off. SDK sessions also need CLAUDE_ | All sessions. Project env can set it before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Stops the home settings seed from starting in the file sync worker. The start check reports disabled. | On or off, off by default. Claude Code reads a truthy string from the child spawn environment | Remote and hosted sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Stops the session activity tracker from counting nested prompts that block on the user. | On or off, off by default | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Turns off the repair of a user message that arrives wrapped one level deep on the input stream. The log then says repair_. | On or off, off by default | SDK and stream input |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Skips arming the startup work gate that makes queued startup tasks wait. | On or off, off by default | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Overrides the total download deadline of the updater download, for tests. | A number. Invalid or 0 gives the default | Native installer and updater download |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Flushes the transcript to storage right after each persist, before the turn goes on. | On or off, off by default. Also on when CLAUDE_ has a value | SDK and print mode with session persistence |
CLAUDE_ | Documented: An official docs page names this item. | Turns on file checkpointing in non-interactive mode. | On or off, off by default. CLAUDE_ still wins. The SDK sets it to true when its option is on | SDK and -- mode |
CLAUDE_ | Documented: An official docs page names this item. | Exits the process this many ms after the query loop goes idle. | A number, off by default. Whole number. A value above 0 turns it on | SDK mode and scripts |
CLAUDE_ | Documented: An official docs page names this item. | Keeps transcripts and history when CLAUDE_ would mark a session as nested. | On or off, off by default | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Turns off the pacing of outbound messages to local uds inboxes. The code credits and debits a pacer for each send. | On or off. When set, the pacing check returns false. When unset, a feature flag decides | All sessions, cross-session messaging |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Lowers the longest hold time of the home seed step. The value cannot raise the built-in maximum. | A number of milliseconds. A whole number, with a minimum of 0. The result is the smaller of this value and a built-in cap | Host-seeded home or settings sync |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Lowers the longest wait for the verdict of the home seed step. The value cannot raise the built-in maximum. | A number of milliseconds. A whole number, with a minimum of 0. The result is the smaller of this value and a built-in cap | Host-seeded home or settings sync |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Records the session id that the host app gave in the session registry entry as host. | Text. Read only for host-started sessions | Host apps (desktop) |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Holds the worktree path that a host declares for the session. Claude Code checks it against the start directory and reports problems. | Text. Claude Code deletes it from the env of child processes | Host apps |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Holds the fence that a host declares for the worktree. Claude Code checks it and reports a problem such as fence_. | Text. Claude Code deletes it from the env of child processes | Host apps |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Pins the storage backend and the config home at start. Claude Code then reports a later change of CLAUDE_. | On, off, or unset, off if unset. Any truthy string also triggers the pin at CLI entry. Unset falls back to a feature flag | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Names the folder of managed (policy) settings in place of the machine default. This build ignores it. We set it to a folder with managed-. The debug log still read the machine default folder. | Text. Claude Code also sets it to a config dir in the env it builds for isolated runs | All sessions, managed settings |
CLAUDE_ | Documented: An official docs page names this item. | Gives the path of the session inbox socket to hooks and Bash commands. | Set by Claude Code when it binds the socket | Sessions with cross-session messaging |
CLAUDE_ | Documented: An official docs page names this item. | Gives a per-session token that a script can send to the inbox socket to prove it belongs to the session. | Text (a secret). Set by Claude Code beside the socket path. Claude Code deletes it when the socket closes | Sessions with cross-session messaging |
CLAUDE_ | Documented: An official docs page names this item. | Lets Claude Code run the package manager upgrade command in the background. Matches the docs for Homebrew and WinGet. | On or off. The upgrade runs with a 300000 ms timeout and logs pm_ or pm_ telemetry | Homebrew and WinGet installs |
CLAUDE_ | Documented: An official docs page names this item. | Sets the projects/ subdir name for transcripts and memory. Needs CLAUDE_. | Text. Claude Code refuses Windows reserved names | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Carries a pid: token across a relaunch. It proves that the home dir trust came from the parent process. | Text. Claude Code sets it on relaunch | Relaunched sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Carries the proactivity baseline permission mode across a relaunch. Claude Code drops bypass when it is not allowed. | Claude Code sets it on relaunch. It reads it once and deletes it from the env | Relaunched sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Carries across a relaunch whether the proactivity choice was already made. | Claude Code sets it on relaunch. It reads it once and deletes it | Relaunched sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Carries across a relaunch whether proactivity was ever on. | Claude Code sets it on relaunch. It reads it once and deletes it from the env | Relaunched sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Carries the proactivity level across a relaunch. An invalid level clears the related relaunch vars. | Claude Code sets it on relaunch. It reads it once and deletes it from the env | Relaunched sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Restricts use of personal Claude Code files, per a bundle message. The check also reads a settings-level source. | On or off. Part of the env list that background sessions pass on | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Names a source session to load at start with the sessions API. It applies when a URL or SDK URL start has no messages. | Text. Claude Code clears it for child worker processes | Remote and SDK starts |
CLAUDE_ | Documented: An official docs page names this item. | Resumes a turn that ended in the middle. | On or off. Claude Code sets it to 1 when it restarts a worker or background session a second time | SDK and background sessions |
CLAUDE_ | Documented: An official docs page names this item. | Bounds the age of the last message for auto resume of a turn. | A number of milliseconds. 0 or unset gives no bound. Negative or non-numeric gives 3600000 ms | SDK and background sessions |
CLAUDE_ | Documented: An official docs page names this item. | Overrides the continuation text that Claude Code sends to the model when an interrupted turn resumes instead of resending its prompt. | Text, Continue from where you left off. by default. Empty string uses the default. The background supervisor sets it on respawn after a first attempt | Resume, background sessions, -. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Names why a host resumed an interrupted turn. The first reply frames of the resumed turn carry the value. | Text. Other values fall back to interrupted_ | Hosts and SDK output. Docs of the SDK frame list examples such as host_ |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | On resume, waits up to this many ms for Session hooks, then continues without them. A Probes run saw no effect. | A number of milliseconds. Integer 1 to 2147483647, unset by default. When unset, resume does not wait for these hooks | Resume of a session that has messages |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Tells a resumed or forked session that its source session is still alive. It carries ids and a boundary time used to skip rows already seen. | Text. Fields seen are session, parent, and boundary | Resume and fork. A host sets it. Not set from project env before trust |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets the idle age in minutes after which a resumed session receives the return prompt. Default is 70. | A number, 70 by default. Integer, default 70. Works only when a feature flag or a feature flag is on | Interactive resume. Gated by a feature flag and a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Works only behind a feature flag or server gate | Sets the estimated token size above which a resumed session receives the return prompt. Default is 100000. | A number, 100000 by default. Integer, default 100000. Works only when a feature flag or a feature flag is on | Interactive resume. Gated by a feature flag and a feature flag |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | On resume, does not treat trailing context-only user rows from the host as a new prompt. This keeps interrupted-turn detection correct. | On or off. Claude Code also passes it to the parked-permission logic as tolerates | Resume and SDK or remote hosts |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | On resume, lets context seed rows and queued task notifications pass in interrupted-turn detection. Then the log reads as no turn rows. | On or off | Resume and SDK or remote hosts |
CLAUDE_ | Documented: An official docs page names this item. | Holds the current session ID for Bash, hook, and stdio MCP subprocesses. Session sync also reads it. | Text. Claude Code sets it for subprocesses. Claude Code deletes it from some inherited envs so a child does not reuse it. For stdio MCP servers the ID stays as it was at spawn | Bash, PowerShell, hooks, MCP stdio. Claude Code sets it |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Names the kind of session. The value bg marks a background session, which changes cwd handling and restart advice. | Text. The code seen tests only the value bg | Background sessions. The supervisor sets it |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the session name in the concurrent-session record. A user-set name has source user. | Text. The code trims it. An empty result means no name | Concurrent-session registry, background sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Changes the order of session start announcements relative to the first prompt. When set, they come before it. | On or off. The exact order effect was not read further | All sessions |
CLAUDE_ | Documented: An official docs page names this item. | Skips writing prompt history and session transcripts to disk. Such sessions do not show in resume or up-arrow history. | On or off. Persistence reports the reason skip_. It also marks a nested ambient session | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Overrides the no-data stall timeout of the update download. Meant for tests. | A number. A zero or invalid value falls back to 120000 ms | Installer and updater downloads |
CLAUDE_ | Documented: An official docs page names this item. | Makes a stream- run write a result message with a startup_ for startup failures that end with stderr alone. | On or off | Print mode with -- |
CLAUDE_ | Documented: An official docs page names this item. | Overrides the temp directory for internal temp files. Claude Code also passes it to child shells and uses it as TMPDIR in the sandbox. | Text. Falls back to /. The sandbox also reads undocumented CLAUDE_ and uses / last | All sessions |
CLAUDE_ | Documented: An official docs page names this item. Differs: The official docs and the program disagree. The row says how. The official docs and the program disagree. The row says how. | Trims the transcript before each compaction once the file passes 5 MB. The docs match this. The docs omit that 0 also blocks a flag-driven path. | On, off, or unset. For the remote path it overrides a feature flag. The local path needs non-interactive and not CLAUDE_ | - and SDK sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Picks slim over counted mode for tool results in the transcript of SDK sessions that use an SDK URL. | On or off. Read at startup in non-interactive sessions with an SDK URL | SDK URL sessions |
CLAUDE_ | Documented: An official docs page names this item. | Sets the config directory in place of ~/.. It also changes the name of the secure storage entry with a hash of the path. | Text | All sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Enables the import-conversations command. Without it the command says it is not enabled. | On or off. The command also needs -- | CLI import command |
CLAUDE_ | Documented: An official docs page names this item. | Holds the job directory of a background session. Claude Code writes exit- and exit- files there. | A path. Claude Code sets it | Background sessions |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Carries the session -- paths over a relaunch of Claude Code. | - | - |
CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Sets the temp directory for the Bash sandbox, after CLAUDE_. | - | - |
DISABLE_ | Documented: An official docs page names this item. | Turns off automatic background updates. | On or off | - |
DISABLE_ | Documented: An official docs page names this item. | Turns off installation warnings. | On or off | - |
DISABLE_ | Documented: An official docs page names this item. | Blocks every update, including claude update and claude install, with the message "Updates are disabled by your administrator". | On or off. Claude Code also reports it as the reason the auto-updater is off, ahead of DISABLE_ | All sessions. Project env can set it before trust |
TEMP | Documented: An official docs page names this item. | Names the temp directory. Claude Code uses it to find the temp dir when CLAUDE_ is not set. | Text. Non-empty string. On Windows, Claude Code tries TEMP, then TMP | All sessions |
TERMUX_ | Undocumented: Only the program shows this item. It can change without notice. | Marks the Termux app on Android. Claude Code then uses $PREFIX/ instead of / for sockets and daemon files. | Text. Non-empty string, with PREFIX set. Claude Code uses it for the daemon dir, the socks dir, and a path check | Termux on Android |
TMP | Documented: An official docs page names this item. | Names the temp directory. Claude Code uses it as a fallback when CLAUDE_ and TMPDIR are not set. | Text. Non-empty string. On Windows, Claude Code tries TEMP then TMP | All sessions |
TMPDIR | Documented: An official docs page names this item. | Names the temp directory. Claude Code uses it as the temp root on Linux when CLAUDE_ is not set. | Text. Non-empty string. macOS ignores it for the temp root. Claude Code also adds it to the allowed write paths | All sessions |
XDG_ | Documented: An official docs page names this item. | Names the XDG cache directory. Claude Code uses it for cache paths and adds it to allowed sandbox paths. | Text. Non-empty string. Default is ~/. | Linux |
XDG_ | Documented: An official docs page names this item. | Names the XDG config directory. Claude Code uses it for the global git ignore file and the Anthropic config dir. | A path. Non-empty absolute path. Default is ~/. | Linux and macOS |
XDG_ | Documented: An official docs page names this item. | Names the XDG data directory. Claude Code uses it to find shell history and adds it to allowed sandbox paths. | Text. Non-empty string. Default is ~/. | Linux |
XDG_ | Undocumented: Only the program shows this item. It can change without notice. | Names the XDG runtime directory. Claude Code puts the cc- socket dir under it. | Text, dir by default. Non-empty string. Falls back to a default dir if unset or if the path is too long for a socket | Linux |
XDG_ | Documented: An official docs page names this item. | Names the XDG state directory. Claude Code uses it for log and state paths and adds it to allowed sandbox paths. | Text. Non-empty string. Default is ~/. | Linux |
How It Works
Claude Code writes settings, transcripts, and caches under the config folder.
Settings files copy env values as written. No shell expands them, so ~ and $HOME stay as typed. Use an absolute path in settings.json.
Related Pages
- Environment Variables: how Claude Code reads variables and which value wins.
- Files on Disk
- Sessions and Storage
- Undocumented Items: every item that only the program shows.
Source: the program (variable names found in the 2.1.312 binary) and the Environment Variables page of the official docs.