claude-housekeeping

Housekeeping

User-invoked drift detector + cleanup helper for the user's Claude Code artifacts.

Operating principle (hard rule — never relax)

1. User-invoked. Nothing schedules this skill automatically on Stop/SessionStart/Notification. The one exception: after the user explicitly approves and the model applies recommendations, the skill self-schedules a follow-up run 24 hours out (see Post-apply scheduling). That schedule is a direct result of user-approved work, not background automation.
2. Scans and reports. Produces a numbered recommendation list. Does not apply any change on its own.
3. Only acts on items the user explicitly approves — "do #1, #3" or "all" or "skip". The user can also say "modify #3 to do X instead" and the skill respects that.
4. After approved actions, report what was done + offer a follow-up scan to confirm the items cleared.

If invoked via /schedule for an unattended cron run, the skill MUST stop after producing the report — surfaces a notification for the user to review on their next prompt. No unattended execution of recommendations, ever.

Invocation modes

/claude-housekeeping                           # interactive: scan, show report, prompt for approvals, apply
/claude-housekeeping --report-only             # scan only, write report file, no prompts
/claude-housekeeping --report-only --quiet     # report only, no notification if zero recommendations
/claude-housekeeping --diff before=X after=Y   # generate delta report comparing two prior snapshots
/claude-housekeeping --threshold-days=N        # tune the "orphan plans older than N days" cutoff (default 1)
/claude-housekeeping --include-dormant         # scan dormant projects too (default: skip)
/claude-housekeeping --emit-commands=3,7,12    # output only the specified recommendations' command blocks
/claude-housekeeping --report-only --auto-reschedule  # report only + reschedule next run 24 h out (used by self-scheduled runs)

How to invoke from the model

When the user types /claude-housekeeping (with any args), run the scanner directly — there is no wrapper script:

python3 $HOME/.claude/skills/claude-housekeeping/scanner.py --report-only [args]

The scanner writes a markdown report to ~/.claude/housekeeping/reports/YYYY-MM-DD-HHMM.md and prints the path on stdout. The model should Read the report file and surface a summary + numbered recommendations to the user.

Interactive flow (after reading the report):

1. Surface the recommendation list to the user.
2. Wait for approval input ("do 1,3,7" / "all" / "skip" / "1-5" / "modify 3").
3. Execute approved recommendations one-by-one using the Executable command list section of the report (each block has backup → pre-check → action → post-check).
4. Report the result of each.
5. Post-apply scheduling — after all approved actions are complete, schedule the next run (see Post-apply scheduling).

Plan mode compatibility: --report-only is safe to run in plan mode — it only writes an audit-output file under ~/.claude/housekeeping/reports/, not actual state changes. Defer applying recommendations until plan mode exits.

Post-apply scheduling

After the user approves and the model applies one or more recommendations, the model must create or reset a 24-hour one-shot follow-up run. This is the only scheduling that happens; it does not fire on --report-only runs that were not triggered by the scheduler itself.

State file: ~/.claude/housekeeping/scheduled-run.json

{ "job_id": "<CronCreate id>", "scheduled_for": "<ISO UTC>", "created_at": "<ISO UTC>" }

Steps (run after step 4 of the interactive flow)

1. Read state file. If ~/.claude/housekeeping/scheduled-run.json exists, extract job_id.
2. Cancel old job. Call CronDelete(id) — ignore errors (job may have already fired and auto-deleted).
3. Compute target time. Run via Bash:

   date -d '+24 hours' '+%M %H %d %m *'
   

   This produces the local-time cron expression (e.g. "27 14 22 5 *").
4. Create new job. Call CronCreate with:
   • cron: the value from step 3
   • recurring: false (one-shot; auto-deletes after firing)
   • durable: true (persists across session restarts)
   • prompt: "/claude-housekeeping --report-only --auto-reschedule"
5. Save state. Write the returned job ID and timestamps to ~/.claude/housekeeping/scheduled-run.json:

   SCHED_FOR=$(date -d '+24 hours' -u +%Y-%m-%dT%H:%M:%SZ)
   NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
   printf '{"job_id":"%s","scheduled_for":"%s","created_at":"%s"}\n' \
     "$NEW_JOB_ID" "$SCHED_FOR" "$NOW" \
     > ~/.claude/housekeeping/scheduled-run.json
   

6. Inform the user. One line: "Next housekeeping run scheduled for <human-readable local time>." (e.g. "Thu 22 May 14:27").

--auto-reschedule flow (self-scheduled unattended run)

When invoked as /claude-housekeeping --report-only --auto-reschedule (i.e., fired by the scheduler):

