global claude settings plan

Global Claude Settings Management Plan

Current State Analysis

Currently, each Claude Code project has individual configurations stored in .claude.json with project-specific settings including:

• allowedTools: Tools permitted for each project
• ignorePatterns: Files/directories to exclude
• mcpServers: MCP server configurations per project
• hasTrustDialogAccepted: Trust settings per project

Problems identified:

• Settings like allowedTools and ignorePatterns vary inconsistently across projects
• No centralized way to apply common settings across all projects
• Repetitive permission setup for each new project directory
• Inconsistent MCP server availability across different working directories

Proposed Solution Architecture

1. Global Settings Template System

Create a centralized settings management system that:

• Defines common permissions that should be applied globally
• Maintains project-specific overrides when needed
• Syncs settings automatically when running cl command

2. Implementation Strategy

Phase A: Audit Current Settings

• Find all .claude/settings*.json files across /home/hassen/
• Catalog common allowedTools patterns (Bash, Read, Edit, Write, etc.)
• Identify frequently used ignorePatterns (node_modules, .git, .env, etc.)
• Document project-specific settings that should remain local

Phase B: Create Global Settings Infrastructure

• Create ~/.claude/global-settings.json template with common settings:

  {
    "allowedTools": ["Bash", "Read", "Edit", "Write", "LS", "Glob", "Grep", "MultiEdit"],
    "ignorePatterns": ["node_modules", ".git", "*.log", ".env*", "dist", "build"],
    "commonMcpServers": {
      "browsermcp": true,
      "github-mcp": true, 
      "gmail-mcp": true
    }
  }

Phase C: Enhance setupClaudeServers Function

• Add settings sync logic to setupClaudeServers function
• Merge global settings with existing project settings (non-destructive)
• Add --skip-settings-sync flag for projects that need custom configs
• Create backup of existing settings before modification

Phase D: Smart Settings Merger

• Implement logic to:
  • Copy global allowedTools if project has empty array
  • Merge ignorePatterns (global + project-specific)
  • Apply hasTrustDialogAccepted: true for trusted global tools
  • Preserve project-specific MCP servers while adding global ones

3. Settings Sync Workflow

When cl is executed:

1. Load global settings template from ~/.claude/global-settings.json
2. Check if current directory has .claude/settings.json or create it
3. Merge settings intelligently (project settings take precedence)
4. Apply MCP server configurations
5. Launch Claude Code with unified settings

4. Example Global Settings Template

{
  "version": "1.0",
  "globalDefaults": {
    "allowedTools": [
      "Bash", "Read", "Edit", "Write", "MultiEdit", 
      "LS", "Glob", "Grep", "Task", "TodoRead", "TodoWrite",
      "WebFetch", "WebSearch"
    ],
    "ignorePatterns": [
      "node_modules/**",
      ".git/**", 
      "*.log",
      ".env*",
      "dist/**",
      "build/**",
      ".cache/**",
      "tmp/**",
      "*.tmp"
    ],
    "hasTrustDialogAccepted": true,
    "enabledMcpjsonServers": [],
    "disabledMcpjsonServers": []
  },
  "projectOverrides": {
    "/home/hassen/workspace/sensitive-project": {
      "allowedTools": ["Read"],
      "hasTrustDialogAccepted": false
    }
  }
}

5. Implementation Files

• ~/.claude/global-settings.json - Global settings template
• ~/config/scripts/private/lib/claude-settings-manager.sh - Settings sync script
• Enhanced setupClaudeServers function in misc.bash

6. Usage Examples

# Normal usage - applies global settings
cl

# Skip settings sync for sensitive projects  
cl --skip-settings-sync

# Force reset project settings to global defaults
cl --reset-to-global

# Show what settings would be applied
cl --dry-run

7. Benefits

• Consistency: All projects get same baseline permissions
• Security: Sensitive projects can opt-out with overrides
• Convenience: No repeated permission dialogs
• Maintainability: Central location for permission management
• Flexibility: Project-specific settings still supported

8. Migration Strategy

1. Phase 1: ✅ Add browsermcp to global setupClaudeServers (COMPLETED)
2. Phase 2: Audit existing settings across all projects
3. Phase 3: Create global settings template
4. Phase 4: Implement sync logic in setupClaudeServers
5. Phase 5: Test with subset of projects
6. Phase 6: Full rollout with documentation

9. Future Enhancements

• Settings Profiles: Different profiles for work/personal projects
• Validation: Ensure settings are valid before applying
• Backup/Restore: Easy rollback if settings cause issues
• CLI Tool: Dedicated claude-settings command for management
• Integration: Sync with other development environment configs