melodic-software/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