Disk Usage from Temp Files

Some users found many gigabytes of files named like responses-state.json.ocx.<pid>.<seq>.tmp in their opencodex home (~/.opencodex by default), growing after every reboot.

What these files are

opencodex keeps a continuation cache so previous_response_id chains survive a proxy restart. It writes that snapshot atomically: content goes to a temp file first, then replaces the real file in one step. That is what stops a crash mid-write from leaving a half-written snapshot.

The temp is normally removed the instant the swap completes. If the process dies between the two steps, the temp survives.

Each file can be up to 24 MB because the snapshot is rewritten whole, not appended to. A few hundred abandoned files therefore add up quickly.

They are cache, not durable state. Deleting them costs nothing except that in-flight conversation chains may re-send context once. No configuration, credentials, or history live in these files.

Why they could accumulate

A cleanup already existed, but it ran at one moment only: when a proxy loaded the continuation cache for the first time, which happens before that process writes anything. Two consequences followed.

A proxy that crashed and restarted swept too early to see the temp its predecessor had just left — there is a 15-minute grace period so a file being written right now is never touched — and it never looked again for the rest of its life. Each restart then added one more file.

Worse, the cleanup skipped any file whose owning process ID was still alive. After a reboot the operating system routinely reissues the same process IDs, so an old file could be permanently mistaken for one belonging to a running process. That is why the growth tracked reboots.

What opencodex does now

The cleanup repeats on the proxy’s normal background timer instead of running once at startup, so a running proxy reclaims abandoned files on its own. It also ignores the process-ID check for files older than the current boot, since no running process can own those.

The safety rules are unchanged: a file younger than 15 minutes is never removed, and the proxy never removes a file it is writing itself.

How often the snapshot is written

Writes are debounced, and the debounce is derived from the size of the last snapshot actually written: while that file is small the next write is scheduled about two seconds after a change, and once it is near the 24 MB bound the wait stretches to at most thirty seconds. A cache that has only just grown therefore still takes the short wait once — the longer cadence applies from the write after it. A flush is skipped only when this process already wrote the same bytes to the same file, that file still matches on disk, and — outside Windows — its mode is still owner-only. A fresh process rewrites an identical snapshot once, and a file whose contents or permissions changed underneath the proxy is rewritten through the hardening path rather than left alone.

Each ordinary background cadence performs at most one full atomic rewrite. If the continuation cache changes while that write is in progress, opencodex schedules one follow-up on the normal delayed cadence instead of rewriting the whole snapshot again immediately. Graceful shutdown keeps its bounded retry behavior after in-flight requests have drained so the final snapshot can catch up before the process exits.

Together these keep the write rate roughly flat as the cache grows, instead of re-serializing and replacing the whole file every two seconds.

A graceful shutdown flushes immediately rather than waiting out the timer, so the longer wait mainly widens the window in which a hard kill loses the most recent continuation entries — which are cache, as above. That flush is still a disk write and can fail like any other, so a shutdown on a full or read-only volume can lose the same entries.

Reclaiming files that already accumulated

If the proxy runs, this happens automatically within a minute or two.

If the proxy will not start — the case where the pile grows fastest — check and reclaim from the command line:

ocx doctor

The “Response-state temp files” section reports how many files are reclaimable and how much space they hold. It only reports; it changes nothing.

To actually remove them:

ocx doctor --reclaim-response-temps

Both commands work without a running proxy. Files currently locked by another process are reported rather than forced. They are retried on the next reclaim — automatically while the proxy is running, otherwise the next time you run this command.

If a very large backlog exceeds one pass, the command says how many files remain so you can run it again.

This covers response-state snapshot temps specifically. Other components write their own temp files with a similar name, and those are not touched here.