From claude-ecosystem
Manages 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.
npx claudepluginhub melodic-software/claude-code-plugins --plugin claude-ecosystemThis skill is limited to using the following tools:
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.
references/audit.mdreferences/backup.mdreferences/cleanup-agents.mdreferences/cleanup-debug.mdreferences/cleanup-hook-logs.mdreferences/cleanup-sessions.mdreferences/compaction-review.mdreferences/costs.mdreferences/file-versions.mdreferences/global.mdreferences/history.mdreferences/mcp.mdreferences/plans.mdreferences/prompt-extract.mdreferences/prune.mdreferences/reset-plugins.mdreferences/reset.mdreferences/restore.mdreferences/retrospective.mdreferences/session-stats.mdManages Claude Code user configs (~/.claude/, ~/.claude.json): storage cleanup, backup/restore, reset with MCP preservation, history/plans/sessions/stats, health audits.
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].
Provides structured tutorials, templates, Mermaid diagrams, and learning path for Claude Code features: slash commands, memory, skills, subagents, MCP, hooks, plugins, checkpoints, CLI.
Share bugs, ideas, or general feedback.
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.
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 |
| 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 |
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 |
audit (without --fix), compaction-review, costs, file-versions (without --restore), prompt-extract, retrospective, session-stats, status, storage, transcript-search
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 |
| 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 |
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 |
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/^-//'
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.
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.
Follow the instructions in the reference file, passing REMAINING_ARGS as the action's arguments.