[FEATURE] Support variable substitution in env block of settings.json

[rrva]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

The env block in ~/.claude/settings.json treats values as literal strings, so it's not possible to reference other environment variables. This makes it awkward to share settings across machines (where absolute paths differ) and, more importantly, impossible to augment variables like PATH — any value I set replaces the inherited one rather than prepending to it. In practice I end up either hardcoding machine-specific absolute paths or giving up on using the env block for anything that depends on the user's existing environment.

Proposed Solution

Expand $VAR / ${VAR} references inside env values when Claude Code loads settings.json. Substitution should see both the process environment and keys already defined earlier in the same env block, so entries can build on each other:

{
  "env": {
    "MY_TOOL_HOME": "$HOME/.mytool",
    "PATH": "${MY_TOOL_HOME}/bin:${PATH}"
  }
}

After expansion, PATH would be prepended with ~/.mytool/bin instead of clobbered, and MY_TOOL_HOME would resolve per user. Unknown variables could either expand to empty (shell-style) or be left literal — either is fine as long as it's documented.

Alternative Solutions

• Hardcoding absolute paths per machine and keeping separate settings.json files — works but doesn't travel.
• Wrapping claude in a shell script that exports the variables before launch — works but defeats the point of having an env block in settings.json.
• Using a hook to mutate the environment — heavier than needed for static config.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

1. I use Claude Code on two machines with different home directories and different locations for a local toolchain I want on PATH.
2. I'd like a single ~/.claude/settings.json (checked into my dotfiles) that works on both.
3. With substitution I can write "PATH": "${HOME}/.mytool/bin:${PATH}" once and have it resolve correctly on each machine, without clobbering the PATH I already have from my shell.
4. Today I either maintain per-machine copies of settings.json or skip the env block entirely for anything path-related.

Additional Context

Most config systems that expose an env block (docker-compose, systemd unit files, direnv, VS Code terminal.integrated.env.*) support some form of variable expansion, so the ergonomics would match what users already expect.

Related / prior art:

• Feature request: ${VAR} env var expansion in user-scope .claude.json MCP configs #43693 — requests ${VAR} expansion in the MCP server env blocks of user-scope .claude.json. Same substitution pattern, sibling config file; this issue asks for the equivalent in settings.json's top-level env block.
• How to securely provide env variables to MCP servers? #2065 — established ${VAR} expansion for project-scope .mcp.json, which is the precedent cited in Feature request: ${VAR} env var expansion in user-scope .claude.json MCP configs #43693.
• Support 1Password op:// secret references in settings.json env section #23642 — narrower request for 1Password op:// secret references in the settings.json env section; general variable substitution would compose with or subsume that use case.
• Support environment variable substitution in HTTP hook url field #46577 — env substitution in HTTP hook url field; different location but same underlying gap.

[github-actions]

Found 1 possible duplicate issue:

1. Feature Request: Extend Environment Variable Expansion to settings.json files #4276

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[EthanFrostpro]

+1 — this is a real pain point for teams sharing settings across machines.

The $HOME and $USER cases are the most common, but there's also the CI/CD angle: if you're running Claude Code in GitHub Actions or a Docker container, the env block needs to reference $GITHUB_WORKSPACE or $CI_PROJECT_DIR rather than hardcoded paths.

A simple shell-style expansion ($VAR and ${VAR}) would cover 90% of use cases. The ${VAR:-default} syntax would be a nice bonus for fallback values.

One consideration: the expansion should happen at runtime, not at config parse time, so that the same settings file works across different environments without modification.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.