claude-code-resume

ccr — a fuzzy-search picker for resuming Claude Code sessions across every project.
ccc — the same picker with your OpenAI Codex sessions in it too.

Browse all your Claude Code sessions across every project in a fuzzy-search
menu, see a rich preview of each, then resume the one you want — ccr auto-cds
into the session's working directory and runs claude --resume for you. No more
hunting for which folder a conversation lived in.

Beyond the CLI's own sessions, it also lists Claude Desktop (Cowork)
conversations and sessions Claude has already cleaned up, shows the ports
and watchers your agents left running, and can resume with mobile Remote
Control. Use ccc to get Claude Code + Codex in one list.

⚙ processes running under your session projects (by CPU)
  :5173   PID 4242    12.5% CPU   200 MB  vite                        ~/code/acme-api  → http://localhost:5173
  -       PID 6060     1.0% CPU    80 MB  tsc --watch                 ~/code/acme-api
────────────────────────────────────────────────────────────────────────
Enter resume  ^R +remote  ^F fork  ^Y print cmd  │  sort ^T time ^O title ^G dir  │  Esc quit
^X show/hide expired sessions  │  Desktop sessions open as a fork
[time] ❯
 just now │ ⚙ Add JWT auth to the API gateway          │ ~/code/acme-api
   2m ago │   Fix flaky checkout integration test      │ ~/code/storefront
   1d ago │   Teach the team Claude Desktop features   │ Desktop · ~/code/handbook
  11d ago │   Set up the CI release pipeline           │ ~/code/infra
┌──────────────────────────────────────────────────────────┐
│ 📌 Add JWT auth to the API gateway                       │
│ 🕒 2026-06-20 14:08  (just now)                          │
│ 📁 /Users/you/code/acme-api                              │
│ 🔑 0a1b2c3d-4e5f-6789-abcd-ef0123456789                  │
│ 💬 last prompt: extract the token check into middleware  │
└──────────────────────────────────────────────────────────┘

(中文說明請見 下方。)

What's new in 0.4 — ccc lists Claude Code and Codex sessions together.
0.3 added the process pane, 0.2 added Desktop / expired sessions and fork.
See Releases.

Features

Sessions

