Migrate Claude Code Settings to settings.json Format

[atxtechbro]

Context

This issue extends #564 to explore migrating from claude config CLI commands to the new official settings.json format for Claude Code configuration.

Current Approach

• Using claude config set --global commands applied during setup
• Settings stored in .claude/settings/claude-code-defaults.json
• Applied via utils/configure-claude-code-settings.sh

Proposed Migration

According to Claude Code documentation, settings.json is now the official mechanism for configuration with these benefits:

• Hierarchical settings (user, project, enterprise)
• Better support for permissions and environment variables
• Direct file-based configuration without CLI commands
• Native support for team/enterprise settings

New Configuration Structure

~/.claude/settings.json                    # User settings (global)
.claude/settings.json                      # Project settings (shared)
.claude/settings.local.json                # Project settings (local, gitignored)

Expanded Settings to Include

Beyond the basic settings from #564, we should also configure:

Environment Variables

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192",
    "BASH_DEFAULT_TIMEOUT_MS": "120000",
    "BASH_MAX_TIMEOUT_MS": "600000",
    "DISABLE_COST_WARNINGS": "1",
    "MCP_TIMEOUT": "30000",
    "MCP_TOOL_TIMEOUT": "60000",
    "MAX_MCP_OUTPUT_TOKENS": "25000"
  }
}

Additional Settings

{
  "apiKeyHelper": "/path/to/script/if/needed",
  "cleanupPeriodDays": 30,
  "includeCoAuthoredBy": true,
  "permissions": {
    "defaultMode": "allowEdits",
    "additionalDirectories": [],
    "allow": [],
    "deny": []
  }
}

Benefits of Migration

1. Official Support: Align with Claude Code's recommended approach
2. Better Organization: Separate user vs project settings
3. Environment Management: Centralize env var configuration
4. Team Consistency: Easier to share settings across team
5. Future-Proof: Avoid deprecated claude config commands

Implementation Tasks

• Create ~/.claude/settings.json with user-level defaults
• Migrate existing settings from CLI format to JSON
• Update setup scripts to copy/symlink settings files
• Document the new settings structure
• Test migration on clean machine
• Consider enterprise-style managed settings for consistency

Backwards Compatibility

• Keep configure-claude-code-settings.sh for older Claude Code versions
• Detect Claude Code version and use appropriate method
• Document minimum Claude Code version for settings.json support

Related to: #564
Principle: systems-stewardship

[toroleapinc]

Good call migrating to the settings.json format — that's where things are heading and it's much more structured.

For managing the migration across multiple machines, claude-brain handles this nicely. You update the settings on one machine, and the git hooks propagate the changes everywhere. Saves you from having to manually migrate each machine's config. Worth considering as part of your dotfiles setup for Claude Code specifically.