codex-cleaner

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 10 Open GitHub ↗

Open-source SwiftUI macOS app for safely cleaning and archiving local Codex desktop state in ~/.codex.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Codex Cleaner

[![Latest release](https://img.shields.io/github/v/release/AyoParadis/codex-cleaner?label=version)](https://github.com/AyoParadis/codex-cleaner/releases/latest)
[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-111827?logo=apple)](https://github.com/AyoParadis/codex-cleaner/releases/latest)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/AyoParadis/codex-cleaner/main/LICENSE)

Codex Cleaner is a native macOS utility for safely maintaining local Codex
state in `~/.codex`. It scans first, backs up important data, keeps pinned chats
active, and clearly shows what cleanup will do before anything changes.

Current release: **v1.0.23**

![Codex Cleaner v1.0.23 overview](https://raw.githubusercontent.com/AyoParadis/codex-cleaner/main/docs/screenshots/codex-cleaner-app.png)

## Why use it?

- **Pinned chats stay active.** Cleaner restores pinned rollouts moved by older
  versions and always excludes them from optional chat archiving.
- **Archiving is the default.** Old generated files and worktrees move into
  recoverable archive folders instead of being deleted.
- **Chat cleanup is opt-in.** Only old unpinned chats are eligible, and Codex's
  native archive command keeps them resumable.
- **Every action is visible.** Live scan phases, item counts, elapsed time, and
  a cleanup plan make long scans understandable.
- **Local and private.** Cleanup runs on the Mac. The update checker reads only
  this repository's public latest-release record; it sends no Codex data or
  analytics.

## What it maintains

Codex Cleaner scans active and archived sessions, worktrees, generated image
runs, visualizations, shell snapshots, logs, databases, attachments, dictation
history, and trusted project entries.

Before cleanup, it creates a timestamped backup in:

```text
~/.codex/maintenance_backups
```

The default cleanup can:

- restore pinned chats that older Cleaner versions archived;
- archive stale worktrees, generated images, visualizations, and shell
  snapshots;
- rotate oversized `logs_*` SQLite files and their `-wal`/`-shm` sidecars;
- remove trusted project entries whose folders no longer exist; and
- optionally archive unpinned chats older than 10 days.

The separate **Delete old generated bloat** option permanently removes only
stale generated image runs, visualizations, and shell snapshots. It never
deletes chats, worktrees, logs, databases, config, backups, attachments,
dictation history, or project settings.

> [!IMPORTANT]
> Quit Codex before cleanup. Codex Cleaner refuses to mutate `~/.codex` while
> Codex is running so both apps cannot touch the same local databases.

## Install on macOS

Requires macOS 14 or newer.

1. Download
   [Codex Cleaner v1.0.23 for macOS](https://github.com/AyoParadis/codex-cleaner/releases/download/v1.0.23/Codex-Cleaner-1.0.23-macOS.zip).
2. Expand the ZIP and move **Codex Cleaner.app** to `/Applications`.
3. Open the app. If macOS blocks the first launch, Control-click the app,
   choose **Open**, then confirm.

The matching
[SHA-256 checksum](https://github.com/AyoParadis/codex-cleaner/releases/download/v1.0.23/Codex-Cleaner-1.0.23-macOS.zip.sha256)
is published with the release.

## Updates

Cleaner checks for a newer public GitHub release at most once per day while it
is open. You can also choose **Codex Cleaner → Check for Updates…**.

When an update exists, choose **Download Update** or **Later**. Cleaner never
downloads, replaces, or launches software without your choice. After download,
quit Cleaner and replace the app in `/Applications`.

## Build from source

```sh
git clone https://github.com/AyoParadis/codex-cleaner.git
cd codex-cleaner
./Scripts/build-app.sh
open ".build/app/Codex Cleaner.app"
```

Run the test suite with:

```sh
swift test
```

Package a release ZIP and checksum with:

```sh
./Scripts/package-release.sh
```

The packaging script verifies that the current version is documented in both
this README and [CHANGELOG.md](CHANGELOG.md), so release documentation cannot
silently fall behind the app bundle.

## Latest changes

- **v1.0.23:** Added the Clean Vault icon across Finder, Dock, About, and the
  in-app sidebar, with a complete Retina-aware ICNS set.
- **v1.0.22:** Added automatic and manual update checks with explicit
  **Download Update** and **Later** choices.
- **v1.0.21:** Fixed large-database scan stalls; added live progress, elapsed
  time, visible version/build information, and a simpler native layout.
- **v1.0.20:** Restored pinned chats archived by older builds and made old
  unpinned chat archiving opt-in through Codex's native archive command.

See [CHANGELOG.md](CHANGELOG.md) for the complete release history.

## Social preview

The repository-ready 1280 × 640 sharing image is stored at
[`docs/social-preview.jpg`](docs/social-preview.jpg).

![Codex Cleaner v1.0.23 social preview](https://raw.githubusercontent.com/AyoParadis/codex-cleaner/main/docs/social-preview.jpg)

## Credit

Inspired by Meta Alchemist
([@meta_alchemist](https://x.com/meta_alchemist)) and
[their Codex cleanup checklist](https://x.com/meta_alchemist/status/2050270281521045844):
inspect first, back up important state, maintain stale data, verify the result,
and make routine maintenance boring.

---

<h2 align="center">💛 Support this project</h2>

<p align="center">
  <strong>Help keep Codex Cleaner safe and current as Codex storage formats evolve.</strong><br>
  <sub>Your support funds ongoing macOS compatibility, maintenance, and developer documentation.</sub>
</p>

## License

[MIT](LICENSE)

codex-cleaner

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README