User Configuration Management
Unified skill for managing Claude Code user configuration (~/.claude/ and ~/.claude.json). Consolidates all user-config operations into a single entry point with action-based routing.
Related Skill: Invoke the claude-ecosystem:user-config-management skill for the meta-level configuration authority, known-structure manifest, and docs-management delegation patterns.
Quick Decision Tree
What do you want to do?
| Intent | Action | Read-Only? |
|---|---|---|
| Check config health at a glance | status |
Yes |
| Deep health audit with drift detection | audit |
Yes (unless --fix) |
| See storage breakdown and recommendations | storage |
Yes |
| View session file counts and trends | session-stats |
Yes |
| Estimate API costs and token usage | costs |
Yes |
| Clean up old session files | cleanup-sessions |
Destructive |
| Clean up old agent transcripts | cleanup-agents |
Destructive |
| Clean up old debug files | cleanup-debug |
Destructive |
| Clean up old hook log files | cleanup-hook-logs |
Destructive |
| Comprehensive cleanup (all categories) | prune |
Destructive |
| Backup config to ~/.claude-backups/ | backup |
No (creates files) |
| Restore config from backup | restore |
No (overwrites files) |
| Reset Claude Code preserving MCP servers | reset |
Destructive |
| Nuclear plugin reset (cache+registry) | reset-plugins |
Destructive |
| View/edit ~/.claude.json global config | global |
Depends on mode |
| List/manage MCP server configurations | mcp |
Depends on mode |
| Search/analyze command history | history |
Yes (unless --clear) |
| List/view/archive plan files | plans |
Depends on mode |
| Browse file edit history across sessions | file-versions |
Yes (unless --restore) |
| Review compaction information loss | compaction-review |
Yes |
| Extract successful prompts from sessions | prompt-extract |
Yes |
| Search across session transcripts | transcript-search |
Yes |
| Generate session retrospective/postmortem | retrospective |
Yes |
Argument Routing Table
| Action | Arguments | Default Behavior | Reference |
|---|---|---|---|
audit |
[--fix] [--verbose] |
Full audit with summary report | audit.md |
backup |
[--include-history] [--include-sessions] |
Backup essential config only | backup.md |
cleanup-agents |
[days] [--dry-run] [--all-projects] |
Remove agent files >7 days, current project | cleanup-agents.md |
cleanup-debug |
[days] [--dry-run] |
Remove debug files >7 days | cleanup-debug.md |
cleanup-hook-logs |
[days] [--dry-run] |
Remove hook logs >30 days | cleanup-hook-logs.md |
cleanup-sessions |
[days] [--dry-run] [--all-projects] |
Remove session files >7 days, current project | cleanup-sessions.md |
compaction-review |
[session-id] [--current] [--compare] |
Review most recent compaction | compaction-review.md |
costs |
[--days N] [--project] [--breakdown] [--export FILE] |
Summary of recent costs (30 days) | costs.md |
file-versions |
<file-path> [--list] [--diff VER] [--restore VER] |
Show version summary for cwd | file-versions.md |
global |
[--view] [--edit SECTION] [--validate] |
View config summary | global.md |
history |
<search-term> [--days N] [--stats] [--export FILE] [--clear] |
Show recent history summary | history.md |
mcp |
[--list] [--export FILE] [--import FILE] [--add NAME] [--remove NAME] |
Show MCP server summary | mcp.md |
plans |
[plan-name] [--list] [--archive] [--cleanup N] |
List recent plans | plans.md |
prompt-extract |
[--successful-only] [--category CAT] [--days N] [--export FILE] |
Extract all prompts (30 days) | prompt-extract.md |
prune |
[days] [--dry-run] [--all-projects] [--include-debug] [--include-todos] [--nuclear] |
Comprehensive cleanup >7 days, current project | prune.md |
reset |
[--backup] [--restore] [--list-backups] |
Interactive reset wizard | reset.md |
reset-plugins |
[--dry-run] [--include-marketplaces] [--force] |
Clear all except marketplaces | reset-plugins.md |
restore |
[backup-name] [--list] [--mcp-only] [--dry-run] |
Interactive selection from backups | restore.md |
retrospective |
[session-id] [--current] [--days N] |
Analyze most recent session | retrospective.md |
session-stats |
[--all-projects] |
Stats for current project | session-stats.md |
status |
(none) | Unified config overview | status.md |
storage |
[--verbose] |
Storage analysis with recommendations | storage.md |
transcript-search |
<query> [--days N] [--project] [--regex] [--context N] |
Search all projects, all time | transcript-search.md |
Common Argument Patterns
These patterns are shared across multiple actions:
| Pattern | Used By | Description |
|---|---|---|
[days] |
cleanup-agents, cleanup-debug, cleanup-sessions, prune | Remove files older than N days (non-negative integer) |
--dry-run |
cleanup-*, prune, reset-plugins, restore | Preview without making changes |
--all-projects |
cleanup-agents, cleanup-sessions, prune | Apply to all projects (default: current only) |
--days N |
costs, history, prompt-extract, transcript-search | Limit time range for analysis |
--export FILE |
costs, history, mcp, prompt-extract | Export results to file |
--project |
costs, transcript-search | Limit to current project |
Safety Classification
Read-Only Actions (Always Safe)
audit (without --fix), compaction-review, costs, file-versions (without --restore), prompt-extract, retrospective, session-stats, status, storage, transcript-search
Destructive Actions (Require Confirmation)
All destructive actions MUST use AskUserQuestion before deletion. Never delete files without explicit user confirmation.
| Action | What Gets Deleted | Reversible? |
|---|---|---|
cleanup-agents |
Agent transcript files (agent-*.jsonl) | No |
cleanup-debug |
Debug transcript files | No |
cleanup-hook-logs |
Hook log .jsonl files | No |
cleanup-sessions |
Session .jsonl files | No |
prune |
Sessions + agents + statsig + plans + optionally debug/todos/locks | No |
reset |
User must manually delete ~/.claude/ (skill only prepares backup) | Partially (backup) |
reset-plugins |
Plugin cache, registry, enabledPlugins setting | Partially (reinstall) |
history --clear |
Command history entries | No |
Write Actions (Create/Modify Files)
| Action | What Gets Written |
|---|---|
backup |
Creates backup in ~/.claude-backups/ |
restore |
Overwrites config files from backup |
global --edit |
Modifies ~/.claude.json |
mcp --add/--remove/--import |
Modifies ~/.claude.json mcpServers |
plans --archive |
Moves plan files to archive/ subdirectory |
Protected Files (Never Deleted)
These files are NEVER touched by any cleanup action:
| File | Reason |
|---|---|
~/.claude/CLAUDE.md |
User instructions |
~/.claude/settings.json |
User settings |
~/.claude/settings.local.json |
Local settings |
~/.claude/.credentials.json |
OAuth tokens (never backup either) |
~/.claude/history.jsonl |
Command history (use history --clear explicitly) |
~/.claude/plugins/ |
Installed plugins (use /plugin uninstall) |
~/.claude/file-history/ |
Edit undo history (losing this removes /rewind capability) |
~/.claude/commands/ |
User commands |
~/.claude/skills/ |
User skills |
~/.claude/agents/ |
User agents |
~/.claude/hooks/ |
User hooks |
Cross-Platform Path Handling
All actions handle paths cross-platform:
Python: Use pathlib.Path.home() / ".claude" -- never hardcode OS-specific paths.
Bash: Use $HOME/.claude -- works on macOS, Linux, and Git Bash on Windows.
Project path encoding: pwd | sed 's/[\/:]/-/g' | sed 's/^-//'
Execution
Step 1: Parse Action
Extract the action from $ARGUMENTS:
ACTION = first non-flag argument (audit, backup, cleanup-agents, etc.)
REMAINING_ARGS = everything after the action
If no action provided or action is unrecognized, show the Quick Decision Tree above and ask user to specify an action.
Step 2: Load Reference
Load the detailed reference file for the action from references/{action}.md. The reference contains the complete operational instructions, workflows, code examples, and output formats.
Step 3: Execute
Follow the instructions in the reference file, passing REMAINING_ARGS as the action's arguments.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.