kimi-recap

A session manager for the kimi-code CLI.

kimi vis is a great agent trace debugger (timeline, token usage, wire events). But when you want a user-management view — "which sessions exist, where did I leave off, how do these two branches differ" — it's the wrong shape. kimi-recap fills that gap.

It is strictly read-only against ~/.kimi-code/. It never writes, never modifies sessions. "Continue a session" is left to the official CLI — kimi-recap just points you at the right id.

Requirements

• Node.js >= 18
• kimi-code CLI with some session history under ~/.kimi-code/

Install

Option 1 — from npm (recommended)

npm install -g kimi-recap

This installs a standalone copy into your global node_modules. Upgrade later with npm update -g kimi-recap, remove with npm uninstall -g kimi-recap.

Option 2 — from source (for development)

git clone https://github.com/CacinieP/kimi-recap.git
cd kimi-recap
npm install && npm run build && npm link

npm link makes the global kimi-recap command a symlink into this clone's dist/ — it does not copy anything. Consequences:

• After editing the source, run npm run build and the global command picks it up immediately (no reinstall).
• Deleting or moving the clone breaks the global command.
• To detach, run npm unlink -g kimi-recap (or npm uninstall -g kimi-recap).

If you previously linked from source and now want the published package instead: npm unlink -g kimi-recap && npm install -g kimi-recap.

Verify

kimi-recap --help

Quick start

A typical "where was I?" workflow:

kimi-recap ls              # 1. find the session (note the short id, e.g. 44c1e738)
kimi-recap card 44c1e738   # 2. see its todo list — where work stopped
kimi -S session_44c1e738-e964-43d9-993c-5e35b42ae124   # 3. resume in kimi-code

A typical "compare two attempts" workflow:

kimi-recap tree                     # see the fork forest
kimi-recap diff 02b81334 d48715ca   # compare prompts & tool calls

Commands

kimi-recap ls (default command)

List sessions as a table, most recent first. Running bare kimi-recap is the same as kimi-recap ls.

short     updated             recs  title / workDir
────────────────────────────────────────────────────────
44c1e738  2026-07-28 22:25    4748  Pixie-Desktop 端侧日报…
                                    ↳ /Users/caciniep
02b81334  2026-07-28 21:00    2295  TeXada 建议…

Columns:

| Column | Meaning | |---|---| | short | first 8 chars of the session id — usable as <id> in card / diff | | updated | last activity time (local time) | | recs | number of records in the session's wire.jsonl (a rough size/activity indicator) | | title / workDir | session title (truncated to 48 chars), with the working directory on the line below |

Options:

| Option | Default | Description | |---|---|---| | -n, --limit <n> | 15 | how many sessions to show | | -a, --all | off | show every session (ignores --limit) |

kimi-recap card <id>

Show a session's task-progress resume card: the todo list from its last TodoWrite, so you can see exactly where work stopped — plus a ready-to-paste resume command.

session_44c1e738  Pixie-Desktop 端侧日报  (2026-07-28 22:25)
  /Users/caciniep
────────────────────────────────────────────────────────
  ✔  配置支持 vlm/text 双 base_url
  ✔  修正 download_models.sh 的 repo 名
  ⧗  模型下载完成（后台进行中）
  ○  启动双 llama-server 并跑 digest
  ○  跑 report 完成 e2e 验证
  ○  提交并推送
────────────────────────────────────────────────────────
  6 tasks: 2 done · 1 active · 3 pending

  resume: kimi -S session_44c1e738-e964-43d9-993c-5e35b42ae124

Status glyphs:

| Glyph | Meaning | |---|---| | ✔ (green) | done | | ⧗ (yellow) | in progress | | ○ (dim) | pending |

Notes:

• <id> accepts a short prefix (e.g. 44c1e738) — kimi-recap resolves it against the session index. Full session_… ids also work.
• If the session never used the todo tool, the card says No todo list found in this session. and still prints the resume hint.
• The resume: line is copied verbatim into the official CLI to continue the session.

