Housekeeping
The harness you built for stash isn’t a set-it-and-forget-it artifact. It drifts - sessions accumulate, extensions break against new APIs, rules go stale, and skills stop matching the way you actually phrase things. A few minutes of periodic maintenance keeps it sharp instead of letting it rot into something you stop trusting.
Session cleanup
Section titled “Session cleanup”Every Pi session writes a JSONL transcript to ~/.pi/agent/sessions/, organized by working directory. Over weeks of daily use those files pile up into conversation history you may never reread. Review old sessions with pi -r (or /resume) and delete them from Pi’s session picker with Ctrl+D; that keeps branch and active-session state visible and uses the trash CLI when available. Avoid a blanket find ... -delete: age alone does not prove that a session is disposable.
Extension updates
Section titled “Extension updates”When Pi itself updates, re-test your extensions. The event API can shift between releases - a hook signature that worked last month may gain a parameter, rename a field, or change when it fires. After pi update (which updates Pi itself), run through your extensions once: fire the /stash command, trigger the damage-control hook, exercise the re-extract tool. Five minutes of manual testing now saves an afternoon of “why did my gate stop working” later.
Rule review
Section titled “Rule review”Every month, read SYSTEM.md and AGENTS.md top to bottom. Delete rules that no longer apply - the “always run pytest -x before committing” rule is dead weight once you’ve moved the project to uv run pytest. Add rules for mistakes you keep correcting by hand; if you’ve told Pi three times not to touch the migration files, that’s a rule, not a conversation. Rules that pay no rent are noise that dilutes the ones that do.
Skill pruning
Section titled “Skill pruning”If a skill hasn’t fired in a month, its description probably doesn’t match how you actually phrase the task. You don’t say “onboard a new saved-page adapter” - you say “add a parser for this site.” Revise the description to match your real language, or delete the skill if the procedure has changed enough that it would mislead. A skill that fires on the wrong prompt is worse than no skill at all.
Package updates
Section titled “Package updates”Run pi update --extensions periodically to pull the latest versions of installed packages, or pi update --all to update Pi and packages together. Check changelogs for breaking changes before updating anything that carries extensions - a package that registers tools or hooks can change their signatures between versions. Pin versions in your team’s install command (pi install npm:@foo/[email protected]) so a surprise upstream break doesn’t land on everyone’s machine at once.