Skip to content

Add Storage page for Codex session usage and cleanup policy #42

Closed
Closed
Add Storage page for Codex session usage and cleanup policy#42
Labels
enhancementNew feature or requestroadmapAccepted long-term work item; needs its own project cycle

Description

@0disoft
0disoft
opened on Jun 28, 2026

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?

Activity

  1. lidge-jun commented on Jun 29, 2026

    @lidge-jun
    lidge-jun
    on Jun 29, 2026
    Owner

    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.

  2. lidge-jun
    added 2 commits that reference this issue on Jun 29, 2026

    docs(storage): promote issue #42 to 500_ epic with phased plan

    c9cac17

    docs(storage): expand #42 epic to jawdev granularity

    11751d9

  3. Wibias commented on Jul 10, 2026

    @Wibias
    Wibias
    on Jul 10, 2026
    Contributor

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

  4. lidge-jun commented on Jul 10, 2026

    @lidge-jun
    lidge-jun
    on Jul 10, 2026
    Owner

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

  5. Chang-Jin-Lee commented on Jul 20, 2026

    @Chang-Jin-Lee
    Chang-Jin-Lee
    on Jul 20, 2026
    Contributor

    Hi @lidge-jun — I'd like to take Phase 1 (read-only diagnostics) as scoped in your epic comment and devlog/_plan/500_storage-page-session-cleanup (31–33): a storage scanner module + GET /api/storage + a read-only Storage page next to Usage/Logs, with fixture tests asserting the read-only invariant (no writes under CODEX_HOME during a scan). Zero deletion logic — Phases 2/3 untouched.

    Planning to open a PR within a day or two — please flag me if this collides with anything you've already started.

  6. lidge-jun
    added a commit that references this issue on Jul 20, 2026

    feat(gui): read-only Storage diagnostics page (Phase 1 of #42) (#173)

    24d8bbb

  7. lidge-jun commented on Jul 22, 2026

    @lidge-jun
    lidge-jun
    on Jul 22, 2026
    Owner

    Status update: Phase 1 (storage diagnostics page) has landed. The remaining phases — cleanup actions and auto-cleanup policy — touch session lifecycle and are deliberately gated behind more careful design, since a bad cleanup pass can destroy user threads. Still planned, keeping this open to track Phase 2+.

  8. lidge-jun
    added
    roadmapAccepted long-term work item; needs its own project cycle
    enhancementNew feature or request
    on Jul 22, 2026

  9. Wibias commented on Jul 27, 2026

    @Wibias
    Wibias
    on Jul 27, 2026
    Contributor

    Phase 2 (Option A) opened in #529 — preview-first archived cleanup with quarantine under CODEX_HOME/.trash (permanent delete behind checkbox). Phase 1 hygiene (.trash scan skip, dead imports, docs) folded into that PR. No restore UI / auto-policy yet (Phase 2.1 / Phase 3).

  10. github-actions commented on Jul 27, 2026

    @github-actions
    github-actionsBot
    on Jul 27, 2026 – with GitHub Actions
    Contributor
  11. Ingwannu
    added a commit that references this issue on Jul 27, 2026

    Merge pull request #529 from Wibias/feat/storage-phase2-cleanup

    84f39c4
  12. lidge-jun
    added a commit that references this issue on Jul 27, 2026

    docs(devlog): correct the decision ledger against an independent audit

    01aa08f
  13. Wibias
    added 2 commits that reference this issue on Jul 27, 2026

    Merge pull request #559 from Wibias/feat/storage-phase3-auto-policy

    9dbcc24

    feat(storage): restore quarantined archived sessions (phase 2.1 of #42)…

    40fdc3d
  14. Wibias
    closed this as completedon Jul 27, 2026
  15. agentHits
    added 6 commits that reference this issue on Sep 17, 2026

    docs(storage): promote issue lidge-jun#42 to 500_ epic with phased plan

    970e66c

    docs(storage): expand lidge-jun#42 epic to jawdev granularity

    092a817

    feat(gui): read-only Storage diagnostics page (Phase 1 of lidge-jun#42)…

    9989e92

    Merge pull request lidge-jun#529 from Wibias/feat/storage-phase2-cleanup

    4e65e67

    Merge pull request lidge-jun#559 from Wibias/feat/storage-phase3-auto…

    706bff7

    feat(storage): restore quarantined archived sessions (phase 2.1 of li…

    72c6879
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestroadmapAccepted long-term work item; needs its own project cycle

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions