Skip to content

GeniusDog/Codex-Session-Curator

BranchesTags

Repository files navigation

Codex 会话标题编辑器

Codex Session Curator

开发者：烛龙
主页：https://github.com/GeniusDog

如果这个工具对你有帮助，欢迎先点一个 Star 支持一下项目。这会让我更有动力继续把它打磨得更顺手。

一个用于管理本地 Codex 会话的小工具。它可以读取本机的 session_index.jsonl 和 sessions 目录，帮助你更轻松地完成会话命名、内容预览和无用记录清理。

image

中文说明

作者与版权

  • 开发者：烛龙
  • 主页：https://github.com/GeniusDog
  • 本项目界面、源码脚本、打包脚本与说明文档中均已加入作者信息，用于明确署名与知识产权归属。

为什么做它

当本地会话越来越多时，默认标题往往不够直观，很多历史记录也难以快速找回。这个工具的目标很简单：

  • 让你先看对话，再决定怎么命名
  • 让会话标题更统一、更适合搜索
  • 让不需要的会话可以直接清理掉

功能特性

  • 查看当前本地所有 Codex 会话
  • 同时展示“已入索引”和“未入索引”的 session
  • 点击会话后预览本地保存的用户与助手消息
  • 直接修改会话标题并保存回本地索引
  • 删除不需要的会话
  • 删除前自动备份索引文件
  • 支持打开索引目录和原始 session 文件
  • 支持 Windows EXE、Windows 源码、macOS 源码、macOS .app 打包

当前已提供的程序版本

Windows 已提供：

  • dist/Codex-Session-Curator.exe

macOS 已提供：

  • 启动编辑器_mac.command
  • 打包APP_mac.command

说明：

  • 我当前是在 Windows 环境下开发和打包，所以已经直接生成了 Windows EXE。
  • macOS 原生 .app 不能在 Windows 上直接交叉打包生成，所以这里提供的是 macOS 可运行脚本和 macOS 本地打包脚本。
  • 你把项目拷到一台 Mac 上后，可以直接运行源码版本，也可以在 Mac 上生成 .app。

运行环境要求

Windows EXE 运行

  • Windows
  • 目标电脑本地存在 Codex 数据目录
  • 默认读取当前用户目录下的： C:\Users\<你的用户名>\.codex

Windows 源码运行

  • Windows
  • Python 3
  • 本机存在 Codex 本地数据目录： C:\Users\<你的用户名>\.codex

macOS 源码运行

  • macOS
  • Python 3
  • 本机存在 Codex 本地数据目录
  • .codex 目录位于当前用户主目录下： ~/.codex

macOS .app 打包运行

  • macOS
  • Python 3
  • 可联网安装 PyInstaller
  • 在 Mac 上执行： 打包APP_mac.command

这个项目有哪些运行方式

当前一共有 4 种主要运行方式：

  1. Windows 直接运行 EXE
    双击 dist/Codex-Session-Curator.exe

  2. Windows 运行源码版本
    双击 启动编辑器.cmd 或执行 python app.py

  3. macOS 运行源码版本
    双击 启动编辑器_mac.command 或执行 python3 app.py

  4. macOS 打包成 .app 后运行
    在 Mac 上执行 打包APP_mac.command，生成 .app 再双击运行

如何启动

方式一：Windows 直接运行 EXE

双击：

  • dist/Codex-Session-Curator.exe

这个方式不依赖目标电脑额外安装 Python，更适合分发给其他 Windows 用户直接使用。

方式二：Windows 源码运行

双击：

  • 启动编辑器.cmd

或者在终端里运行：

python app.py

方式三：macOS 源码运行

双击：

  • 启动编辑器_mac.command

或者在终端里运行：

python3 app.py

方式四：macOS 打包 .app

在 Mac 上双击：

  • 打包APP_mac.command

或者手动执行：

python3 -m pip install pyinstaller --index-url https://pypi.org/simple
python3 -m PyInstaller --noconfirm --clean --windowed --name "Codex Session Curator" app.py

生成结果会在：

  • dist/Codex Session Curator.app

使用说明

  1. 打开工具后，左侧会显示当前扫描到的会话列表。
  2. 可以在顶部搜索框里按标题、Session ID 或时间筛选。
  3. 点击任意会话，右侧会显示会话信息、可编辑标题和对话预览。
  4. 修改标题后点击“保存修改”，会写回本地 session_index.jsonl。
  5. 如果某个会话不再需要，点击“删除会话”即可清理。
  6. 如果想查看底层文件，可以直接点“打开索引目录”或“打开会话文件”。

