maintenance
Periodic housekeeping and session lifecycle management. Use when performing cleanup, pruning, or session commands.
SKILL.mdharness/skills/maintenance/SKILL.md
GitHubMaintenance
Periodic housekeeping skill for Harness projects. Handles stale state file removal, plugin cache purging, and orphaned worktree cleanup.
Quick Reference
| Subcommand | What It Does |
|---|---|
--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 |
--all |
Run all of the above in sequence |
When to Use
Run /maintenance when any of the following apply:
.claude/state/containsloop-active.jsonbut no loop is running- Old sprint contracts from completed phases are cluttering
.claude/state/contracts/ git worktree listshows entries for branches that have been deleted- The plugin cache has grown stale after a Harness version upgrade
Operations
--clear-state
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 files (
*.sprint-contract.json) for tasks markedcc:Donein Plans.md - Stale
review-result.jsonfiles older than 7 days
Will not touch: Active loop state, pending fix proposals, or the contracts/ directory itself.
--purge-cache
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.
--clean-worktrees
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.
Safety Guarantees
- All operations print a dry-run summary before making changes
- Destructive operations (
--purge-cache) require explicit confirmation - Operations never touch files outside their defined scope
- The main working tree is never modified
Execution Details
See ${CLAUDE_SKILL_DIR}/references/cleanup.md
for step-by-step execution procedures for each subcommand.
Session Lifecycle
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 list
Shows 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 inbox
Checks 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:
Related Skills
harness-plan archive— Archive completed phases from Plans.md (not the same as maintenance)harness-work— Implementation; run maintenance before long breezing sessions