ai-cli-chat-search

跨 Codex / Claude Code / Kimi Code 三大 AI CLI 的会话历史统一搜索工具。 Unified chat history search across Codex / Claude Code / Kimi Code CLI tools.

零第三方依赖,只用 Python 标准库 + Tkinter。命令行 + 桌面 GUI 双形态。 Zero third-party dependencies — Python stdlib + Tkinter only. CLI + desktop GUI.

---

它解决什么问题 / Why this exists

中文: 如果你像我一样同时在用 Codex CLI、Claude Code 和 Kimi Code,会发现:每个工具的会话日志格式都不一样,分散在 ~/.codex、~/.claude、~/.kimi 三个目录,各自的 JSONL schema 也完全不同;想"找一周前那个聊 PDF 知识库的对话"基本只能靠记忆翻文件。本项目把三种 JSONL 统一转换成可读 markdown,然后用一个工具跨三端搜索 —— 文件名 slug + 全文 + 模糊匹配 + 日期过滤都支持。

English: If you use multiple AI CLI tools (Codex, Claude Code, Kimi Code), each stores its session logs in a different format under a different directory (~/.codex, ~/.claude, ~/.kimi) with completely different JSONL schemas. Finding "that conversation about PDF knowledge bases from last week" usually means digging through files by hand. This project converts all three JSONL formats into readable markdown and offers one search tool that ranks across all three corpora — filename slug match + full text + fuzzy + date filtering.

---

主要功能 / Features

• 🔍 跨三端统一搜索 / Cross-CLI search — 一次命令查 Codex + Claude + Kimi
• 🎯 AND 语义 + 模糊匹配 / AND tokens + fuzzy — 多关键词必须同时命中,支持拼写偏差
• 📅 日期范围过滤 / Date filter — --after 2026-04-15
• 🖥️ 桌面 GUI / Desktop GUI — 双击图标即开,Tkinter 标准库,无需 pip install
• 📂 回到原工作目录 / Jump back to cwd — 一键复制 cd 命令或直接在 cwd 启动 cmd
• 📝 JSONL → Markdown 转换器 / Converters — 工具调用、图片、长输出 sidecar 全部保留
• 🟦🟧🟩 来源徽标 / Source badges — 结果行直观显示来自哪个 CLI

---

支持的 CLI 工具 / Supported CLI Tools

CLI	原始数据 / Source	默认位置 / Default path
🟦 Codex	rollout-*.jsonl	~/.codex/sessions/**/
🟧 Claude Code	<uuid>.jsonl	~/.claude/projects/<cwd>/
🟩 Kimi Code	context.jsonl + state.json	~/.kimi/sessions/<hash>/<conv>/

---

与同类项目对比 / Comparison

项目 / Project	Codex	Claude Code	Kimi Code	GUI	中文友好
ai-cli-chat-search	✅	✅	✅	✅ Tkinter	✅
claude-code-log	❌	✅	❌	Web	⚠️
codex-cli-log-viewer	✅	❌	❌	Web	⚠️
其他单端工具 / Others	单一	单一	❌	多为 web	不一

核心差异 / Key differentiator: 目前没有任何已知工具支持 Kimi Code 会话搜索 —— 本项目是首个三合一。 No other tool currently supports Kimi Code session search — this is the first to cover all three.

---

安装 / Install

前置条件 / Requirements:

• Python ≥ 3.10(用到 PEP 604 str | None 等新语法 / uses PEP 604 type unions)
• Windows / macOS / Linux 均可(主要在 Windows 上测试 / primarily tested on Windows)

git clone https://github.com/SmallHorseBrother/ai-cli-chat-search.git
cd ai-cli-chat-search

(可选) Windows 桌面快捷方式 / Optional Windows shortcut:

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

---

使用 / Usage

第一步:把 JSONL 转换成 markdown / Step 1: Convert JSONL to markdown

(初次使用 + 之后想刷新索引时再跑 / run on first use, and again whenever you want a fresh index)

python converters\codex.py
python converters\claude.py
python converters\kimi.py

输出会写到各 CLI 自己的 sessions_md/ 子目录,例如 ~/.codex/sessions_md/<YYYY>/<MM>/<DD>/rollout-...md。 Output goes into each CLI's own sessions_md/ subdirectory.

第二步:搜索 / Step 2: Search

命令行 / CLI:

