// Periodic housekeeping and session lifecycle management. Use when performing cleanup, pruning, or session commands.
| name | maintenance |
| description | Periodic housekeeping and session lifecycle management. Use when performing cleanup, pruning, or session commands. |
| when_to_use | prune logs, clear state, purge cache, clean worktrees, archive traces, housekeeping, maintenance, cleanup, list sessions, inbox check, broadcast message, session lifecycle |
| allowed-tools | ["Read","Write","Edit","Bash","Glob","Grep"] |
| argument-hint | [--prune-logs|--clear-state|--purge-cache|--clean-worktrees|--archive-traces|--all|session list|session inbox|session broadcast] |
| user-invocable | true |
| model | sonnet |
Periodic housekeeping skill for Harness projects. Handles session log pruning, stale state file removal, plugin cache purging, and orphaned worktree cleanup.
| Subcommand | What It Does |
|---|---|
--prune-logs | Remove session log entries older than 90 days |
--clear-state | Remove stale files from .claude/state/ |
--purge-cache | Clear the plugin cache from ~/.claude/plugins/cache/ |
--clean-worktrees | Remove git worktrees with no associated branch |
--archive-traces | Move per-task trace files for completed tasks older than 30 days to .claude/memory/archive/traces/YYYY-MM/ |
--all | Run all of the above in sequence |
Run /maintenance when any of the following apply:
session-log.md exceeds 500 lines and the auto-cleanup hook has warned you.claude/state/ contains loop-active.json but no loop is running.claude/state/contracts/git worktree list shows entries for branches that have been deletedScans .claude/memory/session-log.md and removes entries older than 90 days.
Preserves entries from the current month and the previous month unconditionally.
Will delete: Session log H2 sections (## YYYY-MM) older than 90 days.
Will not touch: decisions.md, patterns.md, or any archive files.
Scans .claude/state/ and removes files that are safe to delete:
loop-active.json — only if no Breezing/harness-work loop is currently running*.sprint-contract.json) for tasks marked cc:Done in Plans.mdreview-result.json files older than 7 daysWill not touch: Active loop state, pending fix proposals, or the contracts/ directory itself.
Removes the plugin cache directory at ~/.claude/plugins/cache/. The cache is rebuilt
automatically on next plugin load. Use after a major Harness version upgrade if stale
cached files are causing unexpected behavior.
Runs bash "${CLAUDE_SKILL_DIR}/scripts/archive-traces.sh" to move per-task execution
traces (schema: trace.v1 — see .claude/memory/schemas/trace.v1.md) out of the active
.claude/state/traces/ directory and into dated archive buckets once they are no longer
actively consumed.
Eligibility (both must hold):
cc:Done in Plans.mdRETENTION_DAYS (default: 30)Target layout: .claude/memory/archive/traces/YYYY-MM/<task_id>.jsonl, bucketed by
each file's mtime so archives stay roughly chronological.
Environment knobs (rarely needed):
RETENTION_DAYS=N — override the 30-day defaultDRY_RUN=1 — print planned moves without executing themVERBOSE=1 — log skip reasons for every trace file consideredIdempotent: a second run finds nothing to do because archived files are no longer
in .claude/state/traces/. Safe to invoke from cron.
Destructive: prompts for confirmation before deleting.
Lists all git worktrees (git worktree list) and removes entries where the associated
branch no longer exists in the repository.
Safe: uses git worktree remove --force only on worktrees confirmed to have no live branch.
--purge-cache) require explicit confirmationSee ${CLAUDE_SKILL_DIR}/references/cleanup.md
for step-by-step execution procedures for each subcommand.
Consolidates session-related subcommands: listing, inbox checks, and broadcasting.
| User Input | Behavior |
|---|---|
session list | Show all active Claude Code sessions in the current project |
session inbox | Check for incoming messages from other sessions |
session broadcast "message" | Send a message to all active sessions |
session listShows all active Claude Code sessions in the current project.
Active Sessions
| Session ID | Status | Last Activity |
|------------|--------|---------------|
| abc123 | active | 2 min ago |
| def456 | idle | 15 min ago |
session inboxChecks for incoming messages from other sessions.
Session Inbox
| From | Time | Message |
|--------|---------|---------------------|
| abc123 | 5m ago | "Ready for review" |
session broadcast "message"Sends a message to all active sessions.
For memory optimization, session lifecycle details, and state transitions, see:
references/memory.mdreferences/session-control.mdreferences/memory-optimization.mdreferences/execution-flow.mdharness-plan archive — Archive completed phases from Plans.md (not the same as maintenance)memory — SSOT sync and memory managementharness-work — Implementation; run maintenance before long breezing sessionsOrchestrates the full powerball-harness plugin release with build, validation, version bump, CHANGELOG, tag, and GitHub Release. Use when releasing this plugin.
Plans and tracks tasks in .claude/harness/plans.json. Use when creating plans, adding tasks, updating markers, checking progress, or brainstorming an idea into tasks.
Runs iterate-until-pass loops with ralph-worker agents in a worktree. Use when running [ralph]-marked tasks or looping until verify passes.
Initializes and configures Harness in a project — CI, memory, duo workflow, Codex. Use when setting up a new project or adding Harness configuration.
Executes plans.json tasks — solo, parallel, or breezing team mode. Use when implementing tasks or running the work loop.
Manages SSOT memory — decisions.md, patterns.md, and cross-session learnings. Use when recording decisions, searching memory, or promoting learnings.