explaingit

liuyoumi/codex-history

★ 17TypeScriptAudience · developerComplexity · 2/5LicenseSetup · easy

TLDR

A command-line tool to safely browse, search, and delete local conversation history stored by the Codex AI coding tool, with confirmation prompts before any deletion and a compatibility checker for after Codex updates.

Mindmap

mindmap
  root((codex-history))
    Commands
      List conversations
      Search by keyword
      Delete by ID
      Clean orphaned data
    Safety
      Confirm before delete
      Cancel on ambiguity
      Doctor check
    Platforms
      macOS
      Windows
      Linux
    Audience
      Codex users
      Developers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Free up disk space by finding and safely deleting old Codex AI conversations you no longer need.

USE CASE 2

Search through past Codex sessions by keyword to locate a specific conversation.

USE CASE 3

Clean up leftover orphaned database entries after Codex conversations are removed, and see how much space will be recovered before confirming.

Tech stack

TypeScript

Getting it running

Difficulty · easy Time to first run · 5min
MIT licensed, use, copy, and modify freely including in commercial projects, just keep the copyright notice.

In plain English

codex-history is a command-line tool for browsing and deleting conversation history that the Codex AI coding tool stores locally on your computer. Codex saves past conversations as files on your machine, and over time these can pile up and take up disk space. This tool gives you a safe way to find specific conversations and remove them without accidentally deleting the wrong things. The main commands let you list your saved conversations, search them by keyword, and delete one or more by ID. Before any deletion happens, the tool shows you exactly what it found and asks you to confirm by typing a short code. If any of the targets you asked to delete cannot be uniquely identified or appear to be actively in use, the whole operation is cancelled rather than proceeding with a partial delete. There is also a cleanup command for orphaned data, which refers to leftover database entries and log records that no longer have a matching conversation file. The tool calculates how much disk space this orphan data is taking up and shows you the plan before asking for confirmation. A doctor command checks whether the current version of the tool understands the data format that your installed version of Codex is using. Since Codex updates can change the local file structure, running doctor after a Codex upgrade is recommended before doing any deletions. The tool works on macOS, Windows, and Linux. It only touches local files on your machine and has no effect on any server-side Codex history. After deleting conversations, restarting Codex Desktop is recommended so it picks up the changes from disk. The project is MIT licensed.

Copy-paste prompts

Prompt 1
Walk me through using codex-history to list all my saved Codex conversations, search for ones mentioning 'React hooks', and delete the ones I no longer need safely.
Prompt 2
How do I use codex-history to clean up orphaned data from Codex and see how much disk space I will recover before I confirm the deletion?
Prompt 3
After updating Codex to a new version, show me how to run the codex-history doctor command and what to do if it reports a data format mismatch.
Prompt 4
I want to delete all Codex conversation history older than a month. How do I use codex-history to identify and remove them without accidentally deleting the wrong files?
Open on GitHub → Explain another repo

← liuyoumi on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.