atxtechbro / atxtechbro/dotfiles

Migrate Claude Code Settings to settings.json Format

Open
#577 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## 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
```json
{
"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
```json
{
"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

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading utils/configure-claude-code-settings.sh and the existing .claude/settings/claude-code-defaults.json file, then verify the documented settings.json support and version requirements. Compare the current CLI-based setup with the proposed user and project settings paths. Done means the migration, setup-script behavior, documentation, compatibility handling, and clean-machine test are resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.