agent-session-kill

Agent Session Kill

NPKILL-style cleanup for AI coding-agent session remnants.

agent-session-kill scans local Claude Code, Pi/pi-mono, Oh My Pi (OMP), GitHub Copilot Chat, and subagent temp storage, then lets you review and delete stale session artifacts from an interactive terminal UI.

Why

Agent harnesses save transcripts, tool outputs, task state, shell snapshots, logs, temp subagent runs, and per-project session files. Those files are useful while work is active, but they pile up.

Agent Session Kill gives you a single cleanup surface with conservative defaults:

• interactive picker by default, inspired by npkill
• dry-run and JSON modes for scripts
• protected paths for auth, settings, plugins, skills, memory, and model config
• cache cleanup is opt-in
• trash-first deletion by default
• explicit confirmation before interactive deletion

Install

npm install -g agent-session-kill

Or run without installing:

npx agent-session-kill

Commands

# Interactive picker (default)
agent-session-kill
agentkill                                           # short alias

# Limit to specific tools
agent-session-kill --tool copilot                   # Copilot Chat only
agent-session-kill --tool claude,omp                # multiple tools

# Orphan detection — OMP sessions for deleted projects trashed regardless of age
agent-session-kill --workspace ~/workspace

# Include cache files as cleanup candidates
agent-session-kill --include-cache

# Non-interactive inventory
agent-session-kill scan                             # table output
agent-session-kill scan --json                      # machine-readable
agent-session-kill scan --tool copilot --json       # scoped to one tool
agent-session-kill scan --older-than 7d             # tighter age threshold

# Dry-run manifest (print what would be deleted)
agent-session-kill clean --dry-run
agent-session-kill clean --dry-run --include-cache  # include cache in preview

# Apply cleanup
agent-session-kill clean --apply                    # trash (recoverable)
agent-session-kill clean --apply --permanent        # permanent delete

# Delegate cleanup to native tools (claude project purge, omp worktree clear)
agent-session-kill clean --dry-run --delegates

Interactive controls

Key	Action
↑ / k	Move up
↓ / j	Move down
PgUp / Ctrl+u	Page up
PgDn / Ctrl+d	Page down
Home / End	Jump to first/last row
Space	Toggle current selectable row
a	Toggle all selectable visible rows
d / Del	Delete selected rows after confirmation
r	Rescan
q / Esc	Quit without changes

Rows that are protected or kept are visible but not selectable.

Options

Option	Description	Default
--older-than <duration>	Minimum age for stale artifacts. Supports m, h, d.	14d
--tool <name>	Limit to claude, pi, omp, temp, or copilot. Repeat or comma-separate.	all
--include-cache	Include cache roots as cleanup candidates.	off
--json	Print JSON. Always non-interactive.	off
--delegates	Run delegated dry-runs (claude project purge, omp worktree clear).	off
--home <path>	Home directory to scan.	current user home
--temp <path>	Temp directory to scan.	OS temp dir
--workspace <path>	Workspace directory; OMP sessions for projects no longer on disk are flagged as orphaned and trashed regardless of age (scans 2 levels deep).	off
--dry-run	Force dry-run mode.	off
--apply	Apply cleanup in clean mode.	off
--permanent	Permanently delete instead of trashing.	off

What it scans

Claude Code

• ~/.claude/session-env/
• ~/.claude/tasks/
• ~/.claude/plans/
• ~/.claude/debug/
• ~/.claude/paste-cache/
• ~/.claude/shell-snapshots/
• ~/.claude/backups/
• ~/.claude/cache/ only when --include-cache is set

Claude project transcripts under ~/.claude/projects/ are protected from direct deletion. Use --delegates to preview the official claude project purge path.

Pi / pi-mono

• ~/.pi/agent/sessions/
• ~/.pi/agent/tmp/
• ~/.pi/session-search/index/
• ~/.pi/agent/cache/ only when --include-cache is set

OMP / Oh My Pi

• ~/.omp/agent/sessions/
• ~/.omp/agent/terminal-sessions/
• ~/.omp/logs/
• ~/.omp/agent/blobs/
• ~/.omp/agent/cache/ only when --include-cache is set
• ~/.omp/cache/ only when --include-cache is set

OMP worktrees are handled through omp worktree clear --dry-run when delegates are enabled.

GitHub Copilot Chat (VS Code)

• ask-agent/, plan-agent/, explore-agent/, logContextRecordings/, memory-tool/
• copilot.cli.oldGlobalSessions.json
• copilot.cli.workspaceSessions.*.json
• commandEmbeddings.json, settingEmbeddings.json, toolEmbeddingsCache.bin, copilot-cli-images/ only when --include-cache is set

macOS path: ~/Library/Application Support/Code/User/globalStorage/github.copilot-chat Linux path: ~/.config/Code/User/globalStorage/github.copilot-chat

Subagent temp runs

• <temp>/pi-subagents-*/chain-runs/
• <temp>/pi-subagents-*/async-subagent-runs/

Protected paths

Agent Session Kill never deletes known auth, settings, plugin, skill, memory, model, or MCP configuration paths, even when broad options are used.

Examples:

• ~/.claude.json
• ~/.claude/settings.json
• ~/.claude/plugins/
• ~/.claude/skills/
• ~/.claude/agents/
• ~/.claude/commands/
• ~/.claude/projects/
• ~/.pi/agent/auth.json
• ~/.pi/agent/settings.json
• ~/.pi/agent/models.json
• ~/.pi/agent/mcp*.json
• ~/.pi/agent/npm/
• ~/.omp/agent/config.yml
• ~/.omp/agent/managed-skills/
• ~/.omp/agent/memories/
• ~/.../github.copilot-chat/api.json
• ~/.../github.copilot-chat/mcpServers.json
• ~/.../github.copilot-chat/debugCommand

Safety model

• Interactive mode requires a TTY.
• Script output uses scan, clean --dry-run, or --json.
• clean is dry-run unless --apply is present.
• --dry-run overrides --apply if both are supplied.
• Cache cleanup requires --include-cache.
• Permanent deletion requires --permanent.
• Interactive deletion requires typing delete after selected paths are printed.

Development

npm install
npm test

Run local smoke checks:

node src/cli.js scan --tool claude
node src/cli.js clean --dry-run --tool claude
node src/cli.js scan --json --tool claude

License

MIT