csift

_{Pronounced "c-sift" (see-sift)}

The missing tool for Claude Code session transcripts.

search, recover, and audit any Claude Code session straight from the .jsonl logs.

──────────────────────────────────────────────────────────────────────────────
 ❯ what that session decide about rate limiting and wheres the code?
──────────────────────────────────────────────────────────────────────────────

⏺ Bash(csift search "rate limit" @13d9645a -t agent --since 1d)
  matches  1 exchange · 1 session · oldest first

  13d9645a·t42  2026-06-20 22:14:07.811 AEST(UTC+10)
    ▸ agent.message  L8821  Added a sliding-window limiter (10 req/min/IP); the 429 path now
                    returns Retry-After and logs the offending IP — gateway/src/rate_limit.rs:88.
  matched 1 exchange · 1 session · label=agent

One regex, the complete round-trip, token-efficient output. No embeddings, no database, no daemon.

Why csift

Claude Code's sessions are plain text in JSONL, so why csift, not grep?

Yes. It has every prompt, thought, tool call, file edit, pasted image, and subagent it spawned. But one of these may happen to you:

• "It deleted my project files, then apologized."

  Running --dangerously-skip-permissions, it wiped the files it had built, said sorry, and stopped dead. Asked to dig them back out of its own session, it fumbled around (the edits spanned subagents, every restore came back partial) and then quietly started rewriting them from memory as it panicked and decided that was "easier".

• "It lost my design images after a compaction, then asked me to re-send them."

  The images were right there in the conversation. One compaction later the agent acts like they never existed: the compaction handed it lossy text fragments instead, and it believed them.

• "Which session does jazzy-twilight-sparkle.md belong to?"

  The plan file carries the architecture that matters. Its invented name says nothing about which session wrote it, and the binding lives in an EnterPlanMode tool call, a needle in the haystack.

• "The machine crashed with three sessions open. Which was which?"

  Frontend, backend, debugging, and claude --resume gives you a lineup with no faces.

• "I literally just said that."

  A few compactions into a long run, the agent still knows its task. Everything you actually said and read is gone, and nothing keeps the last few turns mechanically the way codex or pi do.

• "I DID tell you. In the question dialog."

  It searched its own session by user roles, found nothing, and concluded you never said it. You said it in AskUserQuestion.

• "You're the orchestrator. Why can't you see which session is stuck?"

  Because, it explains, an unanswered AskUserQuestion is never written to disk at all, "so there's nothing I can watch." Or worse: "Yes, I can interpret it from the thinking."

Each of these ends the same way: the agent says You are absolutely right., then stumbles through a one-off script over raw JSON and gets it subtly wrong.

csift is the missing tool it should have had.

✨ Highlights

1. ⏪ Recover files & deleted plans.

   csift recover analyzes and aggregates every edit/read and restores the file's exact bytes, at any point in time, in diff patches or final files, and honors Claude Code's file-modified markers. When it can't reliably recover due to modified boundaries, it salvages what survived with gaps marked.

