@halooojustin/cch 0.1.0

package/README.md

@@ -0,0 +1,186 @@
+# cch — Claude Code History
+
+AI-powered conversation history management for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Find any past conversation with natural language, resume it in a Zellij or tmux session — across all your projects.
+
+## The Problem
+
+Claude Code stores conversation history in `~/.claude/projects/`, scoped per directory. When you work across many repos:
+
+- `claude --resume` only shows history for the **current** directory
+- No way to search across all projects for a past conversation
+- Closing a terminal loses the active session
+- No global view of running Claude sessions
+
+## Install
+
+```bash
+npm install -g cch
+ch setup          # adds shell aliases (cn, cnf, cls, cps, chs)
+source ~/.zshrc   # or open a new terminal
+```
+
+### Claude Code Skill (optional)
+
+Install the skill so Claude Code knows how to use `ch` for you:
+
+```bash
+cp -r $(npm root -g)/cch/skill ~/.claude/skills/cch
+```
+
+Then you can just tell Claude Code things like "find my iOS debugging conversation" and it will use `ch` automatically.
+
+**Requirements:**
+- Node.js >= 18
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
+- [Zellij](https://zellij.dev/) or [tmux](https://github.com/tmux/tmux) (at least one)
+
+## Usage
+
+### Natural Language Search (the killer feature)
+
+Just describe what you remember. AI finds the session.
+
+```bash
+ch 上次帮我调试 iOS 的那个对话
+ch the one where I was deploying shrimp
+ch that donut wallet refactor
+```
+
+`ch` pipes your query + session list to `claude -p` (tries Haiku first for speed, falls back to default model), which returns the best matches. Pick one and it resumes in your multiplexer.
+
+### Commands
+
+```
+ch <description>              Natural language search (default)
+ch list [-n 20]               List recent sessions (interactive selector)
+ch search <keyword>           Exact keyword search in conversation content
+ch new [description]          New Claude session in current directory
+ch new -f [description]       Force new (kill existing same-name session)
+ch ls                         List active multiplexer sessions (interactive selector)
+ch attach <name>              Attach to a live session
+ch kill <name>                Kill a session
+ch resume <session-id>        Resume by session ID
+ch config                     Show configuration
+ch config set <key> <value>   Set a config value
+```
+
+### Interactive Selection
+
+Both `ch list` and `ch ls` feature an interactive selector:
+
+- **Up/Down arrows** or **j/k** — navigate the list
+- **Number keys** — type a number (e.g. `12`) then **Enter** to jump directly
+- **Enter** — confirm selection (resume session or attach to live session)
+- **Esc** or **q** — cancel
+
+CJK text is properly aligned with display-width-aware column padding.
+
+### Two-Level Resume
+
+**Level 1 — Live sessions:** Session still running in your multiplexer?
+
+```bash
+ch ls                    # interactive list — pick one to attach
+```
+
+**Level 2 — History resume:** Session ended, but you want to pick it back up?
+
+```bash
+ch 那个讨论登录bug的对话     # AI finds it
+# or
+ch list                      # interactive list — pick one to resume
+```
+
+Both levels open in a Zellij/tmux session, so you can detach and reattach anytime. All sessions launch via login shell (`zsh -lc`) to inherit your full environment and auth.
+
+### Session Management
+
+```bash
+# Start a new Claude session in current project
+ch new
+
+# With a description (shows up in ch ls and as Zellij tab name)
+ch new "fix authentication bug"
+ch new 修复登录bug              # Chinese descriptions work too
+
+# Force restart (kills existing session first)
+ch new -f "start fresh on auth"
+
+# See what's running (sorted by newest first)
+ch ls
+
+# Clean up
+ch kill ch-myproject-fix-auth
+```
+
+### Session Descriptions
+
+Descriptions you pass to `ch new` are used in multiple places:
+
+- **Zellij tab name** — visible in the tab bar when inside the session (supports Chinese)
+- **`ch ls` output** — shown next to the session name
+- **Session name** — English descriptions are included in the session name (e.g. `ch-infist-fix-login-bug`), Chinese descriptions use a hash fallback (e.g. `ch-infist-a1b2c3`) since Zellij session names don't support CJK
+
+## Configuration
+
+Config lives at `~/.config/cch/config.json`:
+
+```json
+{
+  "backend": "auto",
+  "claudeCommand": "claude",
+  "claudeArgs": ["--dangerously-skip-permissions"],
+  "historyLimit": 100
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `backend` | `"auto"` | `"auto"`, `"zellij"`, or `"tmux"` |
+| `claudeCommand` | `"claude"` | Path to Claude CLI |
+| `claudeArgs` | `["--dangerously-skip-permissions"]` | Default args for new sessions and resumed sessions |
+| `historyLimit` | `100` | Max sessions loaded for AI search |
+
+```bash
+ch config set backend tmux
+ch config set historyLimit 200
+```
+
+## Recommended Aliases
+
+Add to your `.zshrc` or `.bashrc`:
+
+```bash
+alias cn="ch new"
+alias cnf="ch new -f"
+alias cls="ch ls"
+alias chs="ch search"
+```
+
+Then use:
+
+```bash
+cn fix login bug        # new session with description
+cn 修复登录bug           # Chinese descriptions supported
+cnf                     # force restart current project session
+cls                     # interactive list of active sessions
+chs 龙虾                # keyword search
+```
+
+## How It Works
+
+1. **History scanning** — Reads `~/.claude/projects/**/*.jsonl`, extracts session metadata and first user messages. Results are cached (`~/.config/cch/cache.json`) by file mtime for fast subsequent lookups.
+
+2. **AI search** — Builds a text table of all sessions, sends it to `claude -p` (Haiku model preferred for speed, auto-fallback to default). Parses the response to find matching session numbers.
+
+3. **Multiplexer integration** — Creates named sessions in Zellij or tmux. For Zellij, generates temporary KDL layout/config files with `zsh -lc` to ensure full shell environment. For tmux, uses standard `new-session`/`attach` commands. Auto-detects which multiplexer is available (Zellij preferred).
+
+4. **Session naming** — Sessions are named `ch-<dirname>[-<description-or-hash>]`. English descriptions are slugified into the name; Chinese descriptions use an MD5 hash prefix. The `ch-` prefix makes them identifiable in `zellij ls` / `tmux ls`.
+
+5. **Session metadata** — Descriptions, cwd, and creation time are persisted in `~/.config/cch/sessions.json`, surviving reboots. Used by `ch ls` to display descriptions and sort by creation time.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,186 @@
+# cch — Claude Code History
+
+为 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 打造的 AI 对话历史管理工具。
+
+用自然语言找到任何一个过去的对话，在 Zellij 或 tmux 里恢复它——跨所有项目。
+
+## 痛点
+
+Claude Code 的对话历史存在 `~/.claude/projects/` 下，按项目目录隔离。当你同时在多个 repo 工作时：
+
+- `claude --resume` 只能看到**当前目录**的历史
+- 无法跨项目搜索某个对话
+- 关掉终端就丢失活跃会话
+- 没有全局视图查看正在运行的 Claude 会话
+
+## 安装
+
+```bash
+npm install -g cch
+ch setup          # 自动添加 shell 别名 (cn, cnf, cls, cps, chs)
+source ~/.zshrc   # 或新开终端
+```
+
+### Claude Code Skill（可选）
+
+安装 skill 后，Claude Code 就能自动帮你用 `ch` 命令：
+
+```bash
+cp -r $(npm root -g)/cch/skill ~/.claude/skills/cch
+```
+
+安装后直接对 Claude Code 说"帮我找之前调试 iOS 的对话"，它会自动调用 `ch` 搜索。
+
+**前置条件：**
+- Node.js >= 18
+- 已安装 [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- 已安装 [Zellij](https://zellij.dev/) 或 [tmux](https://github.com/tmux/tmux)（至少一个）
+
+## 使用方法
+
+### 自然语言搜索（核心功能）
+
+随便描述你记得的内容，AI 帮你找到对应的对话。
+
+```bash
+ch 上次帮我调试 iOS 的那个对话
+ch 帮我部署虾的那几个
+ch donut 钱包重构的那个
+```
+
+`ch` 会把你的描述和会话列表一起发给 `claude -p`（优先使用 Haiku 模型加速，失败自动回退到默认模型），返回最匹配的结果。选中后直接在终端复用器里恢复。
+
+### 命令一览
+
+```
+ch <描述>                     自然语言搜索（默认行为）
+ch list [-n 20]               列出最近的历史会话（交互式选择器）
+ch search <关键词>            精确关键词搜索对话内容
+ch new [描述]                 在当前目录新建 Claude 会话
+ch new -f [描述]              强制新建（先关闭同名旧会话）
+ch ls                         查看活跃的终端复用器会话（交互式选择器）
+ch attach <会话名>            连接到一个活跃会话
+ch kill <会话名>              关闭一个会话
+ch resume <session-id>        通过 session ID 恢复
+ch config                     查看配置
+ch config set <key> <value>   修改配置
+```
+
+### 交互式选择器
+
+`ch list` 和 `ch ls` 都支持交互式选择：
+
+- **上下箭头** 或 **j/k** — 导航选择
+- **数字键** — 输入数字（如 `12`）然后 **Enter** 直接跳转
+- **Enter** — 确认选择（恢复历史会话或连接活跃会话）
+- **Esc** 或 **q** — 取消退出
+
+中文文本使用显示宽度感知的列对齐，不会错位。
+
+### 两级恢复
+
+**第一级 — 活跃会话：** 会话还在终端复用器里运行？
+
+```bash
+ch ls                    # 交互式列表 — 选一个直接连接
+```
+
+**第二级 — 历史恢复：** 会话已结束，想重新捡起来？
+
+```bash
+ch 那个讨论登录bug的对话     # AI 帮你找
+# 或者
+ch list                      # 交互式列表 — 选一个恢复
+```
+
+两种方式都会在 Zellij/tmux 会话里打开，通过登录 shell（`zsh -lc`）启动以继承完整环境和认证信息。随时可以断开和重连。
+
+### 会话管理
+
+```bash
+# 在当前项目启动新的 Claude 会话
+ch new
+
+# 带描述（会显示在 ch ls 和 Zellij tab 名中）
+ch new "fix authentication bug"
+ch new 修复登录bug              # 支持中文描述
+
+# 强制重启（先关闭旧会话）
+ch new -f "重新开始搞认证"
+
+# 查看正在运行的会话（按创建时间倒序，最新的在最上面）
+ch ls
+
+# 清理
+ch kill ch-myproject-fix-auth
+```
+
+### 会话描述
+
+传给 `ch new` 的描述会用在多个地方：
+
+- **Zellij tab 名** — 进入会话后在 tab 栏可见（支持中文）
+- **`ch ls` 输出** — 显示在会话名旁边
+- **会话名** — 英文描述直接拼入会话名（如 `ch-infist-fix-login-bug`），中文描述使用哈希缩写（如 `ch-infist-a1b2c3`），因为 Zellij 会话名不支持 CJK 字符
+
+## 配置
+
+配置文件位于 `~/.config/cch/config.json`：
+
+```json
+{
+  "backend": "auto",
+  "claudeCommand": "claude",
+  "claudeArgs": ["--dangerously-skip-permissions"],
+  "historyLimit": 100
+}
+```
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `backend` | `"auto"` | `"auto"`、`"zellij"` 或 `"tmux"` |
+| `claudeCommand` | `"claude"` | Claude CLI 路径 |
+| `claudeArgs` | `["--dangerously-skip-permissions"]` | 新建会话和恢复会话时的默认参数 |
+| `historyLimit` | `100` | AI 搜索时加载的最大会话数 |
+
+```bash
+ch config set backend tmux
+ch config set historyLimit 200
+```
+
+## 推荐别名
+
+加到你的 `.zshrc` 或 `.bashrc`：
+
+```bash
+alias cn="ch new"
+alias cnf="ch new -f"
+alias cls="ch ls"
+alias chs="ch search"
+```
+
+然后使用：
+
+```bash
+cn fix login bug        # 带描述新建会话
+cn 修复登录bug           # 支持中文描述
+cnf                     # 强制重启当前项目会话
+cls                     # 交互式查看活跃会话
+chs 龙虾                # 关键词搜索
+```
+
+## 工作原理
+
+1. **历史扫描** — 读取 `~/.claude/projects/**/*.jsonl`，提取会话元信息和用户的前几条消息。按文件修改时间缓存到 `~/.config/cch/cache.json`，后续查询秒开。
+
+2. **AI 搜索** — 构建所有会话的文本列表，连同你的自然语言描述一起发给 `claude -p`（优先使用 Haiku 模型加速，自动回退到默认模型）。解析返回的编号找到匹配的会话。
+
+3. **终端复用器集成** — 在 Zellij 或 tmux 中创建命名会话。Zellij 通过生成临时 KDL 布局/配置文件，使用 `zsh -lc` 启动以确保完整的 shell 环境。tmux 使用标准的 `new-session`/`attach` 命令。自动检测可用的复用器（优先 Zellij）。
+
+4. **会话命名** — 格式为 `ch-<目录名>[-<描述或哈希>]`。英文描述会 slug 化拼入名称；中文描述使用 MD5 哈希前缀。`ch-` 前缀方便在 `zellij ls` / `tmux ls` 中识别。
+
+5. **会话元数据** — 描述、工作目录和创建时间持久化存储在 `~/.config/cch/sessions.json`，重启不丢失。`ch ls` 用它来显示描述和按创建时间排序。
+
+## 许可证
+
+MIT

package/bin/ch.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+await import("../dist/cli.js");