数据说明

工具默认会读取以下位置：

  • Windows 索引文件： C:\Users\<你的用户名>\.codex\session_index.jsonl
  • Windows 会话目录： C:\Users\<你的用户名>\.codex\sessions
  • macOS 索引文件： ~/.codex/session_index.jsonl
  • macOS 会话目录： ~/.codex/sessions
  • 备份目录： 当前用户主目录下的 .codex/session_index_backups

安全说明

  • 保存或删除前会自动备份索引文件
  • 删除会话时会先弹出确认框
  • 删除功能会移除索引记录，并尝试删除对应的本地 session 文件

代码结构说明

当前项目比较轻量，核心文件如下：

  • app.py 主程序入口，包含界面、数据读取、标题保存、会话删除、对话预览等主要逻辑。

  • 启动编辑器.cmd Windows 源码双击启动脚本。

  • 启动编辑器_mac.command macOS 源码双击启动脚本。

  • 打包EXE.cmd Windows EXE 打包脚本，内部调用 PyInstaller。

  • 打包APP_mac.command macOS .app 打包脚本，需要在 Mac 上执行。

  • Codex-Session-Curator.spec PyInstaller 自动生成的 Windows 打包配置文件。

  • dist/ 打包输出目录，保存生成的 EXE 或未来在 Mac 上生成的 .app。

app.py 内部模块划分

  • 数据路径常量 管理 .codex 相关目录位置。

  • SessionItem 会话数据结构，保存标题、时间、索引状态和本地文件路径。

  • 会话加载相关函数 负责从 session_index.jsonl 和 sessions 目录读取数据。

  • 保存与删除相关函数 负责写回索引、备份文件、删除本地 session 文件。

  • 对话解析与预览函数 负责从 session 日志中提取用户与助手消息。

  • SessionTitleEditor 主界面类，负责所有 UI 布局、按钮事件和交互逻辑。

适合谁

  • 经常使用 Codex，并且本地会话很多的人
  • 想整理历史对话、提升检索效率的人
  • 想把本地会话管理做得更清晰一点的人

开源支持

如果你觉得这个工具好用，欢迎：

  • 点一个 Star
  • 提交 Issue 反馈体验问题
  • 提交 PR 一起完善功能和界面

项目文件

  • app.py：主程序
  • 启动编辑器.cmd：Windows 双击启动源码入口
  • 启动编辑器_mac.command：macOS 双击启动源码入口
  • 打包EXE.cmd：Windows EXE 打包脚本
  • 打包APP_mac.command：macOS .app 打包脚本
  • dist/Codex-Session-Curator.exe：已生成的 Windows EXE
  • README.md：项目说明文档

English

Developer: 烛龙
Homepage: https://github.com/GeniusDog

If this tool helps you, please consider giving the project a Star. It really helps the project grow and motivates continued improvements.

This is a small desktop utility for managing local Codex sessions. It reads your local session_index.jsonl and sessions directory so you can rename sessions, preview conversation content, and clean up records you no longer need.

Author and Ownership

  • Developer: 烛龙
  • Homepage: https://github.com/GeniusDog
  • Author information has been added to the UI, source files, launcher scripts, packaging scripts, and documentation to clearly preserve attribution and ownership.

Why This Tool Exists

As your local Codex history grows, default titles become harder to understand and older sessions get difficult to find. This tool is built to solve that with a simple workflow:

  • Preview the conversation before naming it
  • Keep session titles more consistent and searchable
  • Remove sessions you no longer need

Features

  • View all local Codex sessions
  • Show both indexed and not-yet-indexed sessions
  • Preview saved user and assistant messages
  • Edit session titles and write them back to the local index
  • Delete unwanted sessions
  • Automatically back up the index before save or delete operations
  • Open the index folder and raw session files directly
  • Support Windows EXE, Windows source mode, macOS source mode, and macOS app packaging

Available Program Variants

Windows already includes:

  • dist/Codex-Session-Curator.exe

macOS support files included:

  • 启动编辑器_mac.command
  • 打包APP_mac.command

