sync-environment-variables

Sync Environment Variables

Add missing environment variable entries with explicit defaults to settings files.

Arguments

Argument	Description
--target project	Update .claude/settings.json (default)
--target local	Update .claude/settings.local.json
--dry-run	Show changes without modifying files
--include-undocumented	Include changelog/discovered vars (not just official)

Phase 1: Discovery

Run environment variable discovery using the same process as list-environment-variables:

1. Invoke docs-management skill for official documentation
2. WebFetch CHANGELOG.md for additional variables
3. If --include-undocumented, spawn MCP research agents

Collect all discovered variables with their default values.

Phase 2: Read Current Settings

Determine target file based on --target argument:

Target	File Path
project (default)	.claude/settings.json
local	.claude/settings.local.json

Read the target file. If it doesn't exist:

• For project: Create new file with basic structure
• For local: Create new file (this is gitignored)

Parse the current env section (if present).

Phase 3: Compare and Categorize

For each discovered environment variable, categorize:

Category	Criteria	Action
MISSING	Not in current settings, has known default	Add to settings
EXISTS	Already in current settings	Skip (preserve user value)
USER-SPECIFIC	No universal default (e.g., API keys)	Skip, report only
CUSTOM	CLAUDE_HOOK_* or repo-specific	Never touch

Variables to Add (with defaults)

These variables have known, safe defaults:

{
  "env": {
    "DISABLE_AUTOUPDATER": "0",
    "DISABLE_TELEMETRY": "0",
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "0",
    "CLAUDE_CODE_SKIP_EXT_PROMPT": "0"
  }
}

Variables to NEVER Add Automatically

• ANTHROPIC_API_KEY - User-specific, no default
• CLAUDE_CODE_USE_BEDROCK - Provider choice, user decision
• CLAUDE_CODE_USE_VERTEX - Provider choice, user decision
• AWS_* - AWS credentials, user-specific
• GOOGLE_* - Google credentials, user-specific
• HTTP_PROXY / HTTPS_PROXY - Network-specific
• CLAUDE_HOOK_* - Repository-specific hook variables

Phase 4: Preview Changes

Display what will be added:

## Environment Variable Sync Preview

### Target: .claude/settings.json

### Variables to Add
| Variable | Default | Reason |
|----------|---------|--------|
| DISABLE_AUTOUPDATER | "0" | Official default, not in current settings |
| ... | ... | ... |

### Variables Skipped (Already Set)
| Variable | Current Value |
|----------|---------------|
| DISABLE_TELEMETRY | "1" |
| ... | ... |

### Variables Skipped (No Safe Default)
| Variable | Reason |
|----------|--------|
| ANTHROPIC_API_KEY | User-specific, no universal default |
| ... | ... |

Phase 5: User Confirmation

Unless --dry-run is specified, ask for confirmation:

AskUserQuestion:
  question: "Apply these changes to settings?"
  options:
    - "Yes, apply changes"
    - "No, abort"
    - "Show me the full file preview first"

If --dry-run, stop here and report "Dry run complete. No changes made."

Phase 6: Apply and Validate

1. Read current file (or create new if doesn't exist)
2. Merge new env vars into existing env section
3. Preserve existing values - never overwrite user-set values
4. Alphabetical order - sort env vars alphabetically
5. Write updated file
6. Validate JSON - ensure file is valid JSON after write
7. Report success

File Structure

{
  "env": {
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "0",
    "DISABLE_AUTOUPDATER": "0",
    "DISABLE_TELEMETRY": "0"
  }
}

If file has other sections (permissions, hooks, etc.), preserve them.

Error Handling

Error	Action
Target file not valid JSON	Report error, do not modify
Write permission denied	Report error with path
Discovery failed	Report partial results, ask to continue

Post-Sync Verification

After applying changes:

1. Read back the modified file
2. Validate JSON syntax
3. Confirm all intended changes were applied
4. Report any discrepancies

Example Output

## Sync Complete

**Target:** .claude/settings.json

### Added (3 variables)
- CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR = "0"
- DISABLE_AUTOUPDATER = "0"
- CLAUDE_CODE_SKIP_EXT_PROMPT = "0"

### Preserved (1 variable)
- DISABLE_TELEMETRY = "1" (user-set value kept)

### Skipped (2 variables)
- ANTHROPIC_API_KEY (no safe default)
- CLAUDE_CODE_USE_BEDROCK (provider choice)

**File validated:** JSON syntax OK