Stats
Actions
Tags
From claude-ecosystem
Manages Claude Code user configs (~/.claude/, ~/.claude.json): storage cleanup, backup/restore, reset with MCP preservation, history/plans/sessions/stats, health audits.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-ecosystem:user-config-managementThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **STOP - Before providing ANY response about Claude Code user configuration:**
STOP - Before providing ANY response about Claude Code user configuration:
- INVOKE
docs-managementskill 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.
Before responding, verify:
If ANY checkbox is unchecked, STOP and complete the missing steps.
Central authority for managing Claude Code's user configuration directories. This skill provides:
Architecture: Hybrid delegation - official docs via docs-management, custom workflows via skill references.
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:
Use these keywords when querying docs-management skill:
| 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" |
| Topic | Keywords |
|---|---|
| Retention Setting | "cleanupPeriodDays", "session retention", "auto-cleanup" |
| Session Cleanup | "sessions", "project sessions", "session files" |
| Debug Logs | "debug", "debug transcripts", "debugging" |
| Topic | Keywords |
|---|---|
| Storage Structure | "~/.claude", "storage directory", "claude folder" |
| Projects Directory | "projects", "project sessions", "session storage" |
| Plugins Directory | "plugins", "plugin cache", "installed plugins" |
What do you want to do?
All actions are invoked via the consolidated /user-config <action> skill:
/user-config storage/user-config cleanup-sessions/user-config cleanup-agents/user-config cleanup-debug/user-config prune/user-config prune --nuclear/user-config backup/user-config restore/user-config reset - See reset-workflow.md/user-config history/user-config plans/user-config audit/user-config session-stats/user-config mcp/user-config reset-plugins| 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 |
| 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.
All actions consolidated under the /user-config <action> skill:
| 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) |
| 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 |
| 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) |
| 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 |
| 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 |
These workflows are NOT in official documentation - they are custom features:
For users who want a fresh start but need to preserve MCP server configs.
Full guide: references/reset-workflow.md
Quick summary:
For full configuration backup and restore.
Full guide: references/backup-restore.md
Backup location: ~/.claude-backups/backup-YYYY-MM-DD-HHmmss/
Detect when Claude Code updates change the config structure.
Full guide: references/known-structure.yaml
Mechanism: Compare actual ~/.claude/ against known structure manifest.
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"
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
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
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/cleanupPeriodDays in settings.json:
Query docs-management: "cleanupPeriodDays", "session retention"
Note: For official retention settings (like
cleanupPeriodDays), querydocs-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) |
| 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 |
This skill provides validation criteria used by the user-config-auditor agent.
| 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 |
The user-config-auditor agent performs formal audits:
Custom References (skill-owned):
Official Documentation (via docs-management):
Date: 2025-12-30 Model: claude-opus-4-5-20251101
npx claudepluginhub melodic-software/claude-code-plugins --plugin claude-ecosystemManages Claude Code user config (~/.claude/) with actions for audit/status, backup/restore, cleanup sessions/agents/debug/logs, costs/storage/session-stats, history/transcript-search, plugin-reset, and more.
Audits Claude Code configurations for best practices in skills, instructions, MCP servers, hooks, plugins, security, over-engineering, and context efficiency via file scans and focused checks. Invoke with /claudit [focus-area].
Reference every Claude Code setting option from permissions, hooks, and sandbox to models, status line, and MCP servers. Use for config customization and troubleshooting.