1. Run the scanner and write the report as normal.
2. Surface the report summary via notification (even if zero recommendations — confirms the run fired).
3. The one-shot job auto-deleted on firing, so skip step 2 (CronDelete) above. Run steps 3–6 to schedule the next 24-hour run.
4. Never apply recommendations — --report-only takes precedence. The user reviews the report on their next prompt.

What it scans for

1. Orphan plans in ~/.claude/plans/*.md older than --threshold-days (default 1).

   • Skip screenshots/.
   • Recommend: route to a likely project's docs/plans/ (content-sniffing for project signals), or delete if trivially-small / shipped-duplicate.

2. Duplicate memories — same-filename feedback_*.md across ≥3 projects.

   • Recommend: promote to ~/.claude/memory/<name>.md (create global index if absent), delete per-project copies. Show content diff if copies aren't identical.

3. Duplicate commands — *.md in ~/.claude/commands/ that also appear in */.claude/commands/.

   • Recommend: delete the per-project copy. Excludes .worktrees/ paths.

4. Config drift — per-project settings.json hook lines that are now covered globally.

   • Recommend: remove duplicate lines (or remove whole settings.json if empty after).

5. Missing global hooks — sanity check ~/.claude/settings.json matches the expected baseline.

6. Uncommitted/untracked .claude/ changes — modified or untracked artifacts (skills, commands, memory, hooks, settings.json, CLAUDE.md) in either the homedir repo (covers global ~/.claude/) or any project repo (covers ~/SRC/<project>/.claude/). Skips ephemeral subdirs (sessions, cache, daemon, telemetry, backups, etc.) and .bak/~/.tmp/.swp files. Catches in-flight skill development, untracked auto-memory files, and config edits that never got committed.

7. Missing global memory cascade — Claude's auto-memory loader is cwd-siloed: only ~/.claude/projects/{slug}/memory/ loads, so the global memories at ~/.claude/projects/-home-will/memory/ never reach project sessions. This scan detects, per active project, global memory files not yet symlinked into <project>/.claude/memory/. Also catches stale symlinks (target deleted) and real-file collisions (project has a same-named local memory).

   • Recommend: create symlinks via the apply-cascade.py helper, which also merges the global MEMORY.md sections into the project's MEMORY.md between auto-managed markers and updates .gitignore so the symlinks don't get committed into the project repo. Collisions are surfaced but never overwritten.

Report file format

Reports land at ~/.claude/housekeeping/reports/YYYY-MM-DD-HHMM[-before|-after|-diff].md.

Structure (in order):

# Housekeeping report — YYYY-MM-DD HH:MM

## Summary

<sentence: N recommendations across K categories>

## Recommendations

### 1. <category> — <one-line title>
<details>

### 2. ...
[etc.]

## Executable command list

<prelude>

# Recommendation #1
<backup + pre-check + action + post-check + rollback hint>

# Recommendation #2
...

<end summary>

## State visualization

<Unicode-box table — one row per project, columns for artifact types>

## Mermaid graphs

<dependency map, recent migrations (if any), recommendation category pie>

For --diff mode, the structure differs (see "Diff mode" below).

Diff mode (--diff before=X after=Y)

Generates a comparison report:

# Housekeeping diff — <before-timestamp> → <after-timestamp>

## Summary

- Resolved: N recommendations
- New: M recommendations (regressions or new drift)
- Unchanged: K recommendations (deferred / dormant)
- Net change: -<N-M>

## Resolved recommendations
<list — these got fixed>

## New recommendations
<list — investigate before declaring success>

## Unchanged recommendations
<list — skipped/dormant>

## State table diff
<side-by-side — what changed per project>

<details>
<summary>Full before report</summary>
<embedded report #1>
</details>

<details>
<summary>Full after report</summary>
<embedded report #2>
</details>

Safety contract for recommendation execution

Every recommendation's command block follows this pattern:

1. Backup — cp -a originals into /tmp/housekeeping-backup-<timestamp>/recommendation-N/.
2. Pre-check — sha256sum / diff to confirm the file is in the expected pre-state.
3. Action — the actual change (mv, rm, etc.).
4. Post-check — verify the new state matches expectations.
5. Rollback hint — exact reverse commands in a comment.

Hash-pinning: the command block embeds sha256s of source files in pre-checks, so a deferred apply (hours later, state shifted) fails fast rather than overwriting unexpected state.

Canonical project list

The skill reads ~/.claude/projects.json for the list of projects to scan. Each entry has name, path, status (active/dormant), optional notes. Dormants skipped by default; --include-dormant includes them.

Related plan

This skill was specified in ~/SRC/docs/plans/2026-05-19-globalize-hooks-housekeeping-skill.md (Part B). Refer there for design rationale.