Notes:

  • This project is currently developed and packaged on Windows, so the Windows EXE is already generated.
  • A native macOS .app cannot be cross-built directly from Windows in a reliable way.
  • However, this repository now includes a macOS source launcher and a macOS packaging script, so you can run it or build the .app on a real Mac.

Requirements

Windows EXE

  • Windows
  • A local Codex data directory on the target machine
  • Default path: C:\Users\<your-username>\.codex

Windows Source Mode

  • Windows
  • Python 3
  • A local Codex data directory: C:\Users\<your-username>\.codex

macOS Source Mode

  • macOS
  • Python 3
  • A local Codex data directory: ~/.codex

macOS App Packaging

  • macOS
  • Python 3
  • Network access to install PyInstaller
  • Run: 打包APP_mac.command

Ways to Run This Project

There are currently 4 main ways to run this project:

  1. Run the Windows EXE directly
    Double-click dist/Codex-Session-Curator.exe

  2. Run the Windows source version
    Double-click 启动编辑器.cmd or run python app.py

  3. Run the macOS source version
    Double-click 启动编辑器_mac.command or run python3 app.py

  4. Build and run the macOS .app
    Run 打包APP_mac.command on macOS, then open the generated app bundle

How to Launch

Option 1: Run the Windows EXE

Double-click:

  • dist/Codex-Session-Curator.exe

This is the best option for distribution to Windows users because it does not require Python to be installed separately.

Option 2: Run from Windows source

Double-click:

  • 启动编辑器.cmd

Or run from a terminal:

python app.py

Option 3: Run from macOS source

Double-click:

  • 启动编辑器_mac.command

Or run from a terminal:

python3 app.py

Option 4: Build a macOS app

On a Mac, double-click:

  • 打包APP_mac.command

Or run manually:

python3 -m pip install pyinstaller --index-url https://pypi.org/simple
python3 -m PyInstaller --noconfirm --clean --windowed --name "Codex Session Curator" app.py

The output will be generated at:

  • dist/Codex Session Curator.app

How to Use

  1. Launch the tool and review the session list on the left.
  2. Use the search box to filter by title, Session ID, or timestamp.
  3. Click a session to inspect its metadata, editable title, and conversation preview.
  4. Click 保存修改 after editing a title to write it back to session_index.jsonl.
  5. Click 删除会话 if you want to remove a session you no longer need.
  6. Use 打开索引目录 or 打开会话文件 when you want to inspect the underlying files directly.

Data Locations

By default, the tool reads from:

  • Windows index file: C:\Users\<your-username>\.codex\session_index.jsonl
  • Windows session directory: C:\Users\<your-username>\.codex\sessions
  • macOS index file: ~/.codex/session_index.jsonl
  • macOS session directory: ~/.codex/sessions
  • Backup directory: .codex/session_index_backups under the current user's home directory

Safety Notes

  • The index file is backed up automatically before save or delete actions
  • Delete operations require confirmation
  • Deleting a session removes the index record and also attempts to remove the local session file

Code Structure

This project is intentionally lightweight. The main files are:

  • app.py The main application entry. It contains the UI, session loading, title saving, session deletion, and conversation preview logic.

  • 启动编辑器.cmd Windows source launcher.

  • 启动编辑器_mac.command macOS source launcher.

  • 打包EXE.cmd Windows EXE packaging script using PyInstaller.

  • 打包APP_mac.command macOS app packaging script to be executed on a real Mac.

  • Codex-Session-Curator.spec The PyInstaller spec file generated for Windows packaging.

  • dist/ The output directory containing the EXE and future macOS app build output.

app.py Breakdown

  • Path constants Define where .codex data is stored.

  • SessionItem The core data structure for each session.

  • Session loading functions Read data from the local index and session files.

  • Save and delete functions Write updated titles, back up the index, and remove local session files.

  • Preview parsing functions Extract user and assistant messages from local session logs.

  • SessionTitleEditor The main UI class that handles layout, events, and interactions.

Open Source Support

If you find this useful, feel free to:

  • Give the repo a Star
  • Open an Issue for bugs or ideas
  • Submit a PR to improve the tool

About

Codex 会话标题编辑器 / Codex Session Curator,兼容直接运行、windows的exe程序运行、苹果系统的运行软件。A desktop tool to rename, preview, organize, and delete local Codex sessions on Windows and macOS.

Resources

Readme
Activity

Stars

13 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages