ccthread: Instructions file for Claude Code

CLAUDE.md — ccthread

Context for future agents working in this repo. Reading the code is fine; reading this first will save you time.

Why this exists

Claude Code writes every session to ~/.claude/projects/<encoded-project>/<session-uuid>.jsonl. Raw JSONL is unreadable for agents and humans. ccthread turns any session (or any slice) into clean markdown and offers cross-project search. The six target use cases:

1. Finding things in past conversations
2. Learning from past mistakes
3. Reviewing/summarizing rounds of work for teammates
4. Finding answers or values discussed before
5. Reviewing conversations to create skills out of past processes (or enhance them)
6. Reviewing conversations to populate a project's CLAUDE.md

Stack & key decisions

• Bun + TypeScript. Chosen over C for portability, simplicity, and bun build --compile — which emits a single cross-platform binary with the Bun runtime embedded.
• Streaming everywhere. Real session files go up to 100+ MB / 35k lines. Never load a file whole. All parsing flows through src/parser/stream.ts which uses Bun.file().stream() + line splitter.
• Ship a compiled binary. Users get ccthread as a single executable; Bun isn't required at runtime.
• Plugin with a tiny dispatcher. The plugin repo stays ~few KB. plugin/bin/ccthread detects OS/arch on first run and downloads the matching release asset into ${CLAUDE_PLUGIN_DATA}/bin/, caches it, then execs it.
• No SQLite index in v1. Streaming scan is plenty fast (sub-second for find across 11k files on an M-series Mac). v2 can add bun:sqlite for offset caching.
• Thinking on by default. Agents reviewing past work usually want the reasoning. --no-thinking flips it off.
• Tool results truncated to 40 lines by default. --tool-details full shows everything; none hides them entirely.
• Pager is opt-in. Default is plain stdout (agent-friendly; humans can | less themselves).

Architecture

src/
  cli.ts                # citty-based entry; dispatches subcommands
  commands/             # one file per subcommand (projects, list, show, find, search, info, tools, stats, current)
  parser/
    stream.ts           # streaming line-by-line reader (never buffers whole files)
    types.ts            # discriminated types for every known log-line shape
    resolve.ts          # resolves tool_result overflow to sibling tool-results/*.txt
  format/
    markdown.ts         # canonical renderer; per-type rendering policy table lives here
    truncate.ts         # line truncation + image-block stripping
  util/
    current-session.ts  # three-tier detector for the "current" session keyword
    dates.ts            # --since/--until parsing
  paths.ts              # ~/.claude/projects resolution; project-name decode (lossy → fs-verified)
tests/
  fixtures/             # small crafted .jsonl files covering every message type we render
  *.test.ts             # unit + command-level tests (bun test)
.claude-plugin/marketplace.json   # makes the repo itself a marketplace
                                  # (`/plugin marketplace add jakemarsh/ccthread`)
plugin/
  .claude-plugin/plugin.json
  bin/ccthread          # POSIX dispatcher
  bin/ccthread.cmd      # Windows dispatcher
  bin/.ccthread-version # pinned binary version (bumped in lockstep with plugin.json)
  hooks/hooks.json      # SessionStart + SessionEnd wiring for the 'current' detector
  hooks/record-session.sh          # writes session id to $CLAUDE_PLUGIN_DATA/sessions/<claude-pid>.json
  hooks/cleanup-session.sh         # removes the file on session end
  skills/ccthread/SKILL.md
scripts/
  build-all.ts          # cross-compile every target