# CacheLens
> Explainable AI Developer Cache & State Inspector for macOS (Zero-telemetry, Trash-by-default, Classification-depth).

CacheLens is a native macOS application and CLI utility designed specifically for AI engineers and developers. It audits local caches, models, and state directories generated by modern AI coding IDEs (Cursor, Claude Code, Codex, Ollama, Windsurf, Trae, Antigravity, Roo Code, Continue, Cline, and Xcode), explaining the exact deletion consequences and recovery path for every single file before cleanup.

## Why CacheLens Matters (The AI Cache Problem)
Generic Mac cleaners (CleanMyMac, CleanMyDev, etc.) treat developer directories as disposable junk. In modern AI workflows, blindly deleting folders causes catastrophic data loss:
- **Cursor (`state.vscdb*`)**: Deleting index and history databases can leave Cursor permanently stuck on "Loading Chat..." and breaks codebase indexing. CacheLens marks this **Review** (never Safe) and advises using in-editor cleanup.
- **Cursor Snapshots (`*.pack`)**: Checkpoint packs can balloon to tens or hundreds of gigabytes in days. CacheLens identifies runaway writers, marks them **Review**, and advises quitting Cursor before trashing.
- **Claude Code & Codex Sessions**: Prompts, tool memories, and conversation transcripts are protected or audited with explicit recovery instructions.
- **Ollama & LM Studio Models**: Multi-gigabyte GGUF model weights are itemized as **Review** so users never accidentally wipe offline models.
- **API Keys & Auth Tokens**: Credentials (`.credentials.json`, `auth.json`, `Preferences`) are classified as **Protect** and locked against deletion.

## Core Pillars & Safety Guardrails
- **Classification Depth**: Every item is categorized into **Safe** (disposable/regenerable cache), **Review** (history, models, index DBs, runaway packs), or **Protect** (auth tokens, configurations, machine IDs).
- **Fail-Closed Stale-Rule Downgrade**: If a rule's verification metadata is missing or the on-disk directory layout changed, CacheLens immediately downgrades the item to Review. It never guesses.
- **Trash by Default**: Cleanup strictly invokes `FileManager.trashItem`. Silent, permanent `rm -rf` deletions are banned.
- **Zero Telemetry / 100% Local**: Scan, classification, rule verification, and license activation run completely on-device. No network requests, no path telemetry, no cloud dependencies.
- **Safety Ledger**: Every cleanup writes a local, human-readable JSONL receipt with deletion cost and recovery hints.

## Supported AI Tools & Developer Ecosystem
- **Cursor**: `~/.cursor`, `~/Library/Application Support/Cursor`, `~/Library/Caches/Cursor`
- **Claude Code**: `~/.claude` (transcripts, projects, credentials)
- **Codex (OpenAI)**: `~/.codex` (sessions, auth, state)
- **Ollama & LM Studio**: `~/.ollama`, `~/.lmstudio` (model weights, blob storage)
- **Antigravity (Google)**: `~/.gemini` (brain tasks, auth tokens, crashes)
- **Windsurf**: `~/Library/Application Support/Windsurf`, `~/.codeium` (Cascade chats, workspace state)
- **Trae**: `~/Library/Application Support/Trae` (snapshots, cache)
- **Roo Code, Cline, Continue**: Extension global storage, SQLite indexes, LanceDB vectors
- **Xcode**: DerivedData, Archives, iOS DeviceSupport, Simulators

## Key Resources & Documentation
- [Official Website](https://getcachelens.pages.dev/): Product overview, pricing, and direct DMG downloads.
- [Safety Boundaries](https://getcachelens.pages.dev/safety/): Formal security invariants, fail-closed policy, and process guards.
- [Privacy Policy](https://getcachelens.pages.dev/privacy/): Strict zero-telemetry guarantee and offline commitment.
- [Release Binaries](https://github.com/ggxx39/cachelens-releases): Public notarized DMG downloads and SHA-256 checksums.

## Installation & CLI Usage
- **Download**: DMG installer available at `https://getcachelens.pages.dev/`
- **CLI Commands**:
  - `cachelens scan` — Perform a local audit across all installed AI dev tools.
  - `cachelens clean --path <PATH>` — Safely move a verified item to macOS Trash.
  - `cachelens rules verify` — Audit bundled classification rules against on-disk layout.
  - `cachelens receipts --markdown` — Print the local safety audit trail as a Markdown table.