• Cross-project — scans ~/.claude/projects/*/*.jsonl, every session, every folder.
• Your names first — titles prefer the name you gave a session (/rename, claude -n), then the AI-generated title, an older summary, or the first prompt.
• Claude Desktop sessions — Cowork sessions from the Desktop app show up in magenta (Desktop · <folder>). They open in the CLI as a fork (--fork-session), so the original stays untouched in Desktop.
• Expired sessions — Claude deletes transcripts idle for cleanupPeriodDays (default 30). Ctrl-X / ccr --expired lists the ones still in your prompt history, greyed out, with their first prompt. They can't be resumed.
• Retention warning — the header warns when cleanupPeriodDays is unset or under 90 days.
• Rich preview — title, timestamp, working directory, session id, and the last prompt.

Resuming

• One-key resume — Enter cd's into the project and runs claude --resume.
• Fork — Ctrl-F (or ccr --fork) resumes into a new session id with --fork-session, leaving the original untouched.
• Mobile handoff — Ctrl-R resumes with --remote-control so you can continue on the Claude mobile app / web.
• Quick resume — ccr --last / ccr -n N resume straight away without opening the menu.
• Print only — Ctrl-Y prints the cd … && claude --resume … command instead of running it.

Process pane

• What's still running — a pane above the session list shows processes still running under any session's directory, busiest first: listening ports an agent left up as demos (with a http://localhost:<port> link) and dev watchers like tsc --watch, with CPU, memory and project.
• Highlighted — yellow port, bright command, cyan project, green link, and red CPU once a process is at 50% or more.
• Marked sessions — sessions with something running get a ⚙, and resuming one prints its processes first.
• No noise — shells, coding agents themselves (claude, codex) and the MCP servers they start are left out; one row per process tree.

Codex (ccc)

• One list for both tools — Claude Code and Codex sessions side by side, with a leading claude / codex column you can filter on (^codex, ^claude) and Ctrl-A to cycle all / Claude / Codex. See ccc.

Everyday

• Live sorting — by time, title, or working directory; switch inside the menu without restarting.
• Color & alignment — recency-colored timestamps, CJK-width-aware columns that line up even with mixed Chinese/English titles.
• Bilingual UI — English / 繁體中文, auto-detected from $LANG.
• Fast — caches the parsed index and only re-reads sessions whose files changed.
• Zero config — a single self-contained Bash script. No daemon, no background process.

Requirements

• bash (3.2+, the macOS default works)
• fzf
• python3
• the claude CLI (to actually resume)
• lsof (optional, macOS default; for the process pane)
• the codex CLI (optional; only to resume Codex sessions from ccc)

Install

git clone https://github.com/kylinfish/claude-code-resume.git
cd claude-code-resume
./install.sh            # symlinks bin/ccr and bin/ccc into ~/.local/bin
./install.sh --tip      # also add a one-line startup hint to your shell rc

Or just drop bin/ccr anywhere on your PATH (and a ccc symlink to it if you use Codex).

Usage

ccr                      # all sessions, newest first
ccr .                    # only sessions whose cwd is under the current directory
ccr ~/code/myproject     # only sessions under a given directory
ccr --last               # resume the most recent session, no menu
ccr -n 2                 # resume the 2nd most recent session, no menu
ccr --last --fork        # fork the most recent session into a new session id
ccr --expired            # also list sessions Claude has already cleaned up
ccr -s title             # sort by title  (time | title | dir)
ccr --lang zh            # force Chinese UI (default: auto-detect from $LANG)
ccr --version            # print the version
ccr --help

In-menu keys

Remote Control requires a Claude Pro/Max/Team/Enterprise subscription, and
your machine must stay running and online — the phone/web is just a window into
the session that keeps running locally.

ccc — Claude Code + Codex

ccr only looks at Claude Code. ccc is the same script run under another
name: everything ccr does, plus your OpenAI Codex
sessions in the same list.

ccc                      # Claude Code + Codex sessions, newest first
ccc --last               # resume the most recent session of either tool
ccc --version            # ccc 0.4.0

codex  │   9m ago │   Fix the rate limiter                     │ ~/code/acme-api
claude │ just now │ ⚙ Add JWT auth to the API gateway          │ ~/code/acme-api
claude │   1d ago │   Teach the team Claude Desktop features   │ Desktop · ~/code/handbook

• A leading tool column says claude or codex. Because it is the first thing on each row, typing ^codex or ^claude in the search filters by tool (Desktop and expired sessions count as claude). The preview of a Codex row shows branch, model and token count.
• Enter runs codex resume <id>, Ctrl-F runs codex fork <id>, Ctrl-Y prints the command. Codex has no Remote Control, so Ctrl-R refuses with a message.
• Ctrl-A cycles the source filter: all → Claude → Codex.
• Only interactive threads are listed (cli / vscode source, not archived); subagent, review and MCP threads are skipped.
• Codex sessions are read from ~/.codex/state_*.sqlite (read-only). That index is internal and versioned, so ccc looks its columns up by name and falls back to the ~/.codex/sessions/**/rollout-*.jsonl files when it can't be used. Set CODEX_HOME to point elsewhere.
• The process pane covers Codex projects too, and never lists codex itself or the MCP servers it starts.

Environment variables

Scan path resolution: CCR_PROJECTS_DIR → $CLAUDE_CONFIG_DIR/projects → ~/.claude/projects.

How it works

Each Claude Code session is one .jsonl file under ~/.claude/projects/<slug>/.
ccr reads every file, pulling the title (your /rename name, then the
ai-title, an older summary, or the first user prompt), the last prompt, the
working directory (cwd), and the file's modification time. It renders an
aligned, colored list into fzf; the hidden columns feed the preview pane and
the final cd "$cwd" && claude --resume "$sessionId".

Claude Desktop Cowork sessions live under
~/Library/Application Support/Claude/local-agent-mode-sessions/: a
local_<id>.json metadata file (title, last activity, granted folders) next to
a sandbox folder holding the transcript. ccr resumes that transcript by path
with --fork-session, so the new conversation is saved as a normal CLI session
and Desktop's copy is never written to.

Claude Code deletes transcripts that have been idle for cleanupPeriodDays
(default 30). Their prompts stay in ~/.claude/history.jsonl, which is where the
expired rows come from. To keep sessions longer, add this to
~/.claude/settings.json:

{ "cleanupPeriodDays": 365 }

The process pane comes from one ps call plus lsof for listening TCP ports
and each candidate's working directory, cached for 5 seconds. A process is shown
when it listens on a port or runs a known dev command (vite, next, tsc, nodemon,
python, …) and its working directory is inside one of the listed sessions'
directories (the deepest one wins; $HOME and / never count). Shells, coding
agents and the MCP servers they start are skipped, and only one row is kept per
process tree, port holders first.

