Codex Thread Manager

简体中文文档

Local web UI for inspecting and managing Codex CLI thread history.

This is a zero-dependency Python backend with a Vue 3 + Tailwind frontend. It reads Codex's local state_5.sqlite index and session rollouts from your CODEX_HOME, then serves a browser-based management console on 127.0.0.1. Normal installation and usage do not require Node because the built frontend is shipped inside the Python package.

Screenshots

These screenshots use synthetic data and do not contain real Codex thread content.

Chinese UI is also available from Settings:

Features

• Vue 3 + Tailwind local management UI, shipped as static assets inside the Python package.
• Overview cockpit for recent threads, favorites, token/cache metrics, storage pressure, and dangerous-action entry points.
• Search workspace with fast search on the left and a full thread preview on the right.
• Threads table for advanced cross-directory management, filtering, sorting, archiving, deletion, and provider migration.
• Storage view for active sessions, archived sessions, key Codex directories, and database file sizes.
• Settings view for Chinese/English UI switching, sidecar status, index status, and metadata import/export.
• Browse Codex threads across directories.
• Search by title, note, tags, id, cwd, or first user message.
• Optionally scan visible chat text on demand without building a persistent full-history index.
• Filter by provider, state, cwd, and source.
• Sort the Manage table by updated time, created time, raw tokens, effective tokens, cached input, cache hit rate, rollout size, title, provider, state, favorite, tags, notes, and other fields.
• Mark favorite threads, add tags, and keep a private note per thread.
• Archive or unarchive single and selected threads, including moving rollout files between sessions/ and archived_sessions/.
• Migrate a thread's provider metadata when login/provider names change.
• Preview user and assistant chat messages from a thread rollout.
• Move deleted threads into a local trash folder before removing them.
• Restore deleted batches from local trash.
• Permanently purge trash batches and see how much disk space was released.
• Refresh manually.
• Export or import manager-owned metadata as JSON.

Requirements

• Python 3.10+
• A local Codex home directory containing state_5.sqlite

No Python packages are required.

Usage

Install from GitHub with pipx:

pipx install git+https://github.com/Popcornnnnnnnn/codex-thread-manager.git

Run the installed command:

codex-thread-manager

Install a local checkout:

pipx install .

Upgrade the GitHub-installed version:

pipx upgrade codex-thread-manager

You can also run the script directly from the project directory without installing it:

python3 codex_thread_manager.py

The server binds to 127.0.0.1:8780 by default. This project is intentionally kept on port 8780 for long-running launchd service and local development. If that port is occupied, the server exits with a bind error; stop the existing codex-thread-manager service instead of letting it drift to another port.

Use a custom Codex home:

python3 codex_thread_manager.py --codex-home ~/.codex

Use a custom port:

python3 codex_thread_manager.py --port 8780

Run the self-test:

python3 codex_thread_manager.py --self-test

Frontend Development

Running or installing the tool does not require Node. The built Vue 3 + Tailwind frontend is shipped with the Python package.

Only frontend changes require the frontend/ toolchain:

cd frontend
pnpm install
pnpm typecheck
pnpm test
pnpm build

pnpm build writes static assets to codex_thread_manager_static/static/, and the Python server serves / and /assets/* from that package directory.

Data Safety

The tool is local-only and does not send your data anywhere.

Write operations create backups under:

$CODEX_HOME/backups/thread-manager/

Deleted threads are copied to:

$CODEX_HOME/deleted_threads/

Manager-owned annotations are stored separately at:

$CODEX_HOME/thread-manager.sqlite

This sidecar database stores favorites, tags, notes, settings, and metadata audit records. It does not replace Codex's state_5.sqlite.

Trash batches can be permanently purged from the UI. Purging removes only the local trash batch; it cannot be restored afterward.

The manager modifies Codex's local metadata database and, for title/provider changes, selected JSONL rollout metadata. Archive and unarchive operations also move rollout files between Codex's active and archived session folders. Close active Codex sessions that are using the same thread before performing destructive operations.

Delete and Purge

Delete is not immediate permanent deletion. It moves the selected thread data into the local trash folder so the batch can be restored later from the Trash view.

Purge is permanent. It removes a batch that is already in local trash, does not scan active Codex data, and cannot be restored afterward.

Optional: Start on macOS Login

To start the manager automatically after login on macOS, use a user-level launchd service. Save a plist like this to:

~/Library/LaunchAgents/com.example.codex-thread-manager.plist

Replace /path/to/codex-thread-manager with your checkout path.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.codex-thread-manager</string>

  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/python3</string>
    <string>/path/to/codex-thread-manager/codex_thread_manager.py</string>
    <string>--host</string>
    <string>127.0.0.1</string>
    <string>--port</string>
    <string>8780</string>
  </array>

  <key>WorkingDirectory</key>
  <string>/path/to/codex-thread-manager</string>

  <key>RunAtLoad</key>
  <true/>

  <key>KeepAlive</key>
  <true/>

  <key>StandardOutPath</key>
  <string>/tmp/codex-thread-manager.out.log</string>

  <key>StandardErrorPath</key>
  <string>/tmp/codex-thread-manager.err.log</string>
</dict>
</plist>

Load the service:

launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.example.codex-thread-manager.plist
launchctl kickstart -k "gui/$(id -u)/com.example.codex-thread-manager"

Stop the service:

launchctl bootout "gui/$(id -u)/com.example.codex-thread-manager"

Privacy

Do not commit your real Codex data. In particular, keep these out of source control:

• state_*.sqlite*
• sessions/
• backups/
• deleted_threads/
• real .jsonl rollout files

See PRIVACY.md for the repository hygiene checklist.

Project Status

This is an unofficial local utility for Codex CLI history management. It is not affiliated with OpenAI.