User Configuration Management
MANDATORY: Invoke docs-management First
STOP - Before providing ANY response about Claude Code user configuration:
- INVOKE skill for official documentation
- QUERY for the user's specific topic
- BASE all responses on official documentation + this skill's custom references
Skipping this step results in outdated or incorrect information.
Verification Checkpoint
Before responding, verify:
If ANY checkbox is unchecked, STOP and complete the missing steps.
Overview
Central authority for managing Claude Code's user configuration directories. This skill provides:
- Keyword registry for efficient docs-management queries
- Custom workflows not covered by official docs (reset, backup/restore, drift detection)
- Command inventory linking to existing cleanup commands
- Cross-platform guidance for path handling
Architecture: Hybrid delegation - official docs via docs-management, custom workflows via skill references.
When to Use This Skill
Keywords: user config, ~/.claude, .claude.json, cleanup, storage, backup, restore, reset, MCP servers, history, plans, sessions, debug logs, prune, audit, drift detection
Use this skill when:
- Managing ~/.claude/ directory contents
- Cleaning up storage (sessions, agents, debug, cache)
- Backing up or restoring configuration
- Resetting Claude Code while preserving MCP servers
- Searching command history
- Managing plan files
- Viewing session statistics
- Auditing configuration health
- Detecting structure drift after updates
Keyword Registry for docs-management Queries
Use these keywords when querying docs-management skill:
Configuration Files
| Topic | Keywords |
|---|
| Settings Overview | "settings", "settings.json", "configuration files" |
| User Settings | "user settings", "~/.claude/settings.json" |
| Global Config | ".claude.json", "global config", "mcpServers" |
| MCP Servers | "MCP servers", "mcpServers", "user-level MCP" |
Retention & Cleanup
| Topic | Keywords |
|---|
| Retention Setting | "cleanupPeriodDays", "session retention", "auto-cleanup" |
| Session Cleanup | "sessions", "project sessions", "session files" |
| Debug Logs | "debug", "debug transcripts", "debugging" |
Storage Locations
| Topic | Keywords |
|---|
| Storage Structure | "~/.claude", "storage directory", "claude folder" |
| Projects Directory | "projects", "project sessions", "session storage" |
| Plugins Directory | "plugins", "plugin cache", "installed plugins" |
Quick Decision Tree
What do you want to do?
All actions are invoked via the consolidated
skill:
- Check storage usage -> Run
- Clean up sessions -> Run
/user-config cleanup-sessions
- Clean up agents -> Run
/user-config cleanup-agents
- Clean up debug logs -> Run
/user-config cleanup-debug
- Comprehensive cleanup -> Run
- Nuclear cleanup (everything) -> Run
/user-config prune --nuclear
- Backup configuration -> Run
- Restore from backup -> Run
- Reset (preserve MCP) -> Run - See reset-workflow.md
- Search history -> Run
- Manage plans -> Run
- Audit config health -> Run
- View session stats -> Run
/user-config session-stats
- View MCP servers -> Run
- Reset plugins (nuclear) -> Run
/user-config reset-plugins
Directory Structure Reference
~/.claude/ Directory (13 Concepts)
| Directory/File | Purpose | Cleanup Safe | Action |
|---|
| Session files per project | Yes (old files) | /user-config cleanup-sessions
|
| Debug transcripts | Yes (old files) | /user-config cleanup-debug
|
| Installed plugin cache | No (use /plugin) | |
| Edit undo history | No (loses undo) | Never auto-clean |
| Saved execution plans | Yes (old files) | |
| Shell state captures | Yes | |
| Todo list state | Yes (old files) | |
| Feature flag cache | Always safe | |
| IDE lock files | Yes (stale) | |
| Session environment | Yes | |
| User settings | Never | Manual only |
| Command history | Usually keep | |
| OAuth tokens | Never backup | Manual only |
~/ Root Files (3 Concepts)
| File | Purpose | Backup Priority |
|---|
| Global config (mcpServers, OAuth, flags) | Critical (mcpServers) |
| User-level instructions | High |
| User-level ignore patterns | Medium |
IMPORTANT: There is NO
file. User-scope MCP servers go in
under the
field.
Action Inventory
All actions consolidated under the
skill:
Cleanup Actions
| Action | Purpose |
|---|
/user-config cleanup-agents
| Agent transcript cleanup (7d default) |
/user-config cleanup-debug
| Debug log cleanup (7d default) |
/user-config cleanup-sessions
| Session file cleanup (7d default) |
/user-config cleanup-hook-logs
| Hook log cleanup (30d default) |
| Comprehensive cleanup (--nuclear) |
Analysis Actions
| Action | Purpose |
|---|
| Unified overview of all config |
| Storage analysis |
/user-config session-stats
| Session statistics |
| API cost estimation |
| Structure drift detection |
Backup/Restore Actions
| Action | Purpose |
|---|
| Full backup to ~/.claude-backups/ |
| Restore from backup |
| Backup MCP -> Wipe -> Restore workflow |
/user-config reset-plugins
| Complete plugin reset (cache + registry + settings) |
Configuration Actions
| Action | Purpose |
|---|
| View/edit ~/.claude.json safely |
| List/export MCP server configs |
| Search/export command history |
| List/view/archive plan files |
Session Analysis Actions
| Action | Purpose |
|---|
/user-config file-versions
| Browse file edit history |
/user-config compaction-review
| Review compaction information loss |
/user-config prompt-extract
| Extract successful prompts |
/user-config transcript-search
| Search across session transcripts |
/user-config retrospective
| Session postmortem/retrospective |
Custom Workflows (Skill-Owned)
These workflows are NOT in official documentation - they are custom features:
Reset Workflow (MCP Preservation)
For users who want a fresh start but need to preserve MCP server configs.
Full guide: references/reset-workflow.md
Quick summary:
- Backup: Extract mcpServers from ~/.claude.json
- Backup: Copy settings.json (optional)
- User wipes ~/.claude/ and ~/.claude.json
- User relaunches Claude Code (creates fresh config)
- Restore: Inject mcpServers into new ~/.claude.json
Backup/Restore Workflow
For full configuration backup and restore.
Full guide: references/backup-restore.md
Backup location: ~/.claude-backups/backup-YYYY-MM-DD-HHmmss/
Drift Detection
Detect when Claude Code updates change the config structure.
Full guide: references/known-structure.yaml
Mechanism: Compare actual ~/.claude/ against known structure manifest.
Delegation Patterns
Standard Query Pattern
text
User asks: "How do I clean up old sessions?"
1. Check action inventory (this skill)
2. Direct to: /user-config cleanup-sessions
3. If user needs more detail, query docs-management: "cleanupPeriodDays", "session retention"
Reset/Backup Pattern
text
User asks: "I want to reset Claude Code but keep my MCP servers"
1. Load this skill's references/reset-workflow.md
2. Query docs-management for: "mcpServers", ".claude.json"
3. Guide user through reset workflow
Troubleshooting Pattern
text
User reports: "Storage is using too much disk space"
1. Run /user-config storage for analysis
2. Recommend specific cleanup actions based on results
3. If needed, query docs-management for retention settings
Cross-Platform Path Handling
All commands must handle paths cross-platform:
Python:
python
from pathlib import Path
claude_dir = Path.home() / ".claude"
claude_json = Path.home() / ".claude.json"
backup_dir = Path.home() / ".claude-backups"
Bash:
bash
CLAUDE_DIR="$HOME/.claude"
CLAUDE_JSON="$HOME/.claude.json"
BACKUP_DIR="$HOME/.claude-backups"
Never hardcode:
C:\Users\USERNAME\.claude\
Retention Settings
Official Setting (via docs-management)
- Sessions inactive > N days deleted at startup
- Default: 30 days
- Setting to 0 = immediate deletion
Query docs-management: "cleanupPeriodDays", "session retention"
Command Defaults
Note: For official retention settings (like
), query
docs-management: "cleanupPeriodDays session retention"
. The defaults below
are this plugin's command defaults, not Claude Code's official defaults.
| Command | Default Retention |
|---|
| Cleanup commands | 7 days |
| Hook logs | 30 days |
| File history | Never auto-clean (dangerous) |
Troubleshooting Quick Reference
| Issue | Solution |
|---|
| Storage too large | Run then cleanup actions |
| Lost MCP servers after reset | Use workflow (backs up first) |
| Unknown files in ~/.claude | Run for drift detection |
| Can't find old session | Use to search |
| Need to restore config | Use from backup |
| "Another Claude process running" | /user-config prune --nuclear
|
Auditing Configuration
This skill provides validation criteria used by the
agent.
Audit Checks
| Category | Checks |
|---|
| JSON Validity | All .json files parse correctly |
| Orphaned Files | Sessions without projects, stale locks |
| Security | No exposed API keys in settings |
| Structure | Known vs unknown directories/files |
| Cross-References | Todos reference valid sessions |
Related Agent
The
agent performs formal audits:
- Uses this skill's known-structure.yaml for drift detection
- Validates JSON syntax
- Checks for orphaned/stale files
- Generates structured audit reports
References
Custom References (skill-owned):
- known-structure.yaml - Structure manifest for drift detection
- reset-workflow.md - MCP preservation reset guide
- backup-restore.md - Backup/restore procedures
- command-inventory.md - Full command reference
Official Documentation (via docs-management):
- Query: "settings", "settings.json" - Settings structure
- Query: "mcpServers", ".claude.json" - MCP server configuration
- Query: "cleanupPeriodDays" - Retention settings
Version History
- v1.0.0 (2025-12-30): Initial release
- Consolidated command namespace (user-config:*)
- Reset workflow with MCP preservation
- Drift detection manifest
- Pure delegation for official docs
- Custom references for plugin-specific features
Last Updated
Date: 2025-12-30
Model: claude-opus-4-5-20251101