Claude
Skills
Sign in
Back

claude-cleanup

Included with Lifetime
$97 forever

Use when the user says "clean up claude.json", "remove stale projects", "prune old project entries", "clean up my Claude project history", or wants to remove project entries from ~/.claude.json whose directories no longer exist on disk.

General

What this skill does


# Claude Cleanup

Remove project entries from `~/.claude.json` whose directories no longer exist
on disk.

## When NOT to Use

- The user wants to delete *all* project history (this only removes entries whose directories are missing)
- The user wants to manually edit `~/.claude.json` for other reasons

## Rules

1. **Always run Phase 1 first.** Never skip straight to cleanup.
2. **Never delete entries without the user seeing the stale list.**
3. **Stop after Phase 1 if nothing is stale.** Do not ask about /insights.

## Setup: Resolve the script path

The system-reminder at load time contains: `Base directory for this skill: <path>`

Use that value to derive the plugin root:

```bash
# SKILL_BASE = the base directory shown in the system context
PLUGIN_ROOT="${SKILL_BASE%/skills/claude-cleanup}"
SCRIPT="$PLUGIN_ROOT/scripts/cleanup.sh"
```

Use `$SCRIPT` for all bash invocations below.

## Phase 1 — Scan

Run:

```bash
bash "$SCRIPT" --dry-run
```

- If output starts with "Nothing to clean", report this to the user and **stop**.
- Otherwise display the stale paths listed in the output.

## Phase 2 — Insights prompt

Ask the user with `AskUserQuestion`:

- **Question:** "Run /insights before cleaning up?"
- **Options:** Yes, No

## Phase 3 — Insights (conditional)

If the user chose **Yes**, invoke the `/insights` built-in using the `Skill`
tool with skill name `insights`. Wait for it to complete before proceeding.

## Phase 4 — Clean

Run:

```bash
bash "$SCRIPT" --clean
```

Report the output to the user: number of entries removed and backup location
(`~/.claude.json.bak`).

Related in General