agent-session-kill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Brodeur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# 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), 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
+
+```bash
+npm install -g agent-session-kill
+```
+
+Or run without installing:
+
+```bash
+npx agent-session-kill
+```
+
+## Commands
+
+```bash
+agent-session-kill                         # interactive picker
+agentkill                                  # short alias
+agent-session-kill interactive             # explicit picker
+agent-session-kill scan --older-than 14d   # non-interactive inventory
+agent-session-kill scan --json             # machine-readable inventory
+agent-session-kill clean --dry-run         # non-interactive dry run
+agent-session-kill clean --apply           # apply non-interactive manifest
+```
+
+## 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`, or `temp`. 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 |
+| `--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.
+
+### 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/`
+
+## 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
+
+```bash
+npm install
+npm test
+```
+
+Run local smoke checks:
+
+```bash
+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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "agent-session-kill",
+  "version": "0.1.0",
+  "description": "NPKILL-style cleanup for Claude, Pi, and OMP agent session remnants.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Kyle Brodeur",
+  "homepage": "https://github.com/kylebrodeur/agent-session-kill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kylebrodeur/agent-session-kill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kylebrodeur/agent-session-kill/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "oh-my-pi",
+    "pi",
+    "sessions",
+    "cleanup",
+    "agent",
+    "tui",
+    "npkill"
+  ],
+  "bin": {
+    "agent-session-kill": "src/cli.js",
+    "agentkill": "src/cli.js"
+  },
+  "files": [
+    "src/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2"
+  },
+  "scripts": {
+    "test": "node --test",
+    "scan": "node src/cli.js scan",
+    "interactive": "node src/cli.js",
+    "clean:dry-run": "node src/cli.js clean --dry-run"
+  }
+}

package/src/age.js

@@ -0,0 +1,23 @@
+const UNIT_MS = {
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+};
+
+export function parseDurationMs(input) {
+  const match = /^(\d+)([mhd])$/.exec(input);
+  if (!match) {
+    throw new Error(`Invalid duration: ${input}`);
+  }
+
+  const value = Number(match[1]);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`Invalid duration: ${input}`);
+  }
+
+  return value * UNIT_MS[match[2]];
+}
+
+export function isOlderThan(mtimeMs, nowMs, olderThanMs) {
+  return nowMs - mtimeMs >= olderThanMs;
+}

package/src/apply.js

@@ -0,0 +1,115 @@
+import { access, cp, mkdir, rename, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+function normalizeManifest(input) {
+  if (Array.isArray(input)) {
+    return { entries: input, errors: [] };
+  }
+
+  return {
+    entries: Array.isArray(input?.entries) ? input.entries : [],
+    errors: Array.isArray(input?.errors) ? input.errors : [],
+  };
+}
+
+function defaultTrashDir(options) {
+  const homeDir = options?.homeDir ? path.resolve(options.homeDir) : os.homedir();
+  return path.join(homeDir, ".Trash", "agent-session-kill");
+}
+
+function trashPathFor(entry, trashDir) {
+  const absolutePath = path.resolve(entry.path);
+  const parsed = path.parse(absolutePath);
+  const rootSegment = parsed.root.replace(/[^a-zA-Z0-9._-]+/g, "_") || "root";
+  const relativePath = path.relative(parsed.root, absolutePath);
+
+  return path.join(trashDir, rootSegment, relativePath);
+}
+
+async function pathExists(candidatePath) {
+  try {
+    await access(candidatePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+async function uniqueTrashPathFor(entry, trashDir) {
+  const destination = trashPathFor(entry, trashDir);
+
+  if (!(await pathExists(destination))) {
+    return destination;
+  }
+
+  for (let suffix = 1; ; suffix += 1) {
+    const candidate = `${destination}.${suffix}`;
+
+    if (!(await pathExists(candidate))) {
+      return candidate;
+    }
+  }
+}
+
+function shouldSkip(entry) {
+  return entry.protected || entry.action === "keep" || entry.action === "delegate";
+}
+
+async function moveToTrash(entry, trashDir) {
+  const destination = await uniqueTrashPathFor(entry, trashDir);
+  await mkdir(path.dirname(destination), { recursive: true });
+
+  try {
+    await rename(entry.path, destination);
+  } catch (error) {
+    if (error?.code !== "EXDEV") {
+      throw error;
+    }
+
+    await cp(entry.path, destination, { recursive: true, force: false, errorOnExist: true });
+    await rm(entry.path, { recursive: true, force: false });
+  }
+}
+
+export async function applyManifest(input, options = {}) {
+  const manifest = normalizeManifest(input);
+  const result = {
+    deleted: 0,
+    trashed: 0,
+    skipped: 0,
+    errors: [...manifest.errors],
+  };
+  const trashDir = path.resolve(options.trashDir ?? defaultTrashDir(options));
+
+  for (const entry of manifest.entries) {
+    if (shouldSkip(entry)) {
+      result.skipped += 1;
+      continue;
+    }
+
+    try {
+      if (options.permanent || entry.action === "delete") {
+        await rm(entry.path, { recursive: true, force: false });
+        result.deleted += 1;
+        continue;
+      }
+
+      if (entry.action === "trash") {
+        await moveToTrash(entry, trashDir);
+        result.trashed += 1;
+        continue;
+      }
+
+      result.skipped += 1;
+    } catch (error) {
+      result.errors.push(`Failed to apply ${entry.action} to ${entry.path}: ${error.message}`);
+    }
+  }
+
+  return result;
+}

package/src/cli.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import os from "node:os";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { parseDurationMs } from "./age.js";
+import { runDelegateDryRuns } from "./delegates.js";
+import { formatJson, formatTable } from "./format.js";
+import { scanRemnants } from "./scanner.js";
+import { applyManifest } from "./apply.js";
+import { runInteractive } from "./interactive.js";
+const TOOLS = new Set(["claude", "pi", "omp", "temp"]);
+
+function usage() {
+  return buildProgram().helpInformation().trimEnd();
+}
+
+function collectTools(value, previous) {
+  const collected = [...previous];
+  for (const tool of value.split(",").map((part) => part.trim()).filter(Boolean)) {
+    if (!TOOLS.has(tool)) {
+      throw new Error(`Unknown tool: ${tool}`);
+    }
+    collected.push(tool);
+  }
+  return collected;
+}
+
+function buildDefaultOptions() {
+  return {
+    olderThan: "14d",
+    includeCache: false,
+    apply: false,
+    permanent: false,
+    json: false,
+    delegates: false,
+    homeDir: os.homedir(),
+    tempDir: os.tmpdir(),
+    dryRun: false,
+    tools: new Set(TOOLS),
+  };
+}
+
+function toCliArgs(command, options) {
+  return { command, options };
+}
+
+export function buildProgram() {
+  const program = new Command();
+  const selectCommand = (name) => () => {
+    program.selectedCommand = name;
+  };
+
+  program
+    .name("agent-session-kill")
+    .description("NPKILL-style cleanup for Claude, Pi, and OMP agent session remnants")
+    .exitOverride()
+    .allowExcessArguments(false)
+    .option("--older-than <duration>", "minimum age to consider stale", "14d")
+    .option("--tool <name>", "limit to claude, pi, omp, or temp; repeat or comma-separate", collectTools, [])
+    .option("--include-cache", "include cache roots in cleanup candidates", false)
+    .option("--json", "print JSON instead of a table", false)
+    .option("--delegates", "run delegate dry-run cleanup commands", false)
+    .option("--home <path>", "home directory to scan", os.homedir())
+    .option("--temp <path>", "temp directory to scan", os.tmpdir())
+    .option("--dry-run", "force dry-run mode", false)
+    .option("--permanent", "permanently delete instead of trash", false);
+
+  program.command("interactive", { isDefault: true }).description("open the interactive picker").action(selectCommand("interactive"));
+  program.command("scan").description("print a non-interactive inventory").action(selectCommand("scan"));
+  program
+    .command("clean")
+    .description("print cleanup manifest and optionally apply")
+    .option("--apply", "apply cleanup changes", false)
+    .action(selectCommand("clean"));
+
+  return program;
+}
+
+export function parseCliArgs(argv) {
+  const program = buildProgram();
+  const defaults = buildDefaultOptions();
+
+  program.configureOutput({
+    writeOut() {},
+    writeErr() {},
+    outputError() {},
+  });
+
+  try {
+    program.parse(argv, { from: "user" });
+  } catch (error) {
+    if (error?.code === "commander.helpDisplayed") {
+      return toCliArgs("interactive", { ...defaults, help: true });
+    }
+    throw new Error(error.message);
+  }
+
+  const parsed = program.opts();
+  const cleanCommand = program.commands.find((command) => command.name() === "clean");
+  const cleanOptions = cleanCommand ? cleanCommand.opts() : {};
+  const command = program.selectedCommand ?? "interactive";
+  const options = {
+    ...defaults,
+    olderThan: parsed.olderThan,
+    includeCache: parsed.includeCache,
+    apply: command === "clean" ? Boolean(cleanOptions.apply) : false,
+    permanent: parsed.permanent,
+    json: parsed.json,
+    delegates: parsed.delegates,
+    homeDir: parsed.home,
+    tempDir: parsed.temp,
+    dryRun: parsed.dryRun,
+    tools: parsed.tool.length > 0 ? new Set(parsed.tool) : new Set(TOOLS),
+  };
+
+  if (options.dryRun) {
+    options.apply = false;
+  }
+
+  return toCliArgs(command, options);
+}
+
+function writeDelegateOutput(stderr, result) {
+  if (result.stdout) {
+    stderr.write(result.stdout);
+  }
+  if (result.stderr) {
+    stderr.write(result.stderr);
+  }
+}
+
+export async function main(argv = process.argv.slice(2), io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }) {
+  const args = parseCliArgs(argv);
+  const { options } = args;
+  if (options.help) {
+    io.stdout.write(`${usage()}\n`);
+    return 0;
+  }
+
+  const stdin = io.stdin ?? process.stdin;
+  const stdout = io.stdout ?? process.stdout;
+
+  if (args.command === "interactive") {
+    if (!stdin.isTTY || !stdout.isTTY) {
+      io.stderr.write("Interactive mode requires a TTY. Use `scan`, `clean --dry-run`, or `--json` for scripts.\n");
+      return 1;
+    }
+
+    return await runInteractive({
+      homeDir: options.homeDir,
+      tempDir: options.tempDir,
+      nowMs: Date.now(),
+      olderThanMs: parseDurationMs(options.olderThan),
+      includeCache: options.includeCache,
+      apply: false,
+      permanent: options.permanent,
+      tools: options.tools,
+    }, {
+      stdin,
+      stdout,
+      stderr: io.stderr,
+    });
+  }
+
+  const results = await scanRemnants({
+    homeDir: options.homeDir,
+    tempDir: options.tempDir,
+    nowMs: Date.now(),
+    olderThanMs: parseDurationMs(options.olderThan),
+    includeCache: options.includeCache,
+    apply: options.apply,
+    permanent: options.permanent,
+    tools: options.tools,
+  });
+
+  if (args.command === "clean" && !options.apply) {
+    io.stderr.write("Dry run only; no files were changed. Re-run with --apply when ready to cleanup.\n");
+    io.stdout.write(options.json ? formatJson(results) : `${formatTable(results)}\n`);
+  } else if (args.command === "clean" && options.apply) {
+    io.stdout.write(options.json ? formatJson(results) : `${formatTable(results)}\n`);
+    const scanErrorCount = results.errors.length;
+    const applyResult = await applyManifest(results, {
+      homeDir: options.homeDir,
+      permanent: options.permanent,
+    });
+    const applyErrors = applyResult.errors.slice(scanErrorCount);
+    results.errors.push(...applyErrors);
+    io.stderr.write(`Applied: ${applyResult.deleted} deleted, ${applyResult.trashed} trashed, ${applyResult.skipped} skipped.\n`);
+    for (const error of applyErrors) {
+      io.stderr.write(`${error}\n`);
+    }
+  } else {
+    io.stdout.write(options.json ? formatJson(results) : `${formatTable(results)}\n`);
+  }
+
+  if (args.command === "clean" && options.delegates) {
+    for (const result of runDelegateDryRuns(options.homeDir)) {
+      writeDelegateOutput(io.stderr, result);
+    }
+  }
+
+  return results.errors.length > 0 ? 1 : 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().then((exitCode) => {
+    process.exitCode = exitCode;
+  }).catch((error) => {
+    process.stderr.write(`${error.message}\n${usage()}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/delegates.js

@@ -0,0 +1,31 @@
+import { spawnSync } from "node:child_process";
+
+function resolveHomeDir(input) {
+  return typeof input === "string" ? input : input?.homeDir;
+}
+
+export function buildDelegateDryRunCommands(homeDir) {
+  const resolvedHomeDir = resolveHomeDir(homeDir);
+  if (!resolvedHomeDir) {
+    throw new Error("homeDir is required");
+  }
+
+  return [
+    ["claude", "project", "purge", resolvedHomeDir, "--dry-run"],
+    ["omp", "worktree", "clear", "--dry-run"],
+  ];
+}
+
+export function runDelegateDryRuns(homeDir) {
+  return buildDelegateDryRunCommands(homeDir).map(([command, ...args]) => {
+    const result = spawnSync(command, args, { encoding: "utf8" });
+    return {
+      command: [command, ...args],
+      status: result.status,
+      signal: result.signal,
+      error: result.error,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+    };
+  });
+}