Metadata-Version: 2.5
Name: session-cleaner
Version: 0.1.0
Summary: Clean up Codex and Claude Code sessions for workspaces that no longer exist
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# session-cleaner

A small CLI that finds Codex and Claude Code sessions whose recorded workspace
directories no longer exist. By default, it asks you to remove or keep each candidate.
Python 3.10+; no runtime dependencies.

## Install

From a checkout, install it as an isolated command with uv:

```sh
uv tool install .
session-cleaner
```

Or install it into a Python environment with pip:

```sh
python -m pip install .
```

## Usage

```sh
session-cleaner                         # choose remove or keep for each candidate
session-cleaner --provider codex        # only Codex
session-cleaner --provider claude       # only Claude Code
session-cleaner --dry-run               # preview only; no prompts or deletion
session-cleaner --dry-run --json        # detailed machine-readable report
session-cleaner --json > session-cleaner-report.json
session-cleaner --delete                # delete all candidates without prompting
```

The default command first scans, then shows each candidate's provider, session ID,
and missing workspace. Choose `r` (remove) to delete that session immediately,
or `k` (keep) to leave it untouched and continue. Enter defaults to keep; `q`
quits and leaves all remaining candidates untouched. Keeping a session applies
to this run only; it can appear again next time. End of input also stops safely.

`--dry-run` and `--json` never prompt. JSON is a preview unless explicitly combined
with `--delete`. The `--delete` flag still supports unattended bulk cleanup.
Stop Codex and Claude Code before deleting so they cannot recreate files or race
with index updates. Exit status is `0` on success, `1` on an operational/deletion
error, `2` for invalid arguments, and `130` when interrupted at a prompt.
Warnings describe individual files that could not be inspected; those files are
preserved. A preview with warnings may be incomplete.

Defaults are `$CODEX_HOME` (otherwise `~/.codex`) and `$CLAUDE_CONFIG_DIR`
(otherwise `~/.claude`). Override either explicitly:

```sh
session-cleaner --codex-home /path/to/.codex --claude-home /path/to/.claude
```

## What it checks and cleans

The tool reads actual workspace paths from session metadata, never by decoding
Claude's project directory names. A session is eligible only when **every known
workspace path is missing**. Existing paths, permission errors, relative paths,
foreign-platform paths, malformed metadata, and symlinks in session storage are
retained or skipped. Missing stores are a no-op. Deleted worktrees count as
missing workspaces even if their parent repository still exists.

| Provider | Session discovery | Matching data removed when a session is deleted |
| --- | --- | --- |
| Codex | `sessions/**/*.jsonl`, `archived_sessions/**/*.jsonl`, and `state_*.sqlite` threads | Transcripts, session-named shell snapshots, history/session-index entries, and rows keyed to the selected thread IDs in state/history/goals/queue/memories/logs databases |
| Claude Code | `projects/**/*.jsonl`, including subagent transcripts; `history.jsonl` and `sessions-index.json` metadata also cover sessions whose transcripts are gone | Transcripts, session-named project sidecar directories, file-history/session-env files, history entries, and `sessions-index.json` entries |

The JSON report lists only sessions eligible for removal, with their workspaces,
transcript and sidecar files, and Codex state databases. The summary still counts
all inspected sessions. Byte totals cover selected files;
they exclude database/index changes and do not predict disk space reclaimed by
SQLite. Shared history records are removed by exact session ID; unrelated records
and malformed JSONL history lines are preserved. Configuration and credentials
are not modified.

This tool handles local CLI storage formats, not cloud or remote session stores.
Unmounted disks and disconnected network filesystems can look like missing
workspaces: reconnect them before reviewing/deleting. It cannot prove that a
missing path is permanently gone. Stop clients even if their workspace has
already been deleted; workspace absence does not prove a session is inactive.

Files and workspace existence are checked again before deletion. Index files
are replaced atomically, and SQLite uses transactions. There is no global
transaction across multiple databases; a failure during commits can leave a
partial cleanup. File staging is temporary and is **not a persistent backup**.
Unknown future storage schemas may need an update to this tool.

## Develop, build, and distribute

The project follows uv's [packaged application layout](https://docs.astral.sh/uv/concepts/projects/init/)
and exposes the `session-cleaner` console command through `[project.scripts]`.
Claude's transcript location is described in its [session documentation](https://code.claude.com/docs/en/sessions).
Codex adapters are based on the local rollout and SQLite schemas inspected during development.

```sh
uv sync --dev
uv run session-cleaner --help
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build
```

Tests use synthetic data under temporary directories; they never clean your
actual session stores. `uv.lock` pins development dependencies. The wheel and
source distribution land in `dist/`; install a wheel with either:

```sh
uv tool install dist/session_cleaner-0.1.0-py3-none-any.whl
python -m pip install dist/session_cleaner-0.1.0-py3-none-any.whl
```

The package has not been published to PyPI. After choosing an available package
name, setting the intended release metadata/license, and publishing the built
artifacts, users can install it by that name with `uv tool install` or `pip install`.
