agent-session-cleaner

agent-session-cleaner is a terminal dashboard for inspecting and safely cleaning local sessions created by Codex, Claude Code, and OpenCode. It is built with OpenTUI and React, and runs on Node.js.

It is especially useful when coding agents have accumulated stale sessions for deleted repositories, temporary directories, or Git worktrees.

Features

• Browse sessions by provider, then group them by project, repository, or folder.
• Filter all levels by All, Orphaned, or Archived.
• Order providers, groups, and sessions by updated time, known size, or name.
• Inspect paths, timestamps, status, archive state, and known transcript size.
• Review and remove one session, one group, or all safely removable orphaned sessions.
• Use keyboard, Emacs/Vim-style navigation keys, or the mouse.
• Preview every native delete command in a confirmation modal.
• Explore the complete UI with built-in demo data that never touches agent storage.

Requirements

• Node.js 26 or newer. OpenTUI uses node:ffi to call its native terminal renderer; it is unrelated to session discovery or deletion. The packaged CLI and npm scripts enable --experimental-ffi automatically.
• One or more supported agent CLIs available on PATH:
  • codex
  • claude
  • opencode

Missing or unavailable providers are reported in the UI without preventing the others from loading.

Install

npm i -g agent-session-cleaner

Usage

agent-session-cleaner [options]
asc [options]

Options:
  --demo          Use safe built-in sample data
  -h, --help      Show CLI help

Normal mode reads local session metadata from the installed agents. Demo mode loads 15 representative mock sessions across all three providers and never reads or modifies agent storage.

Interface

The dashboard opens at the provider level. Press Enter or the right arrow to browse a provider's groups, then open a group to inspect its individual sessions.

The centered header contains three selectors:

Show(s) All Orphaned Archived · Group(g) Project Repository Folder · Order(o) Updated Size Name

Group is shown after entering a provider. Project is hidden when it would be identical to Folder. Updated and Size sort descending, Name sorts ascending, and unknown sizes appear last.

Keyboard

| Key | Action | | ------------------------ | --------------------------------------- | | Arrow keys | Move, open, or go back | | Enter | Open provider or group | | j / k, C-n / C-p | Move selection | | l, C-f | Open provider or group | | h, C-b | Go back | | C-a / C-e | Select first / last item | | C-v / M-v | Page down / up | | C-g | Cancel or go back | | s | Cycle All / Orphaned / Archived | | g | Cycle Project / Repository / Folder | | o | Cycle Updated / Size / Name | | Tab / Shift-Tab | Cycle grouping forward / backward | | 1 / 2 / 3 | Select Project / Repository / Folder | | / | Search sessions in the current provider | | r | Refresh | | Del or Backspace | Review removal for the current context | | ? | Open or close Help | | q | Quit |

Mouse

• Hover a visible row to select it and update Details.
• Click a row once to open it.
• Use the wheel to scroll without recentering the list around the pointer.
• Click header selectors to filter, group, or order.
• Contextual Back, Refresh, Review, and Delete buttons appear at the bottom of Details after mouse input. They disappear again after keyboard input.

Provider support

| Provider | Session discovery | Size | Single delete | Group delete | | ----------- | ----------------------------------------------- | ------------------------------------------------------ | ------------------------------ | ----------------------------------- | | Codex | codex app-server, with rollout JSONL fallback | Transcript file size | codex delete --force <id> | Individual native deletes | | Claude Code | Local transcript metadata | Transcript file size | Not supported | claude project purge <path> --yes | | OpenCode | opencode session list --format json | Logical session/message/part payload via opencode db | opencode session delete <id> | Individual native deletes |

OpenCode size excludes shared SQLite pages, indexes, and WAL data because those bytes cannot be accurately attributed to one session.

Safety

Deletion is never performed directly from a list keypress or mouse click. Every supported operation opens a centered preview containing the native commands and requires explicit confirmation.

• Active sessions remain blocked from bulk deletion.
• Unsupported operations remain blocked.
• Global orphan cleanup skips operations that may remove additional provider-managed data.
• Claude Code single-session deletion is blocked because it has no supported native operation. The preview shows a project-level --dry-run alternative when possible.
• Demo mode never executes deletion, including after confirmation.

Deletion is permanent once a supported command is confirmed in normal mode. Review the preview carefully.

The project intentionally does not generate or commit a dependency lockfile. .npmrc sets package-lock=false, and common lockfile names are ignored.

Production files are compiled directly with tsc -p tsconfig.build.json. There is no bundler or post-build rewrite step.

License

MIT