{"id":49486306,"url":"https://github.com/jakemarsh/ccthread","last_synced_at":"2026-06-13T22:32:32.832Z","repository":{"id":353464551,"uuid":"1210783117","full_name":"jakemarsh/ccthread","owner":"jakemarsh","description":"Read, search, and have Claude summarize your Claude Code conversation logs from the CLI.","archived":false,"fork":false,"pushed_at":"2026-04-24T01:55:59.000Z","size":343,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T03:26:33.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jakemarsh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T18:49:54.000Z","updated_at":"2026-04-24T01:56:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jakemarsh/ccthread","commit_stats":null,"previous_names":["jakemarsh/ccthread"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jakemarsh/ccthread","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakemarsh%2Fccthread","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakemarsh%2Fccthread/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakemarsh%2Fccthread/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakemarsh%2Fccthread/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jakemarsh","download_url":"https://codeload.github.com/jakemarsh/ccthread/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakemarsh%2Fccthread/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34303280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-01T02:00:22.568Z","updated_at":"2026-06-13T22:32:32.823Z","avatar_url":"https://github.com/jakemarsh.png","language":"TypeScript","funding_links":[],"categories":["Productivity Tools"],"sub_categories":["Monitoring \u0026 Observability"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/github-hero.png\" alt=\"ccthread\" /\u003e\n\u003c/p\u003e\n\n# ccthread\n\nRead, search, and have Claude summarize your Claude Code conversation logs from the CLI.\n\nEvery Claude Code session gets saved as a `.jsonl` file in `~/.claude/projects/`. `ccthread` reads them and turns them into clean markdown, so you — or an agent — can actually do something with them.\n\n## Why\n\nInstall it as a Claude Code plugin and you can ask things like:\n\n\u003e *\"What did we decide about rate limits in that session last Thursday?\"*\n\n\u003e *\"Find the thread where we worked out the ACME setup and put what we learned in CLAUDE.md.\"*\n\n\u003e *\"Summarize my checkout flow work this week. I need to update the team.\"*\n\n\u003e *\"Make a skill out of the process we figured out for redacting test fixtures.\"*\n\n\u003e *\"What port did we land on for the local Stripe webhook?\"*\n\nClaude runs `ccthread find` / `search` / `show` and answers from the actual conversation content. You can also use the CLI yourself — it has a real `--help` and the usual flags.\n\n## Install\n\nPick whichever fits your setup. They're independent — you can do one, both, or neither and build from source.\n\n### Option A — Claude Code plugin\n\nUse this if you want Claude Code to call `ccthread` automatically when you ask about past conversations.\n\n```\n/plugin marketplace add jakemarsh/ccthread\n/plugin install ccthread@ccthread\n```\n\nThe repo doubles as its own marketplace. `add` registers it; `install` activates the skill. The first time Claude invokes `ccthread`, the plugin's dispatcher downloads the matching binary for your platform and caches it under `~/.claude/plugins/data/ccthread/`. No other setup needed.\n\n### Option B — standalone CLI on your PATH\n\nUse this if you want to run `ccthread` yourself in a shell (pipe it, script it, grep through it).\n\nmacOS / Linux:\n```sh\ncurl -fsSL https://raw.githubusercontent.com/jakemarsh/ccthread/main/install.sh | sh\n```\nDrops `ccthread` in `/usr/local/bin` (or `~/.local/bin` if the first isn't writable).\n\nWindows (PowerShell):\n```powershell\nirm https://raw.githubusercontent.com/jakemarsh/ccthread/main/install.ps1 | iex\n```\nDrops `ccthread.exe` in `%LOCALAPPDATA%\\Programs\\ccthread\\` and adds it to your user PATH.\n\n### Option A + B\n\nDoing both is fine and common. The plugin keeps its own cached binary (so it doesn't care whether `ccthread` is on your PATH), and you still get the CLI for your own shell work.\n\n### From source\n\n```sh\ngit clone https://github.com/jakemarsh/ccthread \u0026\u0026 cd ccthread\nbun install \u0026\u0026 bun test \u0026\u0026 bun run build\n./dist/ccthread --help\n```\n\n## TL;DR\n\n```sh\nccthread find \"stripe webhook\"            # which old thread discussed this?\nccthread show 2F0A28FA                    # read a session (paginated markdown)\nccthread show last                        # read the most recent session\nccthread show current                     # read THIS session (auto-detected)\nccthread search \"rate limit\" --window 2   # grep with surrounding context\nccthread list --project great-work --since 2026-04-01\nccthread info 2F0A28FA                    # metadata + token usage\nccthread tools 2F0A28FA                   # tool-call breakdown\nccthread stats --project great-work       # aggregate totals\nccthread projects                         # list every project\nccthread current                          # print the current session's id\n```\n\n`\u003cid\u003e` can be a UUID prefix (6+ hex chars, 8+ recommended), a file path, `last` / `latest`, or `current` (the session you're in right now, if ccthread is running inside Claude Code).\n\nEvery command supports `--json`, `--plain`, and `--help`.\n\n## Using it from Claude Code\n\nAfter `/plugin install ccthread`, the bundled skill tells Claude where past conversations live and when to reach for the CLI. It triggers on phrases like \"past conversation\", \"old thread\", \"last session\", \"summarize\", \"what did we decide\", \"remember when\", \"find where we talked about\". You can also just say \"use ccthread to...\".\n\n### Things it's good for\n\n**Recalling decisions and values.**\n\n\u003e What port did we use for the local Stripe webhook last time?\n\n→ `ccthread search \"stripe webhook\" --window 3` and quotes the relevant messages.\n\n**Finding an old session by topic.**\n\n\u003e Find the thread where we set up the ACME phone number.\n\n→ `ccthread find \"ACME\"`, picks the right session, then `ccthread show \u003cid\u003e`.\n\n**Writing a recap for a teammate.**\n\n\u003e Summarize my work on the checkout refactor this week. Under 200 words.\n\n→ `ccthread list --project \u003cname\u003e --since \u003cdate\u003e` to find the sessions, then `show` on each one, then Claude writes the recap from the rendered transcripts.\n\n**Learning from past mistakes.**\n\n\u003e Why did we roll back that migration two weeks ago?\n\n→ `ccthread search \"rollback\"` + `ccthread info \u003cid\u003e`, reads the transcript around the decision.\n\n**Turning a past process into a skill.**\n\n\u003e Go look at the long session where we figured out Sparkle deploys and turn it into a skill.\n\n→ `ccthread show \u003cid\u003e --no-thinking --tool-details none`, distills the steps, writes SKILL.md.\n\n**Seeding CLAUDE.md with project knowledge.**\n\n\u003e Look at my last month of sessions on great-work and pull conventions into CLAUDE.md.\n\n→ Iterates over `ccthread list` + `ccthread show`, commits new sections.\n\n**Looking up something from the current conversation.**\n\n\u003e Before we compacted, you said something useful about X — find it.\n\n→ `ccthread show current --before-last-compact` or `ccthread search \"X\" --session current --before-last-compact --window 3`. Works because Claude Code writes each session's transcript to disk as it goes, and ccthread can detect which session invoked it (via the parent `claude` process's argv, or the plugin's SessionStart hook for bare `claude` launches).\n\n**Answering questions across many sessions.**\n\n\u003e How often have I hit Overloaded errors this week?\n\n→ `ccthread stats --since \u003cdate\u003e` reports api_errors directly, or `ccthread search \"Overloaded\"` for per-match detail.\n\n`ccthread` itself is just the reader — the agent does the thinking, reading its output like it would a source file. Everything runs locally; nothing leaves your machine. Files are streamed, so a 100 MB session still returns page 1 in under a second.\n\n## Direct CLI use\n\nYou don't need Claude Code to use this. It's a proper Unix CLI.\n\n### `ccthread projects`\n\nLists every project under `~/.claude/projects/` with session counts and last-active date.\n\n### `ccthread list`\n\n| Flag | Meaning |\n|---|---|\n| `--project \u003cname\u003e` | Filter to one project (basename, decoded path, or on-disk name). |\n| `--since \u003cISO\u003e` | Only sessions modified on or after this ISO date. |\n| `--until \u003cISO\u003e` | Only sessions modified on or before this ISO date. |\n| `--limit N` | Cap sessions returned (default 50). |\n| `--sort recent\\|oldest\\|size` | Sort order (default `recent`). |\n\nColumns: short id · start date · #messages · duration · model · title. A `project` column shows up when the scope spans multiple projects.\n\n### `ccthread show \u003cid-or-path\u003e`\n\n| Flag | Meaning |\n|---|---|\n| `--page N` | 1-indexed page (default 1). |\n| `--per-page M` | Messages per page (default 50). |\n| `--from N --to M` | 0-indexed half-open range. |\n| `--no-thinking` | Hide thinking blocks. |\n| `--include-sidechains` | Inline subagent sidechain messages. |\n| `--tool-details full\\|brief\\|none` | Default `brief` (40-line truncation per tool result). `full` = untruncated. `none` = hide bodies. |\n| `--count-total` | Pre-scan for accurate \"Page N of M\" (one extra file read). |\n| `--verbose` | Show hook / progress / attachment lines too. |\n| `--utc` | UTC timestamps. |\n\n### What gets rendered\n\nReal log files contain a lot of bookkeeping that isn't useful for reading. `show` filters it down to the parts humans and agents care about, with `--verbose` and `--include-sidechains` to pull the rest in when you want them.\n\n**Shown by default**\n\n- 👤 **User messages** — regular text, images, tool-use requests\n- 🤖 **Assistant messages** — text, tool uses, with model + cache-hit token count in the header\n- 🧩 **Tool results** — attached under the preceding tool-use instead of rendering as a synthetic user message\n- ⚠️ **API errors** — status code + error message\n- **Context compaction** — rule + \"_Context compacted_\" where Claude Code compacted the session\n- **Local commands** — one-line note when you ran a slash command\n- **Scheduled task fires** — one-line note\n- **Permission mode changes** — inline \"_Permission mode → X_\"\n- 🔗 **PR links** — in the document header\n\n**Hidden by default** (use `--verbose` to see)\n\n- `progress` — hook execution progress (very noisy)\n- `attachment` — IPC metadata (tool lists, etc.)\n- `queue-operation` — background task bookkeeping\n- `turn_duration`, `bridge_status` — timing/transport internals\n- `agent-name`, `last-prompt`, `file-history-snapshot` — internal state\n\n**Hidden by default** (use `--include-sidechains` to see)\n\n- Any line where `isSidechain: true` — subagent threads\n\nImages are stripped to size labels (`[image: image/png, 124 KB]`). Base64 data never leaks into output. Long tool results that overflow to sibling `tool-results/\u003cid\u003e.txt` files get resolved inline.\n\n### `ccthread find \u003cquery\u003e`\n\nOne line per session that contains the keyword. Good for \"which old thread was X in?\".\n\n| Flag | Meaning |\n|---|---|\n| `--project \u003cname\u003e` | Limit to one project. |\n| `--limit N` | Max matching sessions (default 20). |\n| `--snippet-len N` | Snippet context length (default 60 chars). |\n\nSubstring match, case-insensitive.\n\n### `ccthread search \u003cquery\u003e`\n\nKeyword search with ±N messages of context around each hit. One section per session, each hit headed by `### Match: \"...\" @ msg N`.\n\n| Flag | Meaning |\n|---|---|\n| `--project \u003cname\u003e` | Scope to one project. |\n| `--session \u003cid\u003e` | Scope to one session. |\n| `--since \u003cISO\u003e` / `--until \u003cISO\u003e` | Date range. |\n| `--window N` | Messages before AND after each hit (default 2). |\n| `--limit N` | Max sessions (default 20). |\n| `--max-matches-per-session N` | Cap hits per session (default 5). |\n| `--regex` | Query is an ECMAScript regex. |\n| `--case-sensitive` | Case-sensitive match. |\n| `--role user\\|assistant\\|tool_use\\|tool_result\\|thinking\\|any` | Restrict matches by role. |\n| `--fields text,tool_use,tool_result,thinking` | Which content to search within (default: text,tool_use,tool_result). |\n| `--sort recent\\|oldest\\|hits` | Session ordering. |\n| `--include-sidechains` | Include subagent content. |\n| `--before-last-compact` | Only match against messages before each session's most recent `/compact`. |\n\n### `ccthread info \u003cid\u003e`\n\nQuick overview of one session — numbers and metadata, not a narrative. Covers: project, cwd, git branch, models used, start/end/duration, message counts per type, token totals (input / output / cache-hit / cache-create), tool-call breakdown, and interrupted/api-error/compact-boundary counts. For prose about what actually happened in a session, read the session with `ccthread show` or let Claude summarize it for you.\n\n### `ccthread tools \u003cid\u003e`\n\nTool-usage breakdown (Bash: 412, Edit: 203, …). `--top N` limits the list.\n\n### `ccthread stats`\n\nAggregates across many sessions. Scope with `--project`, `--since`, `--until`, or combine.\n\n| Flag | Meaning |\n|---|---|\n| `--project \u003cname\u003e` | Limit to one project. |\n| `--since \u003cISO\u003e` / `--until \u003cISO\u003e` | Date range. |\n| `--group-by project\\|day\\|model` | Markdown table broken down by the chosen key. |\n\nShows: session count, messages, total duration, role counts, token totals (with cache-hit percentage), top tools, top models, interrupted/api-error/compact-boundary counts.\n\n## Global options\n\n| Flag / env | Meaning |\n|---|---|\n| `--help`, `-h` | Usage for main or any subcommand. |\n| `--version`, `-v` | Print version. |\n| `--strict` | Exit on malformed JSON lines instead of warn + continue. |\n| `--silent` | Suppress stderr warnings. |\n| `--no-color` | Strip emoji from output. Keeps the rest of the markdown formatting (use `--plain` if you want code fences stripped too). |\n| `CCTHREAD_PROJECTS_DIR` | Override projects directory (default `~/.claude/projects`). |\n| `CCTHREAD_STRICT=1` | Same as `--strict`. |\n| `CCTHREAD_SILENT=1` | Same as `--silent`. |\n| `NO_COLOR` | Same as `--no-color` ([no-color.org](https://no-color.org)). |\n\nExit codes: `0` ok, `1` runtime error, `2` bad args, `3` session/project not found, `4` ambiguous session id.\n\n## Session identifiers\n\nAnywhere `\u003cid\u003e` is accepted you can pass:\n\n- A full UUID (`2F0A28FA-23B0-41ED-BF9C-2E13144B9BED`)\n- A hex prefix of 6+ characters (`2F0A28FA`). 8+ is recommended to avoid\n  ambiguous matches when you search across all projects.\n- A file path (absolute, `./relative`, or `~`-rooted).\n- `last` or `latest` for the most recently modified session anywhere.\n- `current` — the session that invoked ccthread. Detected in order: `CCTHREAD_SESSION_ID` env var → `--session-id` / `--resume` in an ancestor `claude` process's argv → a PID-keyed file written by the plugin's SessionStart hook. If none of those work, you'll get a clear error listing your options.\n\nAmbiguous prefix → exit 4 with a list of candidates.\n\n## How it works\n\n`ccthread` reads `~/.claude/projects/\u003cencoded-project\u003e/\u003cuuid\u003e.jsonl` files and streams them line-by-line. It never loads whole files, because some are 100+ MB. That means:\n\n- `show` returns page 1 in ~80 ms even on a 64 MB file.\n- `find` across 11,000+ sessions finishes in ~0.4 s.\n- Memory stays roughly constant regardless of file size.\n\nEvery recent log-line type is handled. Images stripped to size labels. Tool-result overflow files auto-resolved. All local.\n\n## Caveats\n\n- Your `.jsonl` files contain whatever you and your tools wrote — secrets included if they leaked into prompts or tool output. `ccthread` only reads locally, but piping output to somewhere else takes that content with it.\n- Project-name decoding is lossy (dash vs slash). We walk the filesystem to disambiguate; rare edge cases fall back to the naive decode.\n- No branch/DAG rendering yet. v0.1.0 renders messages in file order.\n\n## Roadmap\n\n- SQLite index for sub-second cross-project search.\n- `ccthread watch` for tailing active sessions.\n- Branch / DAG rendering.\n- HTML export.\n\n## License\n\nMIT © Jake Marsh\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakemarsh%2Fccthread","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakemarsh%2Fccthread","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakemarsh%2Fccthread/lists"}