kimi-recap tree

Show the fork/branch forest. Rebuilds parent-child edges from forkedFrom and parent_session_id in each state.json.

├─ 44c1e738  Pixie-Desktop…  [fork]  2026-07-28 22:25
│  └─ a1b2c3d4  experiment-v2…  2026-07-28 23:10
├─ 02b81334  TeXada 建议…  2026-07-28 21:00

Badges:

| Badge | Meaning | |---|---| | [fork] (yellow) | created by /fork inside kimi-code | | [child] (magenta) | created as an explicit child session (parent_session_id) |

Sessions that were never forked appear as a flat list — this reflects the true data state, not a bug. The view becomes a tree the moment you use /fork.

kimi-recap diff <a> <b>

Compare two sessions' activity — which prompts are shared or unique, and how tool-call counts differ. Both <a> and <b> accept short id prefixes.

diff  session_02b81334  ↔  session_d48715ca
────────────────────────────────────────────────────────
Prompts   (A:2  B:19)
  2 shared
  19 only in B:
    + …

Tool calls  (A:11  B:288)
  Bash     A:  8  B:212  +204
  Edit     A:  0  B: 20   +20

Reading the output:

• Prompts — user prompts are compared as a set. - lines (red) exist only in A, + lines (green) only in B; shared counts prompts present in both. This is the useful view for forked siblings: shared prompts are the common prefix, unique prompts are where the branches diverged.
• Tool calls — per-tool counts side by side, with the delta (B − A) on the right: green +n means B used it more, red -n means A used it more, = means equal.

Global options & environment

| Flag / variable | Description | |---|---| | --home <path> | Read from a different data dir instead of ~/.kimi-code (useful for tests/backups). Also settable via KIMI_CODE_HOME. | | KIMI_RECAP_DEBUG=1 | Print full stack traces instead of one-line errors. | | NO_COLOR | Standard convention — disables colored output. |

Errors are reported on stderr with the data dir path shown, and the exit code is non-zero — safe to use in scripts.

Visualization?

kimi-recap is deliberately a text-only CLI — no TUI, no web UI. The "visualization" is the formatted terminal output itself: the tree ASCII forest, the card status glyphs, and the diff +/- view. Everything is pipeable (kimi-recap ls | grep …) and script-friendly.

For an interactive, graphical trace view of a single session (timeline, token usage, wire events), use the official kimi vis — the two tools complement each other: kimi-recap answers "which session and where did I stop", kimi vis answers "what exactly happened inside it".

How it works

kimi-recap reads three things from ~/.kimi-code/:

| Source | Used for | |---|---| | session_index.jsonl | session discovery | | <session>/state.json | title, timestamps, forkedFrom, workDir | | <session>/agents/main/wire.jsonl | todo snapshots (tools.update_store), prompts (turn.prompt), tool calls (context.append_loop_event) |

The wire parser mirrors the official kimi vis wire-reader.ts: it streams line by line, skips malformed lines with a warning, and keeps unknown record types (never drops them). This makes it forward-compatible — a protocol bump (1.4 → 1.5) just means some records can't be interpreted, never a crash.

It does not depend on the private @moonshot-ai/transcript package (which isn't published to npm). Type names and field semantics are aligned with the upstream monorepo so the code can be lifted into a future PR without renaming.

Design principles

• Read-only. Never writes to ~/.kimi-code/.
• No reimplementation of "continue". Resume hints point at kimi -S <id>.
• Forward-compatible. Unknown wire types are tolerated, not fatal.
• No dependency on upstream private packages. Fully standalone and distributable.

Development

npm install
npm run dev        # tsup --watch
npm test           # vitest run
npm run typecheck  # tsc --noEmit
npm run build      # tsup → dist/

Layout:

src/cli.ts            command definitions (commander)
src/commands/         ls / card / tree / diff — one file each
src/data/             paths, session_index/state.json loading, wire.jsonl parser
tests/                wire parser tests (vitest)

License

MIT