Add Storage page for Codex session usage and cleanup policy

[0disoft]

Problem

Codex session data can grow quietly over time, but the dashboard currently does not show where that storage is going or offer a guided way to reclaim space.

On one active Windows setup, the largest Codex-related storage buckets were roughly:

• archived sessions: ~3.1 GB
• active sessions: ~1.3 GB
• logs sqlite: ~1.1 GB
• attachments / remote attachments / deletion manifests: smaller, but still useful to surface

The exact numbers will vary by user, but the important part is that storage is split across multiple Codex-owned areas. Users often only notice the problem after disk space has already dropped sharply.

Proposal

Add a dashboard Storage page that starts with read-only diagnostics, then grows into cleanup controls if the direction makes sense.

Phase 1: storage diagnostics

Show a compact breakdown for:

• active sessions
• archived sessions
• logs database / WAL files
• attachments
• remote attachments
• deletion manifests
• total tracked size

Useful fields:

• size
• count
• oldest item
• newest item
• largest few items, capped to avoid rendering a huge table

Phase 2: manual archived cleanup

Add an archived-session cleanup flow with preview first:

• slider for deleting the oldest archived conversations by percentage
• quick presets such as 10%, 25%, 50%
• preview button before any deletion
• confirmation modal showing estimated count and bytes to remove
• optional checkbox for immediate permanent deletion
• safer default can be quarantine/trash if preferred by the project

Active sessions should probably stay read-only at first.

Phase 3: optional auto-cleanup policy

Add an opt-in policy for users who want storage to stay bounded:

• default off
• threshold such as "archived sessions exceed N GB"
• cleanup target such as "reduce to N GB" or "delete oldest N%"
• schedule such as startup / daily / weekly / manual
• deletion mode: quarantine/trash or permanent delete
• last run, next run, and freed bytes summary

This should run as a batch policy, not delete one item every time a new session appears.

Implementation concerns

Deleting Codex history is not just a simple filesystem delete. The implementation may need to account for:

• rollout JSONL files
• state_5.sqlite thread rows and rollout paths
• attachments linked to removed sessions
• deletion manifests / audit trail if quarantine is used
• database locks while Codex is active

Because of that, I think the first PR should probably be read-only diagnostics plus cleanup preview, with actual deletion added only after the data model is clear.

Open questions

• Should opencodex directly manage Codex session deletion, or only expose diagnostics?
• Should logs_2.sqlite be shown on the Storage page, cleaned separately, or left as diagnostics only?
• Should permanent deletion be supported behind an explicit checkbox, or should quarantine be the only supported cleanup mode?
• If you agree with this direction, would you prefer to implement it yourself, or should I prepare a phased PR starting with read-only diagnostics?

[lidge-jun]

Promoting this to a long-term epic with phased delivery. Splitting the work as you proposed:

Phase 1 — Storage diagnostics (read-only) · low risk · first PR

A dashboard Storage page that shows where ~/.codex disk goes, with zero deletion.

• New GET /api/storage (read-only) aggregating per-bucket size/count/oldest/newest.
• New gui/src/pages/Storage.tsx next to Usage/Logs.
• Sizes via fs.stat; any DB row counts via ?mode=ro&immutable=1 with graceful skip on lock — never opens an in-use DB for writing.

Phase 2 — Manual archived cleanup · C4 high-risk · separate PR

Reclaim space from old archived sessions, preview-first, quarantine by default.

• Preview + confirmation modal showing estimated count + bytes before any action.
• Permanent delete only behind an explicit checkbox.
• Full data-model reconciliation (not a file delete): the rollout JSONL + the threads row (rollout_path, archived) + attachments + deletion manifest, plus WAL-lock safety while Codex is running.
• Active sessions stay read-only.

Phase 3 — Opt-in auto-cleanup policy · default OFF · separate PR

Threshold + target + schedule + deletion mode, with last/next-run and freed-bytes summary. Inherits all Phase 2 safety.

Measured layout (this Mac, ~/.codex)

• sessions/<YYYY>/<MM>/<DD>/rollout-<ts>-<uuid>.jsonl — 2.4 GB / 858 files (dominant consumer). JSONL line types: session_meta, event_msg, response_item.
• state_5.sqlite — threads table (236 rows, 1 archived) with rollout_path as the JOIN key to each session's JSONL, plus archived/archived_at.
• logs_2.sqlite — 78,037 rows, separate lifecycle (estimated_bytes per row).
• archived_sessions/ — flat dir of archived rollout JSONL.

Recommendation: ship Phase 1 (read-only) first; Phase 2/3 land as separate, carefully-reviewed PRs with quarantine as the default cleanup mode and explicit lock safety.

[Wibias]

@lidge-jun Have u already started working on this one?

[lidge-jun]

@Wibias not yet I think upstream will fixing issue with somehow but planning in weeks