CliJanitor (v1.0.0)

English | 简体中文

Unified local session cleaner for Claude Code, Codex, and Gemini, with both CLI and desktop GUI.

Table of Contents

• Introduction
• Key Features
• Quick Start
• GUI Usage
• CLI Usage
• Config and Data
• Build EXE
• Release Artifact
• FAQ
• Project Structure

Introduction

AI CLI tools can generate many local session files over time. CliJanitor helps you:

• Scan sessions from Claude Code / Codex / Gemini.
• Filter by provider, keyword, date, and size.
• Preview sessions and edit descriptions in GUI.
• Batch delete safely (recycle bin by default).

Key Features

• Session summary behavior aligned with real usage:
  • Codex: prefers first meaningful user message.
  • Gemini: prefers the first sentence of the first user message.
• Editable description:
  • Writes back to source session files first (json/jsonl).
  • Falls back to local storage if source write fails.
• Conversation Preview is easier to read:
  • USER and ASSISTANT are rendered with different colors.
  • command/meta/reasoning noise is filtered (including Claude local-command records and Codex commentary streams).
  • the preview tail appends Recent Dialogue / 最近一次对话 with the latest completed user + assistant round.
• Realtime filters (no Apply button):
  • provider, keyword, date picker, sorting, page size.
• Better list actions:
  • Select All, Select All Filtered, Clear Selection.
• Safe delete model:
  • when Dry-run is on, no actual deletion happens (even if permanent delete is enabled).
• Detail panel:
  • preview conversation, edit/save description, open session source file.
• Explicit stats units:
  • User turns, Input tokens, Output tokens.

Quick Start

Option 1: Run EXE (Windows)

• Executable: release/CliJanitor/CliJanitor.exe

Option 2: Run from source

# Install project in editable mode (code changes take effect immediately)
pip install -e .
# Run environment and dependency diagnostics
clijanitor doctor
# Launch desktop GUI
clijanitor gui

GUI Usage

Layout

• Top: Scan button (with query icon) and loading overlay.
• Left: filters and delete mode.
• Middle: paginated session list and selection actions.
• Right: detail panel, description edit, preview, open source file.

Conversation Preview Behavior

• Keeps only conversation content (user/assistant) and skips tool/runtime noise.
• Adds a separator at the end:
  • Recent Dialogue / 最近一次对话
• If the latest turn has no assistant answer yet, the recent section may only show the latest user message.

Interface Preview

CLI Usage

Common Commands

# Check runtime environment and dependencies
clijanitor doctor
# Scan configured provider roots and refresh local index
clijanitor scan
# List sessions with current/default filters
clijanitor list
# Show details for a session by ID prefix
clijanitor show <session_id_prefix>

Filter Examples

# List Codex sessions containing keyword "bug" before a date
clijanitor list --provider codex --keyword bug --before 2026-01-01
# List Claude Code sessions within a file-size range (bytes)
clijanitor list --provider claude_code --min-size 1024 --max-size 1048576

Delete Examples

# Preview only (no deletion)
clijanitor delete --provider codex --before 2026-01-01 --dry-run

# Delete by session ID prefix
clijanitor delete 2f7a9d1 9b18ef0

# Delete all matched sessions (explicit --all required)
clijanitor delete --provider gemini --keyword draft --all

Config and Data

• Config: %USERPROFILE%\.clijanitor\config.toml
• Delete log: %USERPROFILE%\.clijanitor\logs\actions.log
• Runtime log: %USERPROFILE%\.clijanitor\logs\runtime.log
• Description fallback: %USERPROFILE%\.clijanitor\session_descriptions.json

Notes:

• Gemini sessions are commonly under ~/.gemini/tmp/*/chats/session-*.json.
• Legacy config auto-merges missing Gemini default roots.

Build EXE

# Install build dependency
python -m pip install cx_Freeze
# Build Windows EXE into release/CliJanitor
python cxfreeze_setup.py build_exe --build-exe release\CliJanitor

If release/CliJanitor is locked by a running app, stop processes and clean first:

# Stop GUI runtime processes
Get-Process CliJanitor,flet -ErrorAction SilentlyContinue | Stop-Process -Force
# Remove old build folder
cmd /c if exist release\CliJanitor rmdir /s /q release\CliJanitor
# Rebuild
python cxfreeze_setup.py build_exe --build-exe release\CliJanitor

Version check:

# Print package version from installed module
python -c "import clijanitor; print(clijanitor.__version__)"
# Check built EXE file name, size and timestamp
Get-Item release\CliJanitor\CliJanitor.exe | Select-Object Name,Length,LastWriteTime

Release Artifact

• Folder: release/CliJanitor/
• Executable: release/CliJanitor/CliJanitor.exe
• Current version: v1.0.0

FAQ

• Q: Why old sessions disappeared after auth mode changes?
  • A: Click Scan and check provider roots. Codex is usually under ~/.codex/sessions.
• Q: Why official /resume list may not update instantly after description edits?
  • A: Some clients cache indices. Re-open resume list, and restart the related CLI process if needed.
• Q: What if Dry-run and permanent delete are both enabled?
  • A: Dry-run wins. It is preview only.
• Q: Why does the recent section sometimes show only one side?
  • A: The latest turn may be incomplete (for example, user sent a message but no assistant final answer yet).
• Q: What is flet.exe?
  • A: It is the Flet desktop runtime used by CliJanitor.exe.

Project Structure

.
|- src/clijanitor/         # CLI, GUI, models, services
|- tests/                  # tests
|- assets/                 # icons and assets
|- docs/screenshots/       # README screenshots
|- cxfreeze_setup.py       # EXE build script
|- README.md               # English docs
`- README_zh.md            # Chinese docs