Codex Data Storage

  • Desktop app
  • All plans
View as Markdown

What it does

Every Codex agent runs in a folder AgentsRoom generates per project and per account, where Codex keeps its conversations, logs and generated images. Nothing used to delete those folders: a project removed from the sidebar, an account removed from Settings or a finished QA run left its data on disk for good, and one install was found holding several gigabytes for a single live project. Since 1.184.0 AgentsRoom cleans up in two ways: the folders of deleted projects and removed accounts are reclaimed whole, and inside the live folders the conversations, logs and generated images older than a retention you choose are deleted. A conversation a saved agent can still resume is never touched, whatever its age.

Where to find it

Settings > AI providers & accounts > Codex tab, under the Codex Accounts block: the Codex data on this machine row. It shows the total size and the number of folders ("N folders"), how many belong to a deleted project or a removed account and their size ("N folders from deleted projects or removed accounts (size)"), the Keep data for selector and the Reclaim disk space button.

How to use it

  1. Nothing to enable. At every launch of the app (a little after the restored consoles are back), when you delete a project and when you remove a Codex account, the matching folders are reclaimed by themselves.
  2. To free space now, open the Codex tab and click Reclaim disk space. The row then reads "Freed {size} ({homes} folders, {files} files)." or "Nothing to reclaim.", and "N folders used by running agents were left alone." when a Codex console is still open on one of them: stop the agent and click again if you want that folder swept too.
  3. To keep less (or more) history, pick a value in Keep data for: 7, 30 or 90 days, or Forever. The rule applies at the next startup and the next click on the button. A value set through the settings tool that is not one of these four is shown as its own option, never snapped to another one.

What the rotation removes inside a live folder: conversation transcripts, log databases, generated images and temporary files untouched for longer than the retention. What it keeps: the session index Codex lists and resumes from, the account link, the configuration, the agent profiles, skills and plugins, and any transcript still reachable from a saved agent of the project.

Settings

  • codexDataRetentionDays (global, Settings > AI providers & accounts > Codex > Keep data for): days of Codex data kept in the generated folders, whole number from 0 to 3650, default 90. 0 means Forever: the rotation is off, but folders of deleted projects and removed accounts are still reclaimed.

Agent tools (MCP)

  • settings_get / settings_set: read or change codexDataRetentionDays (scope: "global"). No tool triggers the sweep or reads the size report: the button is a user gesture.

Providers

Codex only: it is the one CLI AgentsRoom runs from a generated home per project and per account. Claude accounts, Grok and Cursor directories are managed accounts you create on purpose and are not swept; the Codex account directories themselves (where the login lives) are not removed either when you delete an account, only the per-project folders derived from it.

Mobile

Not on the phone: the disk of the desktop machine has no equivalent there, and the storage settings are not exposed to the mobile companion.

Limits

  • A folder with a running Codex console is never deleted, and never partially deleted either: it is reported as left alone and reclaimed at a later sweep once the agent is stopped.
  • The sweep of orphan folders is disabled when the app's project list cannot be read (missing, unreadable or empty): an unreadable list must not read as "no project". The retention rotation still runs.
  • A project created moments ago is protected for an hour even if it is not yet written to the project list, so it cannot be mistaken for an orphan.
  • The QA bot cleans its own conversation at the end of a run, never the shared QA folder of the project, which other QA runs and browser-enabled agents use.
  • Same behaviour on macOS, Windows and Linux; the folders live under the AgentsRoom data directory of the user.

Common questions

  • Why is my disk full of Codex sessions? Each project and each account had its own Codex folder and nothing cleaned them. Update to 1.184.0, open Settings > AI providers & accounts > Codex and click Reclaim disk space; the folders of deleted projects and removed accounts go first.
  • Will I lose a conversation I want to resume? No. A transcript a saved agent can still resume is kept whatever its age; a throwaway conversation older than the retention is deleted. Pick Forever to keep every transcript.
  • The button says "Nothing to reclaim." but the row still shows gigabytes. The data is younger than the retention, or it belongs to conversations of saved agents, or to a folder with a running agent. Lower Keep data for, or stop the agent and try again.
  • Does this touch my own ~/.codex? No. Only the folders AgentsRoom generates are measured and swept; the CLI's own home and the account directories you created are left alone.

Related