User Configuration Management

MANDATORY: Invoke docs-management First

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

• INVOKE docs-management 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:

• 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:

• 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 /user-config <action> skill:

• Check storage usage -> Run /user-config storage

• 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 /user-config prune

• Nuclear cleanup (everything) -> Run /user-config prune --nuclear

• Backup configuration -> Run /user-config backup

• Restore from backup -> Run /user-config restore

• Reset (preserve MCP) -> Run /user-config reset

• See reset-workflow.md

• Search history -> Run /user-config history

• Manage plans -> Run /user-config plans

• Audit config health -> Run /user-config audit

• View session stats -> Run /user-config session-stats

• View MCP servers -> Run /user-config mcp

• 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:

• 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

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