atxtechbro / atxtechbro/dotfiles
Migrate Claude Code Settings to settings.json Format
- 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