User Configuration Management

MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about Claude Code user configuration:

1. INVOKE docs-management skill for official documentation
2. QUERY for the user's specific topic
3. 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:

• Did I invoke docs-management skill for official docs?
• Did I check this skill's references for custom workflows?
• Is my response based on official docs (settings, MCP) + skill references (reset, backup)?

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:

1. Keyword registry for efficient docs-management queries
2. Custom workflows not covered by official docs (reset, backup/restore, drift detection)
3. Command inventory linking to existing cleanup commands
4. 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 /user-config <action> skill:

1. Check storage usage -> Run /user-config storage
2. Clean up sessions -> Run /user-config cleanup-sessions
3. Clean up agents -> Run /user-config cleanup-agents
4. Clean up debug logs -> Run /user-config cleanup-debug
5. Comprehensive cleanup -> Run /user-config prune
6. Nuclear cleanup (everything) -> Run /user-config prune --nuclear
7. Backup configuration -> Run /user-config backup
8. Restore from backup -> Run /user-config restore
9. Reset (preserve MCP) -> Run /user-config reset - See reset-workflow.md
10. Search history -> Run /user-config history
11. Manage plans -> Run /user-config plans
12. Audit config health -> Run /user-config audit
13. View session stats -> Run /user-config session-stats
14. View MCP servers -> Run /user-config mcp
15. Reset plugins (nuclear) -> Run /user-config reset-plugins

Directory Structure Reference

~/.claude/ Directory (13 Concepts)

Directory/File	Purpose	Cleanup Safe	Action
projects/	Session files per project	Yes (old files)	/user-config cleanup-sessions
debug/	Debug transcripts	Yes (old files)	/user-config cleanup-debug
plugins/	Installed plugin cache	No (use /plugin)	/plugin uninstall
file-history/	Edit undo history	No (loses undo)	Never auto-clean
plans/	Saved execution plans	Yes (old files)	/user-config plans
shell-snapshots/	Shell state captures	Yes	/user-config prune
todos/	Todo list state	Yes (old files)	/user-config prune
statsig/	Feature flag cache	Always safe	/user-config prune
ide/	IDE lock files	Yes (stale)	/user-config audit
session-env/	Session environment	Yes	/user-config prune
settings.json	User settings	Never	Manual only
history.jsonl	Command history	Usually keep	/user-config history
.credentials.json	OAuth tokens	Never backup	Manual only

~/ Root Files (3 Concepts)

File	Purpose	Backup Priority
.claude.json	Global config (mcpServers, OAuth, flags)	Critical (mcpServers)
CLAUDE.md	User-level instructions	High
.claudeignore	User-level ignore patterns	Medium

IMPORTANT: There is NO ~/.mcp.json file. User-scope MCP servers go in ~/.claude.json under the mcpServers field.

Action Inventory

All actions consolidated under the /user-config <action> 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)
/user-config prune	Comprehensive cleanup (--nuclear)

Analysis Actions

Action	Purpose
/user-config status	Unified overview of all config
/user-config storage	Storage analysis
/user-config session-stats	Session statistics
/user-config costs	API cost estimation
/user-config audit	Structure drift detection

Backup/Restore Actions

Action	Purpose
/user-config backup	Full backup to ~/.claude-backups/
/user-config restore	Restore from backup
/user-config reset	Backup MCP -> Wipe -> Restore workflow
/user-config reset-plugins	Complete plugin reset (cache + registry + settings)

Configuration Actions

Action	Purpose
/user-config global	View/edit ~/.claude.json safely
/user-config mcp	List/export MCP server configs
/user-config history	Search/export command history
/user-config plans	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:

1. Backup: Extract mcpServers from ~/.claude.json
2. Backup: Copy settings.json (optional)
3. User wipes ~/.claude/ and ~/.claude.json
4. User relaunches Claude Code (creates fresh config)
5. 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

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

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

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:

from pathlib import Path
claude_dir = Path.home() / ".claude"
claude_json = Path.home() / ".claude.json"
backup_dir = Path.home() / ".claude-backups"

Bash:

CLAUDE_DIR="$HOME/.claude"
CLAUDE_JSON="$HOME/.claude.json"
BACKUP_DIR="$HOME/.claude-backups"

Never hardcode:

• C:\Users\USERNAME\.claude\
• /Users/USERNAME/.claude/
• /home/USERNAME/.claude/

Retention Settings

Official Setting (via docs-management)

cleanupPeriodDays in settings.json:

• 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 cleanupPeriodDays), 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 /user-config storage then cleanup actions
Lost MCP servers after reset	Use /user-config reset workflow (backs up first)
Unknown files in ~/.claude	Run /user-config audit for drift detection
Can't find old session	Use /user-config history to search
Need to restore config	Use /user-config restore from backup
"Another Claude process running"	/user-config prune --nuclear clears stale locks

Auditing Configuration

This skill provides validation criteria used by the user-config-auditor 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 user-config-auditor 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