# How to Resolve Conflicts When Merging Settings With Existing Claude Code Configurations

> Learn how to resolve conflicts when merging settings with existing Claude Code configurations. Deep merge JSON settings combining your hooks and MCP servers with new template definitions, preserving customizations.

- Repository: [Daniel Avila/claude-code-templates](https://github.com/davila7/claude-code-templates)
- Tags: how-to-guide
- Published: 2026-04-26

---

**When the Claude Code CLI detects existing configuration files during template installation, it provides a "Merge configurations" option that performs a deep merge of JSON settings—combining your existing hooks and MCP servers with incoming template definitions while preserving customizations.**

Installing templates from the **davila7/claude-code-templates** repository into projects that already contain Claude Code setups requires careful handling of files like [`CLAUDE.md`](https://github.com/davila7/claude-code-templates/blob/main/CLAUDE.md), [`.mcp.json`](https://github.com/davila7/claude-code-templates/blob/main/.mcp.json), and `.claude/` directories. The CLI includes intelligent conflict resolution mechanisms that allow you to resolve conflicts when merging settings with existing Claude Code configurations without overwriting your existing work.

## How the CLI Detects Configuration Conflicts

When you run the installer, the tool scans the target directory for existing Claude Code configurations. If detected, the `promptUserForOverwrite` function in [`cli-tool/src/file-operations.js`](https://github.com/davila7/claude-code-templates/blob/main/cli-tool/src/file-operations.js) (lines 310-348) triggers an interactive prompt listing the conflicting files and offering three resolution paths:

- **Backup & overwrite**: Archives existing files before replacing them
- **Merge configurations**: Combines existing and new settings
- **Cancel**: Aborts the installation

The merge option presents to users as:

```javascript
// cli-tool/src/file-operations.js – promptUserForOverwrite
// https://github.com/davila7/claude-code-templates/blob/main/cli-tool/src/file-operations.js#L310-L348
const choices = [
  { name: '🔀 Merge configurations – Combine existing with new templates', value: 'merge' },
  // ... other choices
];

```

## The Deep Merge Implementation

Choosing **merge** activates sophisticated deep-merge logic that preserves existing data structures while incorporating template updates. The implementation handles JSON configurations differently from standard file overwrites.

### Step-by-Step Merge Process

The `mergeSettingsFileFromContent` function (lines 195-221) executes the following sequence:

1. **Load existing JSON**: Reads the current configuration using `fs.readJson`

2. **Filter hooks by selection**: When templates specify hook subsets, both collections are filtered to retain only selected hooks:

```javascript
// cli-tool/src/file-operations.js – mergeSettingsFileFromContent
// https://github.com/davila7/claude-code-templates/blob/main/cli-tool/src/file-operations.js#L195-L221
if (templateConfig.selectedHooks && newSettings.hooks) {
  newSettings.hooks = filterHooksBySelection(newSettings.hooks, templateConfig.selectedHooks);
}

```

3. **Deep-merge objects**: Combines configurations using object spreading with special handling for the `hooks` sub-object:

```javascript
const mergedSettings = {
  ...existingSettings,
  ...newSettings,
  hooks: {
    ...existingSettings.hooks,
    ...newSettings.hooks
  }
};

```

4. **Preserve formatting**: Writes the merged result with consistent spacing:

```javascript
await fs.writeJson(destPath, mergedSettings, { spaces: 2 });

```

### MCP Server Configuration Merging

For Multi-Component-Platform (MCP) configurations, the `mergeMCPFileFromContent` function (lines 48-78) applies similar logic to the `mcpServers` map, merging server definitions while stripping descriptive fields added by templates.

## Handling Edge Cases and Manual Resolution

While automatic merging resolves most conflicts, specific scenarios require manual intervention.

### Duplicate Keys With Different Values

The spread operator sequence `...existingSettings` followed by `...newSettings` means **template values override existing values** when keys collide. If you need to preserve specific existing values, manually edit the merged file after installation.

### Hook Name Collisions

If both configurations define a hook with identical names but different implementations, the template definition wins because of the `...newSettings.hooks` spread. Resolve this by:

- Renaming one hook before merging
- Manually editing the merged file to combine implementations
- Using the "Backup & overwrite" option instead, then manually porting desired logic

## Best-Practice Workflow for Safe Merging

Follow this sequence to safely integrate new templates into existing Claude Code projects:

1. **Execute the installer**:

```bash
npx claude-code-templates@latest --install my-template

```

2. **Select "Merge configurations"** when the CLI displays:

```

⚠️  Existing Claude Code configuration detected!
The following files/directories already exist:
   • CLAUDE.md
   • .claude/
   • .mcp.json

```

3. **Review merged files**: Inspect [`settings.json`](https://github.com/davila7/claude-code-templates/blob/main/settings.json), [`.mcp.json`](https://github.com/davila7/claude-code-templates/blob/main/.mcp.json), and hook definitions to verify correct integration

4. **Version control**: Commit the updated configuration files to track changes

If you need to force a clean installation after experimenting with merges, backup your existing configuration first:

```bash
cp -r .claude .claude.backup
cp .mcp.json .mcp.backup.json

# Then run installer selecting "Backup & overwrite"

```

## Summary

- The Claude Code CLI detects existing configurations via `promptUserForOverwrite` and offers merge, backup, or cancel options
- **Merge configurations** performs a deep merge using `mergeSettingsFileFromContent`, preserving existing hooks while adding template-defined ones
- Template values take precedence over existing values when keys collide due to the object spread operator sequence
- Hook filtering occurs via `filterHooksBySelection` (lines 86-92) before merging to respect user template selections
- Always review merged JSON files before committing to ensure critical customizations remain intact

## Frequently Asked Questions

### What happens if a hook exists in both my current config and the template?

The template's hook definition overwrites your existing hook with the same name. The merge algorithm at lines 195-221 spreads `...newSettings.hooks` after `...existingSettings.hooks`, giving precedence to incoming template values. Rename your existing hook before merging if you need to preserve both implementations.

### Which configuration values take precedence during a merge?

Template values take precedence over existing values when keys collide. The merge object spreads `...existingSettings` first, then `...newSettings`, meaning properties in the incoming template overwrite those in your current configuration. Review the merged output in [`settings.json`](https://github.com/davila7/claude-code-templates/blob/main/settings.json) immediately after installation to verify critical settings.

### Can I selectively merge only specific hooks from a template?

Yes. The CLI filters hooks using `filterHooksBySelection` (lines 86-92) before merging occurs. When the template installation prompts you for hook selection, choose only the hooks you want to import. The merge routine then combines only your selected template hooks with your existing hook collection, leaving unselected hooks from both sides unaffected.

### How do I revert a merge if something goes wrong?

Before merging, the CLI offers a "Backup & overwrite" option that archives your existing `.claude/` directory and configuration files with timestamps. If you proceed with merge and encounter issues, restore from these backups or manually edit the JSON files to remove unwanted template additions. There is no automatic "undo" function for the merge operation itself.