Memory and context

Control what Claude Code loads into context, how it compacts, and where it keeps memory and plans. See Manage context and Memory.

autoCompactEnabled

Have Claude Code compact the conversation automatically when context approaches the limit. Appears in /config as Auto-compact, and toggling it there writes this key to your user settings.

• Scope: Any file
• Type: Boolean
  • true: Claude Code compacts the conversation automatically when context approaches the limit
  • false: Claude Code doesn't compact automatically
• Default: true
• Per-session overrides: DISABLE_AUTO_COMPACT turns auto-compact off for one session; whichever of the two turns it off, the other can't turn it back on

{
  "autoCompactEnabled": false
}

The manual /compact command keeps working while auto-compact is off.

autoCompactWindow

Set how full the context window gets before Claude Code compacts automatically.

• Scope: Any file
• Type: number of tokens, from 100000 to 1000000. Claude Code caps the value at your model's context window; the models overview lists each model's window
• Default: unset, so Claude Code picks a window tuned for your model
• Per-session overrides: --autocompact takes precedence over this key for one session, and CLAUDE_CODE_AUTO_COMPACT_WINDOW takes precedence over both

{
  "autoCompactWindow": 500000
}

Set it with the /autocompact command, which writes this key to your user settings. Set the auto-compact window covers how the command, flag, variable, and setting interact.

autoMemoryDirectory

Store auto memory in a directory of your choice instead of the per-project default.

• Scope: Any file
• Type: string, an absolute or ~/-prefixed directory path
• Default: unset, so Claude Code uses ~/.claude/projects/<project>/memory/

{
  "autoMemoryDirectory": "~/my-memory-dir"
}

From project or local settings, Claude Code honors this key under the same workspace trust rule as hooks, since a cloned repository can supply those files.

autoMemoryEnabled

Turn auto memory on or off. When false, Claude doesn't read from or write to the auto memory directory. You can also toggle it with /memory during a session, which writes this key to your user settings.

• Scope: Any file
• Type: Boolean
  • true: the same as unset; auto memory stays on unless something that outranks this key turns it off for the session, such as --bare, safe mode, or CLAUDE_CODE_DISABLE_AUTO_MEMORY
  • false: Claude doesn't read from or write to the auto memory directory
• Default: true
• Per-session overrides: CLAUDE_CODE_DISABLE_AUTO_MEMORY takes precedence over this key for one session, in either direction

{
  "autoMemoryEnabled": false
}

bashOutputMaxChars

Set how many characters of a successful Bash or PowerShell command's output Claude receives inline. When output passes the limit, Claude Code saves it to a file and Claude receives a short preview plus the file's path. Raise the limit when command output, such as a verbose build or a full test-suite log, routinely overflows the default and you want Claude to read it without opening the file. Requires Claude Code v2.1.261 or later.

• Scope: Any file
• Type: number of characters, a positive integer. Claude Code clamps the value into the range 4000 to 128000
• Default: unset, so Claude receives up to 30,000 characters inline

{
  "bashOutputMaxChars": 100000
}

When you set this key, Claude Code ignores the BASH_MAX_OUTPUT_LENGTH environment variable.

claudeMd

Inject CLAUDE.md-style instructions as organization-managed memory without deploying a separate file. Claude Code loads the text as a managed memory entry ahead of user and project CLAUDE.md files.

• Scope: Managed
• Type: string, the text of a CLAUDE.md file; write it as you would the file, Markdown included, with line breaks as \n
• Default: unset

This example deploys two rules as a short Markdown list:

{
  "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}

See Deploy organization-wide CLAUDE.md.

claudeMdExcludes

Skip specific CLAUDE.md files when Claude Code loads memory. In a large monorepo, use it to skip CLAUDE.md files from other teams that aren't relevant to your work; Exclude irrelevant CLAUDE.md files in the large-codebases guide walks through that case. Patterns match against absolute file paths.

• Scope: Any file
• Type: array of strings, each a glob pattern or absolute path
• Default: unset, so Claude Code loads every CLAUDE.md it finds

{
  "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"]
}

Exclusions apply only to user, project, and local memory files; managed policy CLAUDE.md files can't be excluded.

<span id="environment-variables" />

env

Set environment variables for every session and for the subprocesses Claude Code starts from it. Any variable in the environment variables reference can go here, which is how you apply one to every session or roll it out to your team.

• Scope: Any file
• Type: object mapping variable names to string values
• Default: unset

This example turns off automatic compaction and routes API requests through a proxy:

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

How env values interact with your shell

• A value here overwrites the same variable exported in your shell, and when more than one settings file sets a variable, the highest-precedence one applies.
• To cancel a shell export, set the variable to "". Claude Code treats an empty value as unset for provider selection, and subprocesses inherit the empty value.
• NO_COLOR and FORCE_COLOR set here reach only subprocesses. To change Claude Code's own interface colors, set them in your shell before launching claude.
• Values here are plain text in the settings file and reach every subprocess Claude Code starts. For an OTLP bearer token that rotates, use otelHeadersHelper; for API credentials, use apiKeyHelper.

