Feature Request: Extend Environment Variable Expansion to `settings.json` files

[coygeek]

Title: Feature Request: Extend Environment Variable Expansion to settings.json files

Body:

Is your feature request related to a problem? Please describe.

Currently, managing secrets (like API keys) or environment-specific configurations (like webhook URLs for hooks) in settings.json files is challenging. To maintain security and flexibility, these values should not be hardcoded and committed to version control. This makes it difficult to use claude-code effectively in team environments or CI/CD pipelines where configuration is often supplied via the environment.

I've noticed that claude-code already has excellent support for environment variable expansion in .mcp.json files, as detailed in the MCP documentation. However, this valuable feature does not appear to be available in the main settings.json files (~/.claude/settings.json, .claude/settings.json, etc.). This inconsistency limits the ability to configure other core features, like hooks or authentication helpers, in a secure and portable way.

Describe the solution you'd like

I propose extending the existing environment variable expansion mechanism to all settings.json files. The implementation should recursively parse the JSON structure and replace any string value containing $VAR_NAME or ${VAR_NAME} with the corresponding value from the environment.

This would bring the powerful configuration capabilities already present for MCP servers to all aspects of claude-code configuration.

Example Usage

With this feature, a .claude/settings.json file could look like this:

{
  "apiKeyHelper": "/path/to/script-that-uses-api-key.sh",
  "env": {
    "ANTHROPIC_API_KEY": "${CLAUDE_CODE_API_KEY_FROM_ENV}"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "curl -X POST $TEAM_WEBHOOK_URL -d 'A commit is being made!'"
          }
        ]
      }
    ]
  }
}

In this example:

• ${CLAUDE_CODE_API_KEY_FROM_ENV} would be replaced by the value of the CLAUDE_CODE_API_KEY_FROM_ENV environment variable, which can be used by the apiKeyHelper script.
• $TEAM_WEBHOOK_URL in the hook command would be replaced by the value of the TEAM_WEBHOOK_URL environment variable.

Why is this feature valuable?

• Enhanced Security: Secrets like API keys can be managed via environment variables or a secret manager, preventing them from being committed to source control.
• CI/CD Integration: Simplifies running claude-code in automated pipelines where configurations are passed as environment variables.
• Improved Flexibility for Teams: Allows a single, shared .claude/settings.json to be committed to a repository, while each developer can provide their personal secrets or environment-specific values locally.
• Configuration Consistency: Aligns the behavior of settings.json with the existing, useful functionality of .mcp.json.

Prior Art / Reference

The best reference is claude-code's own implementation for .mcp.json files. Additionally, this is a standard feature in many modern developer CLI tools, such as the Google Gemini CLI, which demonstrates its utility in the ecosystem.

Thank you for considering this enhancement

[ericfitz]

I'd like to specifically configure things in settings.local.json like:

"read($TMPDIR/*)",

[bendavis78]

This would be useful in ~/.claude.json as well

[gabrielbryk]

Bump this, would love var expansion in .claude.json so i can keep sensitive vars out of files

[Nucs]

This is relatively a small feature, can we have this? Bump, nothing better than having more control via settings over claude code's behavior.