Thread Delivery Recovery

thread-delivery-recovery is a small, read-only compatibility plugin for Codex Desktop. It is intended for the narrow failure mode where a completed Codex turn is present in the local persisted thread history but the native thread projection omits its persisted items.

The plugin exposes two MCP tools:

• read_thread_safe — reads persisted turn items from the local thread-history database.

• wait_threads_safe — derives a completed-turn snapshot, latest assistant message, and latest tool marker from the same persisted sequence.

Why this exists

Long-running Codex work can be costly to reproduce. If the persisted turn still exists locally but a projection/read path returns an empty item list, this plugin provides a fail-closed recovery path instead of inventing missing content or rewriting Codex state.

This project was extracted from a real local recovery tool and then sanitized for public release. No real conversation data, thread IDs, databases, credentials, or private project files are included in this repository.

Related MCP server: Codex History Hub

Safety model

The implementation opens thread_history_1.sqlite with SQLite read-only mode, validates the expected schema before reading, and closes the database after each operation. It does not write SQLite, JSONL, prompts, model state, or the signed Codex installation.

It intentionally fails on an unsupported schema. That is preferable to silently interpreting a changed Codex storage format incorrectly.

Important: recovered thread content can itself be sensitive. The plugin runs locally, but any caller that forwards tool output to another process or model is responsible for that data flow.

Requirements

• A Codex Desktop installation that maintains the compatible local thread-history schema.

• Node.js 22.5 or newer (node:sqlite is used; Node.js 25 is the development baseline for this release).

Plugin layout

.codex-plugin/plugin.json   Codex plugin manifest
.mcp.json                   MCP server registration
server.mjs                  read-only recovery server
skills/thread-delivery-recovery/SKILL.md
                            usage guidance for Codex
test/server.test.mjs        synthetic regression tests

Development

No third-party runtime dependencies are required.

npm test

The tests create temporary synthetic SQLite databases. They do not read your real Codex history. The regression suite checks successful item recovery, wait snapshots, schema rejection, and that a recovery read leaves the fixture database byte-for-byte unchanged.

Using the plugin

Use this only as a fallback after the native Codex thread tools show the specific symptom described above. Enable the repository as a compatible local/personal Codex plugin source using the plugin mechanism available in your current Codex build; plugin-loading details can change between releases.

Then call read_thread_safe with the exact thread ID, or wait_threads_safe when a wait/snapshot result is required.

Compatibility and limitations

This project relies on a local Codex persistence schema and is therefore version-sensitive. A future Codex release may change table names, columns, item shapes, or plugin loading behavior. The server validates required columns and refuses unsupported schemas rather than guessing.

This tool is for recovery of data that is already persisted locally. It cannot reconstruct a turn that was never persisted, and it never fabricates missing messages.

Security

Please read SECURITY.md before reporting a problem involving real thread content. Never attach your thread_history_1.sqlite, session JSONL, API keys, authentication material, or private conversations to a public issue.

Contributing

Bug reports and focused compatibility fixes are welcome. See CONTRIBUTING.md.

License

MIT. See LICENSE.

Project status

Early public release (0.1.0). The scope is intentionally narrow: safe local recovery, not replacement of Codex's native thread APIs.

Codex is a product of OpenAI. This community project is independent and is not endorsed by or affiliated with OpenAI.