When Claude Code applies env values

• From user settings, --settings, and managed settings: at startup, and again in the running session when a saved change alters the merged env.
• From project and local settings: after you trust the workspace, or at startup in -p mode, which never shows the trust dialog, and again when a saved change alters the merged env.
• Variables Claude Code classifies as safe, such as model selection, timeouts and limits, feature toggles, and telemetry settings: at startup from every settings file, apart from the variables project and local settings can't set.
• After you move the session with /cd on v2.1.246 or later: the new directory's project and local env values, on top of the previous directory's.

Variables Claude Code ignores in env

• Project and local settings can't set variables that a checked-out repository shouldn't control; set those in your shell, user settings, or managed settings instead. Claude Code drops each one and logs a warning you can see with claude --debug. They include:

  • Variables that choose where Claude Code stores or writes its own files: CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, and the operating-system directory variables such as HOME, TMPDIR, TMP, TEMP, and the XDG_* family.
  • Variables that export session content: OTEL_LOG_RAW_API_BODIES and the detailed beta tracing pair ENABLE_BETA_TRACING_DETAILED and BETA_TRACING_ENDPOINT.
  • Variables that change how Claude Code starts or syncs, such as CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR, and CLAUDE_CODE_PLUGIN_SEED_DIR.

  Before v2.1.251, project and local settings could set every variable this list names except HOME, XDG_CONFIG_HOME, and the variables that change how Claude Code starts or syncs.

• Identity variables that Claude Code's hosting environments own, such as CLAUDE_CODE_REMOTE and CLAUDE_CODE_ACCOUNT_UUID, are ignored from every file.

• CLAUDE_CODE_MESSAGING_SOCKET and CLAUDE_CODE_MESSAGING_TOKEN, which Claude Code exports itself, are ignored from every file. Ignoring the socket variable requires Claude Code v2.1.224 or later, and ignoring the token requires v2.1.228 or later.

• CLAUDE_CODE_PROJECT_DIR_NAME, which Claude Code reads from the launch environment only, is ignored from every file; requires v2.1.234 or later.

• CLAUDE_CODE_RESTRICTED, which Claude Code reads from the launch environment only, is ignored from every file.

fileCheckpointingEnabled

Have Claude Code snapshot files before each edit so /rewind can restore them. Appears in /config as Rewind code (checkpoints), and toggling it there writes this key to your user settings.

• Scope: Any file
• Type: Boolean
  • true: Claude Code snapshots files before each edit so /rewind can restore them
  • false: Claude Code doesn't snapshot files, so /rewind can't restore them
• Default: true
• Per-session overrides: CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING turns checkpointing off for one session; whichever of the two turns it off, the other can't turn it back on

{
  "fileCheckpointingEnabled": false
}

In a -p run or an Agent SDK session, Claude Code ignores this key. The SDK turns checkpointing on with its enableFileCheckpointing option, and a bare -p run needs CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true. See File checkpointing in the Agent SDK.

plansDirectory

Choose where Claude Code stores the plan files it writes in plan mode. Claude Code resolves the path relative to the project root and keeps the default when the path resolves outside it.

• Scope: Any file
• Type: string, a path relative to the project root
• Default: unset, so Claude Code uses ~/.claude/plans

{
  "plansDirectory": "./plans"
}

skillListingBudgetFraction

Each turn, Claude sees a listing of your skills with their descriptions, and Claude Code caps that listing at a share of the context window. When the listing is over the cap, Claude Code keeps every skill's name but drops the descriptions of the least-used skills, so Claude can still invoke those skills but is less likely to choose one on its own. Raise this key to keep more descriptions visible at the cost of more context per turn.

• Scope: Any file
• Type: number, a fraction greater than 0 and at most 1
• Default: 0.01, which reserves 1% of the context window

{
  "skillListingBudgetFraction": 0.02
}

To see how much context the listing uses and which skills contribute most, run /doctor.

skillListingMaxDescChars

Each turn, Claude sees a listing of your skills that shows each skill's description and when_to_use text. This key caps how many characters of that text Claude Code shows per skill; longer text is cut at the cap.

• Scope: Any file
• Type: number of characters, a positive integer
• Default: 1536

{
  "skillListingMaxDescChars": 2048
}

Raise it to keep long descriptions intact at the cost of more context per turn; lower it to fit more skills under skillListingBudgetFraction.

taskOutputMaxChars

Set how many characters of a background task's output Claude receives inline when Claude reads the task with the TaskOutput tool. When a finished task's output is longer, Claude receives the most recent characters. Raise the limit when your background tasks routinely produce more output than the default. Requires Claude Code v2.1.261 or later.

• Scope: Any file
• Type: number of characters, a positive integer. Claude Code clamps the value into the range 4000 to 128000
• Default: unset, so Claude receives up to 32,000 characters inline

{
  "taskOutputMaxChars": 100000
}

When you set this key, Claude Code ignores the TASK_MAX_OUTPUT_LENGTH environment variable.