pi-session-cleanup

Interactive session cleanup extension for the Pi coding agent.

pi-session-cleanup provides a focused TUI command for batch-selecting historical sessions and deleting them safely with trash-first fallback and active session protection.

Features

• Interactive Session Cleanup — Browse, select, and delete sessions via an intuitive modal interface
• Scope Filtering — View only orphaned sessions or all historical sessions
• Batch Selection Controls — Multi-select with Space, select all with a, keyboard navigation
• Safe Delete Flow — Excludes the currently active session and uses trash-first deletion with unlink fallback
• Fresh Session Shortcut — /nix starts a fresh session and removes the previous session after confirmation
• Target Agent Handoff — /nix agent [name] starts a fresh session with persisted active-agent metadata
• Quit Cleanup Flow — /nix quit schedules current-session deletion during Pi's graceful shutdown event
• Improved Modal UX — Centered overlay with bordered layout, concise single-line legend, status summary, and automatic icon fallback

Installation

Local Extension Folder

Place this folder in one of Pi's auto-discovery paths:

~/.pi/agent/extensions/pi-session-cleanup     # Global default (when PI_CODING_AGENT_DIR is unset)
.pi/extensions/pi-session-cleanup               # Project-specific

Pi will auto-discover the extension on startup.

As NPM Package

pi install npm:pi-session-cleanup

Git Repository

pi install git:github.com/MasuRii/pi-session-cleanup

Usage

Commands

| Command | Arguments | Description | |---------|-----------|-------------| | /session-cleanup | — | Opens the session cleanup modal showing orphaned sessions only | | /session-cleanup current | — | Opens modal with sessions from the current directory | | /session-cleanup all | — | Opens modal showing all sessions | | /session-cleanup help | — | Displays usage help | | /nix | — | Starts a fresh session after confirmation and deletes the previous session | | /nix quit | — | Deletes the current session during graceful shutdown and quits Pi | | /nix agent | [name] | Starts a fresh session with a selected or explicitly named target agent | | /nix help | — | Displays /nix usage help |

Scopes:

• Default (no args) — Shows orphaned sessions (sessions without a matching directory)
• current — Shows sessions from the current working directory
• all — Shows all historical sessions across all directories

/nix Fresh Session Workflow

/nix is destructive by design and always asks for confirmation before deleting any session file.

• /nix starts a new session with the current agent and deletes the previous session only after ctx.newSession() succeeds.
• /nix agent [name] starts a new session with the selected target agent and writes an active_agent session entry so Pi can resume that agent context. Without [name], the command opens an interactive agent picker; with [name], it validates the name before continuing.
• /nix quit requires Pi builds that expose ctx.shutdown(). It schedules deletion of the current session and performs the delete from the session_shutdown event, so the session file is not removed until Pi has begun graceful shutdown.

Target agents are discovered from the nearest project agent folders (.omp/agents, .pi/agents, .claude/agents) plus user agent folders (~/.omp/agents, $PI_CODING_AGENT_DIR/agents, ~/.claude/agents). If pi-agent-router is installed with custom agentDiscovery paths, those paths are reused.

Modal Controls

When the session picker modal is open:

| Key | Action | |-----|--------| | ↑ / ↓ / j / k | Navigate up/down in the list | | PgUp / PgDn | Page up/down through sessions | | Home / End | Jump to first/last item | | Space | Toggle selection of current item | | a | Select all visible sessions | | r | Refresh the session list | | Enter | Confirm deletion of selected sessions | | Esc / q / Ctrl+C | Cancel and close modal |

Safety Guards

The extension includes multiple safety mechanisms:

1. Active Session Protection — The currently active session is never shown in the list and cannot be deleted
2. Trash-First Deletion — Sessions are moved to trash first; only falls back to permanent deletion if trash is unavailable
3. Confirmation Required — The modal requires explicit Enter keypress to proceed with deletion, and /nix commands require ctx.ui.confirm() approval
4. Graceful Quit Guard — /nix quit refuses to delete anything when the active Pi build does not expose ctx.shutdown()
5. Escapable — Esc or q immediately cancels without any changes

Configuration

Configuration is stored at:

Default global path: ~/.pi/agent/extensions/pi-session-cleanup/config.json
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-session-cleanup/config.json when PI_CODING_AGENT_DIR is set

A starter template is provided in config/config.example.json. On startup, the extension creates config.json with defaults if missing.

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Master on/off switch for the extension | | iconMode | "auto" \| "nerd" \| "fallback" | "auto" | Icon rendering mode for the modal UI (auto detects Nerd Font usage in supported terminals and safely falls back otherwise) |

Icon Mode Overrides

You can override icon mode without editing config:

• PI_SESSION_CLEANUP_ICON_MODE=nerd|fallback|auto
• PI_SESSION_CLEANUP_NERD_FONT=true|false (or PI_NERD_FONT=true|false)

auto now prefers Nerd icons when Nerd Font is actually configured (including Windows Terminal profile/default font checks) and falls back to safe icons when detection is unavailable or uncertain.

Development

npm run build    # Type-check with TypeScript
npm run lint     # Run linting (same as build)
npm run test     # Run test suite
npm run check    # Run full verification (build + test)
npm run package:dry-run

Publishing

The package metadata follows the same publish-ready shape used by established Pi extensions:

• entrypoint: index.ts
• package exports: . → ./index.ts
• Pi extension manifest: pi.extensions
• published files: source, README, changelog, license, and config template
• runtime config.json, tests, and build artifacts excluded from npm publication

Related Pi Extensions

• pi-hide-messages — Hide older TUI chat history while preserving full session context
• pi-context-injector — Inject compact project context into first-turn and compaction prompts
• pi-tool-display — Compact tool rendering and diff visualization
• pi-rtk-optimizer — RTK command rewriting and output compaction

Changelog

See CHANGELOG.md for version history.

License

MIT © MasuRii