Sorting is done in the scan step, so the in-menu sort keys simply reload the
list. A small on-disk index cache (~/.cache/ccr) keyed by file modification
time means unchanged sessions are never re-parsed — startup stays fast even with
hundreds of sessions.

Releases

Full details are in the CHANGELOG.

License

MIT © 2026 kylinfish

中文說明

ccr 讓你在一個模糊搜尋選單裡瀏覽所有專案、所有 Claude Code 歷史對話，
看到每個 session 的摘要預覽，選定後自動 cd 到該專案目錄並 claude --resume，
不必再手動記哪段對話在哪個資料夾。

除了 CLI 本身的 session，也會列出 Claude Desktop（Cowork） 的對話與已被 Claude
清理的 session，顯示 agent 留在背景的 port 與 watcher，並可一鍵開啟手機遠端控制。
用 ccc 可以把 Claude Code + Codex 放在同一個列表。

0.4 新功能：ccc 同時列出 Claude Code 與 Codex 的 session。
0.3 加入 process 區，0.2 加入 Desktop／已清理的 session 與分支續接。
詳見 版本紀錄。

功能

需求

bash（3.2+）、fzf、python3、claude CLI；
lsof（選用，macOS 內建，用於 process 區）；codex CLI（選用，只有用 ccc resume Codex session 時需要）。

安裝

git clone https://github.com/kylinfish/claude-code-resume.git
cd claude-code-resume
./install.sh          # 連結 bin/ccr 與 bin/ccc 到 ~/.local/bin
./install.sh --tip    # 另外在 shell 啟動時加一行提示

也可以直接把 bin/ccr 放到任何 PATH 目錄下（有用 Codex 的話再建一個指向它的 ccc symlink）。

ccc：Claude Code + Codex

ccr 只看 Claude Code。ccc 是同一支腳本換個名字執行：ccr 的所有功能，再加上
OpenAI Codex 的 session，放在同一個列表。

codex  │   9 分鐘前 │   修 rate limiter                          │ ~/code/acme-api
claude │       剛剛 │ ⚙ Add JWT auth to the API gateway          │ ~/code/acme-api

用法

選單內快捷鍵

手機遠端控制需 Claude Pro/Max/Team/Enterprise 訂閱，且本機需持續開著並連網
（手機只是視窗，運算仍跑在你電腦）。

環境變數

掃描路徑優先序：CCR_PROJECTS_DIR → $CLAUDE_CONFIG_DIR/projects → ~/.claude/projects。

Claude Code 預設會刪除 30 天沒活動的對話。想保留更久，在 ~/.claude/settings.json 加上 "cleanupPeriodDays": 365。

運作原理

• CLI session：每個 Claude Code session 是 ~/.claude/projects/<slug>/ 底下的一個 .jsonl。ccr 讀出標題（你 /rename 的名字優先，其次 ai-title、summary、第一句 prompt）、最後一句 prompt、工作目錄與修改時間，交給 fzf 顯示；選定後執行 cd "$cwd" && claude --resume "$sessionId"。
• Desktop 對話：Cowork 對話在 ~/Library/Application Support/Claude/local-agent-mode-sessions/，local_<id>.json 存標題、最後活動時間與授權資料夾，旁邊的沙盒資料夾存對話紀錄。ccr 以對話檔路徑加 --fork-session 開啟，新對話存成一般 CLI session，Desktop 的原檔不會被寫入。
• 已清理的 session：對話紀錄被清理後，prompt 仍留在 ~/.claude/history.jsonl，已清理的列就是從這裡來的。
• Process 區：一次 ps，加上 lsof 取得 listen 的 TCP port 與工作目錄，快取 5 秒。有 listen port 或執行已知開發指令（vite、next、tsc、nodemon、python…），且工作目錄在某個 session 目錄底下的 process 才會列出（以最深的目錄為準；$HOME 與 / 不算）。不列 shell、coding agent 與它們啟動的 MCP server，同一個 process tree 只留一筆，有 port 的優先。
• 快取：依檔案修改時間快取索引（~/.cache/ccr），沒變動的 session 不重複解析，數百個 session 也能快速啟動。

版本紀錄

完整內容請見 CHANGELOG。

授權

MIT © 2026 kylinfish