2. 🖼 Images back out.

   csift image lists, dedups, and extracts them, addressable by the same [Image #N] handle the session uses. (#N was never a unique id. csift copes.)

3. 📝 Plan ↔ Session matched.

   csift plan finds the plan a session wrote.
   csift plan --reverse jazzy-twilight-sparkle.md names the session that owns a file.
   Both directions.

4. 📇 Sessions you can tell apart.

   csift list identifies every session by its first and last messages.
   It is the completion claude --resume never had.

5. 🧵 Un-clip a compaction.

   A summary keeps task state and context. The conversation is a different axis, and csift verbatim reconstructs the clipped back-and-forth within a --budget. Wire it into a hook and every compaction arrives with the recent dialogue attached.

6. 🏷 Typed search.

   A background task's completion notice is a "user" role.
   A subagent's return: also "user".
   Your AskUserQuestion answer: a tool result.
   csift stepped in every one of these traps already, so csift search -t user.answer (one of 28 {role}.{class}.{sub} labels) finds exactly what a naive grep swears was never said.

7. 🛎 Pending questions, on the record.

   csift ships a hook that records AskUserQuestion / ExitPlanMode / MCP elicitations to a sidecar file, and every csift surface merges the unresolved ones in transparently. An orchestrator can finally see which session is stuck waiting on a human, and on what.

8. 🔎 Round-trips, not lines.

   A hit returns the whole exchange, rebuilt from the uuid/parentUuid graph: the matched tool call with its result, the user turn with the agent's reply. This is the context that grep or Claude's ad-hoc scripts can never reliably provide.

9. 🌳 Subagent topology.

   Kind, lifecycle, and the parent→child tree of every spawned agent, plus detection of lanes frozen on a pending permission approval.

10. 🤖 Designed for humans and LLMs.

    Output is terse, re-feedable, and even structural. Simply install the skill and your Claude will gain the power.

11. 🔒 Local, read-only, no magic.

    Pure regex. No embeddings, no index, no database, no daemon, no network, no telemetry, no hidden detections. It reads files already on your disk and never mutates your session histories.

12. ⚡ Rust + mmap + SIMD newline scan + byte prefilters + rayon.

    200 MB transcripts and multi-GB corpora in about a second, quick enough to call from inside a hook without noticing.

Install

cargo install csift

Requires Rust 1.89+. Or from source:

git clone https://github.com/wdhwg001/csift.git
cd csift
cargo install --path .        # builds the optimized binary and puts `csift` on your PATH
# …or just `cargo build --release` → ./target/release/csift

csift reads ~/.claude by default; point it elsewhere with --claude-home <DIR> or Claude Code's own $CLAUDE_CONFIG_DIR. csift <command> --help is the full manual.

Teach it to your agent

csift's primary user is the agent itself: output is terse, parseable, and every record carries a re-feedable handle. The skill teaches Claude Code when and how to reach for it:

npx skills add wdhwg001/csift

Quickstart

csift <command> [TARGET] [flags]. A target is a positional @<uuid> (a session), an @<agent-hex> (a subagent), a project path, or . (this cwd); omit it to scan every project.

Run csift <command> --help for the full flag set and examples.

The eleven subcommands

The summary is a selection. csift keeps the conversation.

When Claude Code compacts, it regenerates a dense summary: kilobytes standing in for dozens of compactions of history. It's a good selection. It keeps the key findings (what changed, with file:line) and often your standing directives verbatim. But it is a selection, re-abstracted every time, and the axis it optimizes is task continuation, not the conversation.

csift verbatim keeps the other axis: the verbatim User↔Agent exchange, what you actually said and what the agent actually reported back when it finished, with the hundreds of tool calls in between collapsed to a count. For the recent window that's tens of KB of full-fidelity dialogue where the summary kept a line or two. Not just your directive, but the agent's "validated against HEAD, the premise holds, here's the evidence" report-back, which a task-findings selection simply doesn't carry.

It doesn't replace the summary. It extends the post-compaction context with the recent conversation at full fidelity, budget-bounded and newest-first: it won't reach the oldest turns, and your never-compacted Plan file still owns the plan. Wire it into a SessionStart(compact) hook (see SKILL.md) and every compaction arrives with the recent verbatim conversation attached.

How it works

csift never loads a whole transcript when it doesn't have to: it mmaps each .jsonl, scans newlines with SIMD (memchr), runs a cheap byte/regex prefilter, and only serde_json-parses candidate lines; list reads just the head and tail; rayon fans out across files. The hard part isn't speed. It's the semantics of Claude Code's log: a role:"user" record is usually a tool result, not a human turn; a pending question is never written to disk; compaction has a specific shape; subagents sit flat on disk and their topology is reconstructed from the spawning tool call. All of it is documented, with the empirical grounding, in SPEC.md.

Documentation

There is none, in the human sense. This repository is written and maintained entirely by Claude Code, and the three reference files are the corpus the maintaining agent works from:

• SKILL.md: the usage reference an agent loads to operate csift.
• SPEC.md: design intent, record-model semantics, and the measurements behind the deep features.
• AGENTS.md: the repo operating manual. Architecture, jsonl domain knowledge, the quality gate.

They are dense, cross-referenced, and written for a model's attention, not yours. The practical way to understand this codebase as a human is to hand the repo to your own agent and ask for the tour: it reads these files well.

Contributing

An honest note first: csift's potholes are Claude's own, and I don't think fixing them should be a human's job. The intended path is to have Claude clone the repo and clean up after itself, then open the PR. From the PR onward, though, I expect a human who has read the code; if reviewing your PR would mean chatting with an AI, it should have been an Issue instead. Issues are genuinely welcome: describe the problem clearly and I'm happy to point my Claude at it.

The entire quality gate is one pre-commit hook (installed on your first cargo test): cargo fmt --check → cargo clippy --all-targets -D warnings → cargo test. Keep those green and you're set.

License

Released under the MIT license.