codex-cleaner 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codex-cleaner contributors
+
+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,83 @@
+# codex-cleaner
+
+Guarded local cleanup for bloated Codex state under `~/.codex`.
+
+```powershell
+npx codex-cleaner@latest
+```
+
+The default TUI always dry-runs first, then offers one apply step after Codex is fully closed.
+It starts with recommended settings, or you can customize each setting.
+
+Current cleanup:
+
+- archives stale unpinned threads through Codex's own app-server API
+- moves old DB-unreferenced rollout JSONL from `sessions` to `archived_sessions`
+- caps huge old `threads.title`, `threads.preview`, and `threads.first_user_message` values
+- optionally caps recent unprotected metadata too
+- vacuums `state_5.sqlite`
+- optionally prunes/caps and vacuums `logs_2.sqlite`
+- optionally backs up and trims `log/codex-tui.log`
+- checkpoints/truncates `state_5.sqlite-wal`
+- scans, prunes, or schedules pruning for old cleaner backups
+
+Noninteractive dry-run:
+
+```powershell
+npx codex-cleaner@latest --allow-running-readonly clean --max-chars 1024 --keep-recent-days 14 --archive-orphan-rollouts --compact-recent-metadata --prune-logs --prune-tui-log
+```
+
+Noninteractive apply:
+
+```powershell
+npx codex-cleaner@latest clean --max-chars 1024 --keep-recent-days 14 --archive-orphan-rollouts --compact-recent-metadata --prune-logs --prune-tui-log --apply --confirm-lossy-metadata --confirm-archive-stale --confirm-archive-orphan-rollouts --confirm-prune-logs --confirm-prune-tui-log
+```
+
+Backup cleanup:
+
+```powershell
+npx codex-cleaner@latest backups scan
+npx codex-cleaner@latest backups prune --older-than-hours 48
+npx codex-cleaner@latest backups prune --older-than-hours 48 --apply --confirm-delete-backups
+npx codex-cleaner@latest backups schedule-prune --after-hours 48 --apply --confirm-schedule-backup-prune
+```
+
+File-only active-session cleanup:
+
+```powershell
+npx codex-cleaner@latest archive-orphan-rollouts --allow-running-orphan-rollout-archive --keep-recent-days 14 --apply --confirm-archive-orphan-rollouts
+```
+
+Safety basics:
+
+- dry-run by default
+- apply refuses to run while Codex processes are active
+- pinned, heartbeat/open, and active-goal threads are always protected
+- recent threads are protected unless `--compact-recent-metadata` is passed
+- rollout JSONL is retained; old DB-orphaned files may be moved out of active `sessions`
+- `archive-orphan-rollouts` reads SQLite but only moves JSONL files and removes empty dirs
+- backups are created in `~/.codex/.codex-cleanup-backups` before mutation
+- after Codex looks right, delete old backups to reclaim disk
+- backup pruning is dry-run unless `--apply --confirm-delete-backups` is passed
+
+## Dev
+
+```powershell
+npm install
+npm run check
+npm pack --dry-run
+```
+
+Local dogfood:
+
+```powershell
+npm run build
+node .\dist\cli.js
+```
+
+Active-session file-only cleanup:
+
+```powershell
+node .\dist\cli.js --allow-running-readonly archive-orphan-rollouts --keep-recent-days 14
+node .\dist\cli.js archive-orphan-rollouts --allow-running-orphan-rollout-archive --keep-recent-days 14 --apply --confirm-archive-orphan-rollouts
+```

package/dist/cleaner.d.ts

@@ -0,0 +1,55 @@
+import path from "node:path";
+import Database from "better-sqlite3";
+import type { BlockingProcess, CleanerOptions, CompactWhere } from "./types.js";
+type CodexSpawnCommand = {
+    args: string[];
+    command: string;
+};
+export declare function requireStoppedOrReadonlyAllowed(args: {
+    allowRunningReadonly: boolean;
+    mutating: boolean;
+}): Promise<void>;
+export declare function findBlockingProcesses(): Promise<BlockingProcess[]>;
+export declare function resolveCodexSpawnCommand(codexCommand: string, args: string[], platform?: NodeJS.Platform, windowsMatches?: string[]): Promise<CodexSpawnCommand>;
+export declare function buildScanReport(options: CleanerOptions): Record<string, unknown>;
+export declare function compactMetadata(options: CleanerOptions): Promise<Record<string, unknown>>;
+export declare function cleanCodex(options: CleanerOptions): Promise<Record<string, unknown>>;
+export declare function archiveStaleThreads(options: CleanerOptions): Promise<Record<string, unknown>>;
+export declare function archiveOrphanRollouts(options: CleanerOptions): Record<string, unknown>;
+export declare function checkpointWal(options: CleanerOptions, backupBeforeCheckpoint?: boolean): Promise<Record<string, unknown>>;
+export declare function vacuumStateDatabase(options: CleanerOptions, backupBeforeVacuum?: boolean): Promise<Record<string, unknown>>;
+export declare function cleanLogs(options: CleanerOptions): Promise<Record<string, unknown>>;
+export declare function cleanTuiLog(options: CleanerOptions): Promise<Record<string, unknown>>;
+export declare function scanBackups(options: CleanerOptions): Record<string, unknown>;
+export declare function pruneBackups(options: CleanerOptions): Record<string, unknown>;
+export declare function scheduleBackupPrune(options: CleanerOptions): Promise<Record<string, unknown>>;
+export declare function compactWhere(args: {
+    archivedOnly: boolean;
+    cutoffMs: number;
+    maxChars: number;
+    protectRecent: boolean;
+    protectedIds: Set<string>;
+}): CompactWhere;
+export declare function collectCompactCandidateStats(db: Database.Database, args: {
+    archivedOnly: boolean;
+    cutoffMs: number;
+    maxChars: number;
+    protectRecent: boolean;
+    protectedIds: Set<string>;
+}): Record<string, unknown>;
+export declare function collectStaleArchiveCandidateStats(db: Database.Database, codexHome: string, args: {
+    cutoffMs: number;
+    protectedIds: Set<string>;
+    statRollouts?: boolean;
+}): Record<string, unknown>;
+export declare function collectLogCleanupStats(db: Database.Database, options: CleanerOptions): Record<string, unknown>;
+export declare function collectTuiLogCleanupStats(logPath: string, keepMib: number): Record<string, unknown>;
+export declare function collectOrphanRolloutArchiveStats(db: Database.Database, codexHome: string, args: {
+    cutoffMs: number;
+}): Record<string, unknown>;
+export declare function nextBackupPath(dbPath: string, backupDir: string, now?: Date): string;
+export declare function nextFileBackupPath(filePath: string, backupDir: string, now?: Date): string;
+export declare function truncateFileToTail(filePath: string, keepBytes: number): void;
+export declare function rolloutThreadId(file: string | path.ParsedPath): string | null;
+export declare function emitReport(report: Record<string, unknown>, asJson: boolean): void;
+export {};