# 多关键词 AND 搜索(同时命中 slug 和正文)
# AND search across multiple tokens
python chat_search.py "知识库 PDF"

# 只在 Kimi 中搜
# Restrict to one CLI
python chat_search.py --cli kimi 抖音

# 只匹配文件名 slug
# Match filename slug only
python chat_search.py --name-only 飞书

# 只搜正文,不看文件名
# Body-only search
python chat_search.py --content-only api

# 模糊匹配(英文拼写错误更有效)
# Fuzzy (effective for English typos)
python chat_search.py --fuzzy "pf zhshk"

# 日期过滤
# Date filter
python chat_search.py --after 2026-04-15 --before 2026-05-01 ppt

# 只看前 5 条
python chat_search.py --limit 5 知识

桌面 GUI / Desktop GUI:

# 直接双击 chat_search_gui.pyw,或:
# Double-click chat_search_gui.pyw, or:
pythonw chat_search_gui.pyw

GUI 功能 / GUI features:

• 顶部:搜索框、CLI 下拉(全部/Codex/Claude/Kimi)、仅文件名/模糊匹配 复选、日期范围
• 列表:来源徽标 / 时间 / 得分 / slug / cwd
• 详情面板:完整路径、cwd、命中片段
• 按钮:📂 在 Explorer 显示 · 📝 打开 markdown · 📋 复制 cd 命令 · 📋 复制 cwd · 🚀 在该 cwd 启动 cmd

---

工作原理 / How it works

~/.codex/sessions/**/*.jsonl  ─┐
~/.claude/projects/**/*.jsonl  ├─> 三个 converters → 统一 markdown ─> chat_search.py 跨语料检索
~/.kimi/sessions/**/context.jsonl ─┘

Markdown 文件名格式 / Filename format: {prefix}-{YYYY-MM-DDTHH-MM-SS}-{first8uuid}--{slug}.md

其中 slug 由首条 user prompt(或 Kimi 的 custom_title)生成,这让"搜索词在标题里"成为强信号。 The slug is derived from the first user prompt (or Kimi's custom_title), making "query appears in slug" a strong ranking signal.

评分逻辑 / Scoring:

• slug 命中:每 token 5 分(模糊命中按 ratio 缩放)
• 正文命中:每 token min(count, 5) 分
• 所有 token 都命中 slug 时再 +5 分(强烈奖励"主题就是这个"的对话)

This rewards conversations whose topic matches the query, not just incidental mentions.

---

已知限制 / Caveats

• 假设各 CLI 的数据目录在默认位置 ~/.codex、~/.claude、~/.kimi。如果你改过 OPENAI_CODEX_HOME 等环境变量,需要相应改 chat_search.py 顶部的 ROOTS。 Assumes default data locations. If you've customized e.g. OPENAI_CODEX_HOME, edit the ROOTS list at the top of chat_search.py.
• 转换无增量逻辑 —— 每次全量重写。当前几百个会话耗时几十秒;数据量上千需要时可加 mtime 跳过。 Converters run a full rewrite each time. For a few hundred sessions this takes tens of seconds.
• 仅在 Windows 上日常测试。Linux/macOS 路径应能正常工作,但部分功能(如桌面快捷方式)是 Windows-only。 Primarily tested on Windows; Linux/macOS paths should work but the shortcut installer is Windows-only.

---

仓库布局 / Repository layout

ai-cli-chat-search/
├── chat_search.py             # CLI 搜索工具 / CLI search
├── chat_search_gui.pyw        # Tkinter GUI
├── sessions_md_lib.py         # 三个转换器共享的辅助库 / Shared converter helpers
├── converters/
│   ├── codex.py               # Codex JSONL → markdown
│   ├── claude.py              # Claude Code JSONL → markdown
│   └── kimi.py                # Kimi Code JSONL → markdown
└── scripts/
    └── install.ps1            # Windows 快捷方式安装 / Windows shortcut installer

---

贡献 / Contributing

欢迎 issue 和 PR,尤其是:

• 其他 AI CLI 工具(Cursor、Aider、Cline、Continue 等)的转换器
• macOS / Linux 上的桌面集成
• Web 版本

Issues and PRs welcome, especially:

• Converters for other AI CLI tools (Cursor, Aider, Cline, Continue, ...)
• macOS / Linux desktop integration
• A web frontend

---

License

MIT © 2026 SmallHorseBrother