cc-history: browse and search Claude Code conversation history (Linux, macOS, Windows)

A developer released cc-history, a cross-platform Python 3.8+ command-line tool for browsing and searching Claude Code conversation history stored in the JSONL logs under ~/.claude/projects/. The utility offers session listing, plain-text, regex and typo-tolerant search, natural-language date filters, interactive pickers, and per-session views of tool calls, touched files and git commits, with shell completions for bash, zsh, fish and PowerShell.

| | /usr/bin/env python3 | | | """ | | | cc-history — Browse and search Claude Code conversation history. | | | | | | Works on Linux, macOS and Windows Python 3.8+ . Reads the JSONL logs that | | | Claude Code writes to ~/.claude/projects/ or $CLAUDE CONFIG DIR/projects/ . | | | | | | Examples: | | | cc-history summary dashboard for the current project | | | cc-history list sessions in the current project, newest first | | | cc-history list -g sessions across all projects | | | cc-history list -p myapp only projects whose name contains "myapp" | | | cc-history list -d "yesterday" natural-language date filters | | | cc-history list -d "past 3 days" | | | cc-history list -d "before may 5" | | | cc-history search "wifi reconnect" plain-text search | | | cc-history search "nmcli\|wifi" -E regex search | | | cc-history search reconect -F typo-tolerant search | | | cc-history search wifi -d "last week" -C 3 | | | cc-history read d31025da read a session prefix match OK | | | cc-history read interactive picker | | | cc-history read --fzf interactive picker using fzf | | | cc-history read d31025da --no-tools hide tool calls | | | cc-history read d31025da --all-tools every tool call with full input+output | | | cc-history read d31025da --ai just the last assistant message | | | cc-history read d31025da --git git commits made in the session | | | cc-history tools d31025da --summary tool/MCP call counts | | | cc-history files d31025da --code files the session touched | | | cc-history projects list all projects | | | cc-history stats stats per project | | | cc-history completions bash\|zsh\|fish\|powershell | | | """ | | | | | | import argparse | | | import json | | | import os | | | import re | | | import shlex | | | import shutil | | | import signal | | | import subprocess | | | import sys | | | import time | | | from collections import defaultdict | | | from datetime import datetime | | | from difflib import SequenceMatcher | | | from pathlib import Path | | | | | | try: | | | import curses not in the Windows stdlib; pip install windows-curses provides it | | | except ImportError: | | | curses = None | | | | | | IS WINDOWS = os.name == "nt" | | | | | | CLAUDE DIR = Path os.environ.get "CLAUDE CONFIG DIR" or Path.home / ".claude" .expanduser | | | PROJECTS DIR = CLAUDE DIR / "projects" | | | INDEX PATH = CLAUDE DIR / "cache" / "cc-history-index.json" | | | | | | Claude Code truncates long project dir names and appends a hash | | | MAX PROJECT NAME = 200 | | | | | | | | | def encode path p : | | | Claude Code names project dirs by replacing every non-alphanumeric char with '-' | | | "/home/me/my app" - "-home-me-my-app", "C:\\Users\\me" - "C--Users-me" | | | return re.sub r" ^A-Za-z0-9 ", "-", str p | | | | | | | | | def norm name name : | | | Windows paths are case-insensitive | | | return name.lower if IS WINDOWS else name | | | | | | | | | def cwd to project dir : | | | """Map the current working directory to the Claude project directory.""" | | | if not PROJECTS DIR.is dir : | | | return None | | | dirs = { norm name d.name : d for d in PROJECTS DIR.iterdir if d.is dir } | | | | | | Walk up parent dirs — Claude stores by project root, which may be a parent | | | cwd = Path.cwd .resolve | | | for p in cwd, cwd.parents : | | | name = norm name encode path p | | | if name in dirs: | | | return dirs name | | | if len name MAX PROJECT NAME: | | | for dname, d in dirs.items : | | | if dname.startswith name :MAX PROJECT NAME : | | | return d | | | return None | | | | | | ─── Colors ────────────────────────────────────────────────────────────────── | | | | | | def supports color : | | | if os.environ.get "NO COLOR" or not sys.stdout.isatty : | | | return False | | | if IS WINDOWS: | | | Turn on ANSI escape processing in the Windows console | | | try: | | | import ctypes | | | kernel32 = ctypes.windll.kernel32 | | | handle = kernel32.GetStdHandle -11 STD OUTPUT HANDLE | | | mode = ctypes.c uint32 | | | if not kernel32.GetConsoleMode handle, ctypes.byref mode : | | | return False | | | kernel32.SetConsoleMode handle, mode.value \| 0x0004 ENABLE VIRTUAL TERMINAL PROCESSING | | | except Exception: | | | return False | | | return True | | | | | | USE COLOR = supports color | | | | | | def c code, text : | | | if not USE COLOR: | | | return text | | | return f"\033 {code}m{text}\033 0m" | | | | | | def dim t : return c "2", t | | | def bold t : return c "1", t | | | def green t : return c "32", t | | | def cyan t : return c "36", t | | | def yellow t : return c "33", t | | | def magenta t : return c "35", t | | | def red t : return c "31", t | | | def blue t : return c "34", t | | | | | | ─── JSONL Parsing ─────────────────────────────────────────────────────────── | | | | | | def iter jsonl path : | | | with open path, "r", encoding="utf-8", errors="replace" as f: | | | for line in f: | | | line = line.strip | | | if not line: | | | continue | | | try: | | | yield json.loads line | | | except json.JSONDecodeError: | | | continue | | | | | | | | | def extract text content : | | | """Extract plain text from a message content field.""" | | | if isinstance content, str : | | | return content | | | if isinstance content, list : | | | parts = | | | for item in content: | | | if isinstance item, dict : | | | if item.get "type" == "text": | | | parts.append item.get "text", "" | | | elif item.get "type" == "tool use": | | | parts.append f" tool: {item.get 'name', '?' } " | | | elif item.get "type" == "tool result": | | | rc = item.get "content", "" | | | if isinstance rc, list : | | | for r in rc: | | | if isinstance r, dict and r.get "type" == "text": | | | parts.append r.get "text", "" | | | elif isinstance rc, str : | | | parts.append rc | | | return "\n".join parts | | | return "" | | | | | | | | | def strip system tags text : | | | """Remove <system-reminder , <command-name , etc.""" | | | text = re.sub r"<system-reminder . ?</system-reminder ", "", text, flags=re.DOTALL | | | text = re.sub r"<command-name . ?</command-name ", "", text, flags=re.DOTALL | | | text = re.sub r"<command-message . ?</command-message ", "", text, flags=re.DOTALL | | | text = re.sub r"<command-args . ?</command-args ", "", text, flags=re.DOTALL | | | text = re.sub r"<local-command-caveat . ?</local-command-caveat ", "", text, flags=re.DOTALL | | | text = re.sub r"<local-command-stdout . ?</local-command-stdout ", "", text, flags=re.DOTALL | | | return text.strip | | | | | | | | | def parse ts ts : | | | """Convert a record timestamp ISO string or epoch s/ms to epoch seconds.""" | | | if isinstance ts, int, float : | | | return ts / 1000 if ts 1e12 else ts | | | if isinstance ts, str : | | | try: | | | return datetime.fromisoformat ts.replace "Z", "+00:00" .timestamp | | | except ValueError: | | | return None | | | return None | | | | | | | | | label cache = {} | | | | | | def project label proj dir : | | | """Readable project name: the session's working dir relative to home. | | | | | | Dir names like '-home-me-my-app' are lossy '-' could have been '/', ' ', '.' , | | | so prefer the 'cwd' field recorded in the session logs. | | | """ | | | proj dir = Path proj dir | | | if proj dir in label cache: | | | return label cache proj dir | | | | | | label = proj dir.name | | | for jsonl file in sorted proj dir.glob " .jsonl" , key=lambda f: f.stat .st mtime, reverse=True : | | | cwd = None | | | for n, record in enumerate iter jsonl jsonl file : | | | cwd = record.get "cwd" | | | if cwd or n 50: | | | break | | | if cwd: | | | p = Path cwd | | | try: | | | label = p.relative to Path.home .as posix | | | label = "~" if label == "." else label | | | except ValueError: | | | label = p.as posix | | | break | | | | | | label cache proj dir = label | | | return label | | | | | | | | | ─── Session Discovery ────────────────────────────────────────────────────── | | | | | | def discover sessions project filter=None, project dirs=None : | | | """Yield session id, project label, path, title, timestamp tuples. | | | | | | project dirs: if set, only scan these specific directories. | | | project filter: substring filter on project label. | | | """ | | | if not PROJECTS DIR.exists : | | | return | | | | | | if project dirs is not None: | | | dirs to scan = d for d in project dirs if d.is dir | | | else: | | | dirs to scan = sorted PROJECTS DIR.iterdir | | | | | | for proj dir in dirs to scan: | | | if not proj dir.is dir : | | | continue | | | label = project label proj dir | | | if project filter and project filter.lower not in label.lower : | | | continue | | | | | | for jsonl file in sorted proj dir.glob " .jsonl" : | | | session id = jsonl file.stem | | | title = None | | | timestamp = None | | | has messages = False | | | | | | for record in iter jsonl jsonl file : | | | rtype = record.get "type" | | | if rtype == "ai-title" and record.get "aiTitle" : | | | title = record "aiTitle" | | | if rtype in "user", "assistant" and "message" in record: | | | has messages = True | | | Keep the latest timestamp, so sessions sort by last activity | | | ts = parse ts record.get "timestamp" | | | if ts is not None: | | | timestamp = ts | | | | | | if not has messages: | | | continue | | | | | | if timestamp is None: | | | timestamp = jsonl file.stat .st mtime | | | | | | if title is None: | | | for record in iter jsonl jsonl file : | | | if record.get "type" == "user" and "message" in record: | | | text = extract text record "message" .get "content", "" | | | text = strip system tags text .strip | | | if text and len text 5: | | | title = text :80 | | | break | | | | | | if title is None: | | | title = " untitled " | | | | | | yield session id, label, str jsonl file , title, timestamp | | | | | | | | | def find session file session prefix : | | | """Find a session file by prefix match.""" | | | for proj dir in PROJECTS DIR.iterdir : | | | if not proj dir.is dir : | | | continue | | | for jsonl file in proj dir.glob " .jsonl" : | | | if jsonl file.stem.startswith session prefix : | | | return jsonl file | | | return None | | | | | | | | | ─── Fuzzy Matching ────────────────────────────────────────────────────────── | | | | | | FUZZY THRESHOLD = 0.75 | | | | | | def fuzzy line matches needle, line : | | | """Return list of start, end spans in line that fuzzy-match needle.""" | | | needle lower = needle.lower | | | n = len needle lower | | | if n == 0: | | | return | | | | | | matches = | | | for m in re.finditer r" a-zA-Z0-9 +", line : | | | word = m.group .lower | | | if len word < 2: | | | continue | | | ratio = SequenceMatcher None, needle lower, word .ratio | | | if ratio = FUZZY THRESHOLD: | | | matches.append m.start , m.end | | | | | | return matches | | | | | | | | | def fuzzy text matches needle, text : | | | """Check if any line in text fuzzy-matches needle.""" | | | for line in text.split "\n" : | | | if fuzzy line matches needle, line : | | | return True | | | return False | | | | | | | | | def highlight fuzzy needle, text : | | | """Highlight fuzzy-matched spans in text.""" | | | lines = text.split "\n" | | | result = | | | for line in lines: | | | spans = fuzzy line matches needle, line | | | if not spans: | | | result.append line | | | continue | | | Build highlighted line from right to left to preserve indices | | | chars = list line | | | for start, end in sorted spans, reverse=True : | | | matched text = line start:end | | | chars start:end = bold red matched text | | | result.append "".join chars | | | return "\n".join result | | | | | | | | | ─── Date Filtering ────────────────────────────────────────────────────────── | | | | | | def parse date filter text : | | | """Parse a natural language date expression into a start ts, end ts range. | | | | | | Returns since ts, until ts — either may be None for open-ended. | | | Handles: | | | "two days ago" - that specific day | | | "may 5" - that specific day | | | "in the past two days" - from two days ago to now | | | "last week" - from one week ago to now | | | "past 3 days" - from 3 days ago to now | | | "since yesterday" - from yesterday to now | | | "before may 5" - everything before may 5 | | | """ | | | try: | | | import dateparser | | | except ImportError: | | | print "dateparser is required for natural-language dates: pip install dateparser", | | | file=sys.stderr | | | sys.exit 1 | | | | | | original = text.strip | | | lower = original.lower | | | | | | before prefix = re.match r'^before\s+', lower | | | if before prefix: | | | remainder = original before prefix.end : | | | parsed = dateparser.parse remainder | | | if not parsed: | | | print f"Could not parse date: '{original}'", file=sys.stderr | | | sys.exit 1 | | | return None, parsed.timestamp | | | | | | Detect range-style queries: "in the past X", "past X", "since X", "last N days" | | | range prefix = re.match | | | r'^ in the \| past\|since\|previous \s+', lower | | | | | | "last N <unit " is a range, but "last week"/"last month" are dateparser-native | | | last n prefix = re.match r'^ in the \| last\s+ ?=\d ', lower | | | | | | is range = bool range prefix or last n prefix | | | | | | if is range: | | | prefix = range prefix or last n prefix | | | remainder = original prefix.end : | | | parsed = dateparser.parse remainder or dateparser.parse remainder + " ago" | | | if not parsed: | | | print f"Could not parse date: '{original}'", file=sys.stderr | | | sys.exit 1 | | | return parsed.timestamp , None | | | | | | Try dateparser on the original — handles "last week", "two days ago", "yesterday", "may 5" | | | parsed = dateparser.parse original | | | if not parsed: | | | print f"Could not parse date: '{original}'", file=sys.stderr | | | sys.exit 1 | | | | | | Decide: range or exact day? | | | Phrases like "last week", "last month" are range-like everything since then | | | if re.match r'^last\s+ week\|month\|year ', lower : | | | return parsed.timestamp , None | | | | | | Otherwise treat as a specific day | | | day start = parsed.replace hour=0, minute=0, second=0, microsecond=0 | | | day end = day start.replace hour=23, minute=59, second=59 | | | return day start.timestamp , day end.timestamp | | | | | | | | | def filter sessions by date sessions, date expr : | | | """Filter sessions by a natural language date expression.""" | | | since ts, until ts = parse date filter date expr | | | filtered = | | | for s in sessions: | | | ts = s 4 | | | if ts is None: | | | continue | | | if since ts is not None and ts < since ts: | | | continue | | | if until ts is not None and ts until ts: | | | continue | | | filtered.append s | | | return filtered | | | | | | | | | ─── Interactive Picker ─────────────────────────────────────────────────────── | | | | | | def pick fzf items, format fn, preview cmd=None : | | | """Use fzf to pick from a list. Returns the selected item or None.""" | | | fzf path = shutil.which "fzf" | | | if not fzf path: | | | return None | | | | | | lines = format fn item for item in items | | | input text = "\n".join lines | | | | | | cmd = fzf path, "--ansi", "--no-sort", "--reverse", | | | "--header=Type to filter, Enter to select, Esc to cancel" | | | if preview cmd: | | | cmd.extend "--preview", preview cmd | | | | | | try: | | | env = dict os.environ, PYTHONIOENCODING="utf-8" for the preview subprocess | | | result = subprocess.run cmd, input=input text, capture output=True, text=True, | | | encoding="utf-8", errors="replace", env=env | | | except OSError, KeyboardInterrupt : | | | return None | | | | | | if result.returncode = 0 or not result.stdout.strip : | | | return None | | | | | | selected line = result.stdout.strip | | | for i, line in enumerate lines : | | | Strip ANSI for comparison | | | clean = re.sub r"\033\ 0-9; m", "", line | | | clean sel = re.sub r"\033\ 0-9; m", "", selected line | | | if clean == clean sel: | | | return items i | | | return None | | | | | | | | | def pick curses items, format fn : | | | """Pure-Python interactive picker using curses. Returns selected item or None.""" | | | if not items: | | | return None | | | | | | def run stdscr : | | | curses.curs set 1 | | | curses.use default colors | | | curses.init pair 1, curses.COLOR CYAN, -1 | | | curses.init pair 2, curses.COLOR YELLOW, -1 | | | curses.init pair 3, curses.COLOR BLACK, curses.COLOR WHITE | | | | | | query = "" | | | cursor = 0 | | | selected = None | | | | | | while True: | | | stdscr.clear | | | h, w = stdscr.getmaxyx | | | | | | Filter items | | | if query: | | | q = query.lower | | | filtered = i, item for i, item in enumerate items | | | if q in format fn item .lower | | | else: | | | filtered = list enumerate items | | | | | | cursor = max 0, min cursor, len filtered - 1 | | | | | | Header | | | header = f" cc-history picker {len filtered }/{len items } ─ type to filter, ↑↓ navigate, Enter select, Esc quit" | | | stdscr.addnstr 0, 0, header, w - 1, curses.A DIM | | | | | | Query line | | | prompt = f" {query}" | | | stdscr.addnstr 1, 0, prompt, w - 1 | | | | | | Items starting from row 3 | | | visible start = max 0, cursor - h - 4 | | | for row idx, fi in enumerate filtered visible start: : | | | row = row idx + 3 | | | if row = h - 1: | | | break | | | | | | idx, item = fi | | | line = format fn item | | | Strip ANSI codes for curses display | | | clean = re.sub r"\033\ 0-9; m", "", line | | | | | | abs idx = visible start + row idx | | | if abs idx == cursor: | | | stdscr.addnstr row, 0, f" ▸ {clean}", w - 1, curses.color pair 3 | | | else: | | | stdscr.addnstr row, 0, f" {clean}", w - 1 | | | | | | Position cursor at end of query | | | stdscr.move 1, min len prompt , w - 1 | | | stdscr.refresh | | | | | | try: | | | key = stdscr.get wch | | | except curses.error: | | | continue | | | | | | if isinstance key, str : | | | if key == "\x1b": Esc | | | return None | | | elif key == "\n" or key == "\r": | | | if filtered: | | | return filtered cursor 1 | | | return None | | | elif key in "\x7f", "\b" : Backspace | | | query = query :-1 | | | cursor = 0 | | | elif key == "\t": Tab = select | | | if filtered: | | | return filtered cursor 1 | | | return None | | | elif len key == 1 and key.isprintable : | | | query += key | | | cursor = 0 | | | elif isinstance key, int : | | | if key in curses.KEY ENTER, 459 : 459 = PADENTER in windows-curses | | | if filtered: | | | return filtered cursor 1 | | | return None | | | elif key == curses.KEY UP: | | | cursor = max 0, cursor - 1 | | | elif key == curses.KEY DOWN: | | | cursor = min len filtered - 1, cursor + 1 | | | elif key == curses.KEY BACKSPACE: | | | query = query :-1 | | | cursor = 0 | | | | | | try: | | | return curses.wrapper run | | | except KeyboardInterrupt, curses.error : | | | return None | | | | | | | | | def pick prompt items, format fn, page size=20 : | | | """Fallback picker without curses/fzf: numbered list + input .""" | | | query = "" | | | while True: | | | if query: | | | q = query.lower | | | filtered = item for item in items if q in format fn item .lower | | | else: | | | filtered = list items | | | for i, item in enumerate filtered :page size , 1 : | | | print f" {cyan f'{i:3d}' } {format fn item }" | | | if len filtered page size: | | | print dim f" ... {len filtered - page size} more, type text to filter" | | | try: | | | answer = input "Number to open, text to filter, empty to quit: " .strip | | | except EOFError, KeyboardInterrupt : | | | return None | | | if not answer: | | | return None | | | if answer.isdigit and 1 <= int answer <= min len filtered , page size : | | | return filtered int answer - 1 | | | query = answer | | | | | | | | | def interactive pick session sessions, use fzf=False : | | | """Pick a session interactively. Returns session id, label, path, title, ts or None.""" | | | if not sessions: | | | print "No sessions found.", file=sys.stderr | | | return None | | | | | | def fmt s : | | | sid, proj, path, title, ts = s | | | date str = datetime.fromtimestamp ts .strftime "%Y-%m-%d %H:%M" if ts else "????" | | | return f"{sid :8 } {date str} {proj} {title}" | | | | | | if use fzf and shutil.which "fzf" : | | | Re-invoke this script for the preview; fzf clips output to the pane | | | argv = sys.executable, os.path.abspath file | | | if IS WINDOWS: | | | prog = subprocess.list2cmdline argv | | | else: | | | prog = " ".join shlex.quote a for a in argv | | | return pick fzf sessions, fmt, preview cmd=f"{prog} read {{1}} --no-tools" | | | if use fzf: | | | print "fzf not found on PATH, using the built-in picker.", file=sys.stderr | | | if curses is not None and sys.stdin.isatty : | | | return pick curses sessions, fmt | | | return pick prompt sessions, fmt | | | | | | | | | ─── Commands ──────────────────────────────────────────────────────────────── | | | | | | def resolve project dirs args : | | | """Return project dirs list based on --global flag and cwd.""" | | | if getattr args, "glob", False or getattr args, "project", None : | | | return None scan all | | | proj dir = cwd to project dir | | | if proj dir: | | | return proj dir | | | return None cwd not in any project — fall back to all | | | | | | | | | def cmd list args : | | | project dirs = resolve project dirs args | | | sessions = list discover sessions project filter=args.project, project dirs=project dirs | | | sessions.sort key=lambda s: s 4 or 0, reverse=True | | | | | | if args.date: | | | sessions = filter sessions by date sessions, args.date | | | | | | if args.limit: | | | sessions = sessions : args.limit | | | | | | if args.json: | | | out = | | | for sid, proj, path, title, ts in sessions: | | | out.append { | | | "session id": sid, | | | "project": proj, | | | "title": title, | | | "timestamp": ts, | | | "date": datetime.fromtimestamp ts .isoformat if ts else None, | | | } | | | print json.dumps out, indent=2 | | | return | | | | | | if not sessions: | | | print "No sessions found." | | | return | | | | | | if args.pick: | | | picked = interactive pick session sessions, use fzf=args.fzf | | | if picked: | | | args read = argparse.Namespace session id=picked 0 , raw=False, no tools=True | | | cmd read args read | | | return | | | | | | for sid, proj, path, title, ts in sessions: | | | date str = datetime.fromtimestamp ts .strftime "%Y-%m-%d %H:%M" if ts else "unknown date" | | | short id = sid :8 | | | print f" {cyan short id } {dim date str } {dim ' ' + proj + ' ' } {title}" | | | | | | | | | def cmd search args : | | | use regex = args.regex | | | use fuzzy = args.fuzzy | | | if use regex: | | | try: | | | pattern = re.compile args.term, re.IGNORECASE | | | except re.error as e: | | | print f"Invalid regex '{args.term}': {e}", file=sys.stderr | | | sys.exit 1 | | | else: | | | term = args.term.lower | | | | | | date since, date until = None, None | | | if args.date: | | | date since, date until = parse date filter args.date | | | | | | Timeout: default 10s for fuzzy, 0 unlimited for exact/regex | | | timeout = args.timeout | | | if timeout is None: | | | timeout = 10 if use fuzzy else 0 | | | timed out = False | | | deadline = time.monotonic + timeout if timeout 0 else None | | | | | | results = | | | | | | project dirs = resolve project dirs args | | | if project dirs is not None: | | | dirs to scan = d for d in project dirs if d.is dir | | | else: | | | dirs to scan = sorted PROJECTS DIR.iterdir | | | | | | try: | | | for proj dir in dirs to scan: | | | if not proj dir.is dir : | | | continue | | | label = project label proj dir | | | if args.project and args.project.lower not in label.lower : | | | continue | | | | | | for jsonl file in proj dir.glob " .jsonl" : | | | if date since is not None or date until is not None: | | | file ts = jsonl file.stat .st mtime | | | if date since is not None and file ts < date since: | | | continue | | | if date until is not None and file ts date until: | | | continue | | | | | | session id = jsonl file.stem | | | title = None | | | messages = | | | | | | for record in iter jsonl jsonl file : | | | rtype = record.get "type" | | | if rtype == "ai-title" and record.get "aiTitle" : | | | title = record "aiTitle" | | | if rtype in "user", "assistant" and "message" in record: | | | text = extract text record "message" .get "content", "" | | | text = strip system tags text | | | For fuzzy mode, skip very large blocks tool output dumps | | | if use fuzzy and len text 5000: | | | text = text :5000 | | | role = record "message" .get "role", rtype | | | messages.append role, text | | | | | | for i, role, text in enumerate messages : | | | if deadline is not None and time.monotonic deadline: | | | raise TimeoutError | | | if use regex: | | | match found = pattern.search text | | | elif use fuzzy: | | | match found = fuzzy text matches args.term, text | | | else: | | | match found = term in text.lower | | | if match found: | | | lines = text.split "\n" | | | for li, line in enumerate lines : | | | if use regex: | | | line match = pattern.search line | | | elif use fuzzy: | | | line match = bool fuzzy line matches args.term, line | | | else: | | | line match = term in line.lower | | | if line match: | | | ctx start = max 0, li - args.context | | | ctx end = min len lines , li + args.context + 1 | | | snippet = "\n".join lines ctx start:ctx end | | | results.append { | | | "session id": session id, | | | "project": label, | | | "title": title or " untitled ", | | | "role": role, | | | "snippet": snippet, | | | "line": li, | | | } | | | except TimeoutError: | | | timed out = True | | | | | | if args.json: | | | print json.dumps results, indent=2 | | | return | | | | | | if not results: | | | print f"No results for '{args.term}'." | | | return | | | | | | seen sessions = set | | | for r in results: | | | sid = r "session id" :8 | | | header needed = sid not in seen sessions | | | seen sessions.add sid | | | | | | if header needed: | | | print | | | print f" {cyan sid } {dim ' ' + r 'project' + ' ' } {r 'title' }" | | | print f" {'─' 60}" | | | | | | role color = green if r "role" == "user" else yellow | | | snippet = r "snippet" | | | if use regex: | | | highlighted = pattern.sub lambda m: bold red m.group 0 , snippet | | | elif use fuzzy: | | | highlighted = highlight fuzzy args.term, snippet | | | else: | | | highlighted = re.sub | | | re.escape args.term , | | | lambda m: bold red m.group 0 , | | | snippet, | | | flags=re.IGNORECASE, | | | | | | for line in highlighted.split "\n" : | | | print f" {role color r 'role' + ':' } {line}" | | | | | | summary = f"{len results } match es across {len seen sessions } session s " | | | if timed out: | | | summary += f" timed out after {timeout}s — use --timeout N to increase " | | | print f"\n {dim summary }" | | | | | | | | | def cmd read args : | | | if not args.session id: | | | project dirs = resolve project dirs args | | | sessions = list discover sessions project dirs=project dirs | | | sessions.sort key=lambda s: s 4 or 0, reverse=True | | | use fzf = getattr args, "fzf", False | | | picked = interactive pick session sessions, use fzf=use fzf | | | if not picked: | | | return | | | args.session id = picked 0 | | | | | | path = find session file args.session id | | | if not path: | | | print f"No session found matching '{args.session id}'", file=sys.stderr | | | sys.exit 1 | | | | | | show git = getattr args, "git", False | | | show ai = getattr args, "ai", False | | | show human = getattr args, "human", False | | | show full = getattr args, "full", False | | | show all tools = getattr args, "all tools", False | | | | | | if show all tools and getattr args, "no tools", False : | | | print "--all-tools and --no-tools are mutually exclusive", file=sys.stderr | | | sys.exit 1 | | | | | | Git mode: show commits and exit | | | if show git: | | | commits = extract git commits path | | | if not commits: | | | print " No git commits found in this session." | | | return | | | print f"\n {bold 'Git commits' }" | | | print f" {'─' 40}" | | | for msg in commits: | | | print f" {msg}" | | | print | | | return | | | | | | Collect all messages for --ai / --human filtering | | | if show ai or show human: | | | records = | | | title = None | | | for record in iter jsonl path : | | | rtype = record.get "type" | | | if rtype == "ai-title" and record.get "aiTitle" and title is None: | | | title = record "aiTitle" | | | if rtype in "user", "assistant" : | | | records.append record | | | | | | proj = project label path.parent | | | if title: | | | print f"\n {bold title } {dim ' ' + proj + ' ' }" | | | print f" {dim path.stem }" | | | print f" {'━' 60}\n" | | | | | | target role = "assistant" if show ai else "user" | | | matching = r for r in records if r.get "message", {} .get "role", r.get "type" == target role | | | | | | if not matching: | | | print f" No {target role} messages found." | | | return | | | | | | Find the last message of that role with actual text content | | | record = None | | | text = "" | | | for r in reversed matching : | | | msg = r.get "message", {} | | | content = msg.get "content", "" | | | if show all tools: | | | candidate = extract all tools text content | | | elif show full: | | | candidate = extract text content | | | else: | | | candidate = extract clean text content | | | candidate = strip system tags candidate | | | if candidate.strip : | | | record = r | | | text = candidate | | | break | | | | | | if not record: | | | print f" No {target role} messages with content found." | | | return | | | | | | role color = green if target role == "user" else yellow | | | print role color f" {target role} " | | | for line in text.split "\n" : | | | print f" {line}" | | | print | | | return | | | | | | Default read mode | | | title = None | | | for record in iter jsonl path : | | | rtype = record.get "type" | | | | | | if rtype == "ai-title" and record.get "aiTitle" : | | | if title is None: | | | title = record "aiTitle" | | | proj = project label path.parent | | | print f"\n {bold title } {dim ' ' + proj + ' ' }" | | | print f" {dim path.stem }" | | | print f" {'━' 60}\n" | | | | | | if rtype not in "user", "assistant" : | | | continue | | | | | | msg = record.get "message", {} | | | role = msg.get "role", rtype | | | content = msg.get "content", "" | | | | | | if args.no tools and isinstance content, list : | | | content = | | | item for item in content | | | if isinstance item, dict and item.get "type" not in "tool use", "tool result" | | | | | | | | | if args.raw: | | | text = json.dumps content, indent=2 if not isinstance content, str else content | | | elif show all tools: | | | text = extract all tools text content | | | elif show full: | | | text = extract text content | | | text = strip system tags text | | | else: | | | text = extract clean text content | | | | | | if not text.strip : | | | continue | | | | | | role color = green if role == "user" else yellow | | | prefix = role color f" {role} " | | | print prefix | | | for line in text.split "\n" : | | | print f" {line}" | | | print | | | | | | | | | ─── File extension categories ─────────────────────────────────────────────── | | | | | | EXT CATEGORIES = { | | | "images": {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".svg", ".webp", ".ico", ".tiff"}, | | | "code": { | | | ".py", ".js", ".ts", ".tsx", ".jsx", ".c", ".cc", ".cpp", ".h", ".hpp", | | | ".rs", ".go", ".java", ".rb", ".sh", ".bash", ".zsh", ".lua", ".zig", | | | ".cs", ".swift", ".kt", ".scala", ".r", ".m", ".pl", ".php", ".ex", | | | ".html", ".css", ".scss", ".less", ".vue", ".svelte", | | | }, | | | "data": {".csv", ".tsv", ".json", ".jsonl", ".yaml", ".yml", ".xml", ".toml", ".ini", ".parquet", ".npy", ".npz"}, | | | "docs": {".md", ".txt", ".rst", ".tex", ".pdf", ".org", ".log"}, | | | "config": {".env", ".gitignore", ".dockerignore", ".editorconfig", ".prettierrc", ".eslintrc"}, | | | } | | | | | | Tools that run shell commands Claude Code on Windows can use PowerShell | | | SHELL TOOLS = "Bash", "PowerShell" | | | | | | | | | def categorize file filepath : | | | ext = os.path.splitext filepath 1 .lower | | | for cat, exts in EXT CATEGORIES.items : | | | if ext in exts: | | | return cat | | | return "misc" | | | | | | | | | def extract tool calls path : | | | """Extract all tool calls from a session JSONL. Returns list of dicts.""" | | | calls = | | | for record in iter jsonl path : | | | if record.get "type" = "assistant": | | | continue | | | content = record.get "message", {} .get "content", | | | if not isinstance content, list : | | | continue | | | for item in content: | | | if not isinstance item, dict or item.get "type" = "tool use": | | | continue | | | name = item.get "name", "?" | | | inp = item.get "input", {} | | | call = {"tool": name, "input": inp} | | | | | | if name in "Read", "Write", "Edit" : | | | call "file" = inp.get "file path", "" | | | elif name in SHELL TOOLS: | | | call "command" = inp.get "command", "" | | | | | | calls.append call | | | return calls | | | | | | | | | def cmd tools args : | | | """List tool/MCP calls made in a session.""" | | | path = find session file args.session id | | | if not path: | | | print f"No session found matching '{args.session id}'", file=sys.stderr | | | sys.exit 1 | | | | | | calls = extract tool calls path | | | | | | if args.mcp only: | | | calls = c for c in calls if c "tool" .startswith "mcp " | | | if args.no bash: | | | calls = c for c in calls if c "tool" not in SHELL TOOLS | | | | | | if args.json: | | | print json.dumps calls, indent=2 | | | return | | | | | | if not calls: | | | print " No tool calls found." | | | return | | | | | | Group and display | | | tool counts = defaultdict int | | | for c in calls: | | | tool counts c "tool" += 1 | | | | | | if args.summary: | | | print f"\n {bold 'Tool call summary' }" | | | print f" {'─' 40}" | | | for tool, count in sorted tool counts.items , key=lambda x: -x 1 : | | | is mcp = tool.startswith "mcp " | | | label = magenta tool if is mcp else cyan tool | | | print f" {count:4d}x {label}" | | | print f"\n {dim f'{len calls } total calls' }" | | | return | | | | | | for c in calls: | | | tool = c "tool" | | | is mcp = tool.startswith "mcp " | | | label = magenta tool if is mcp else cyan tool | | | | | | detail = "" | | | if "file" in c: | | | detail = dim c "file" | | | elif "command" in c: | | | cmd = c "command" :100 .split "\n" 0 | | | detail = dim cmd | | | elif is mcp: | | | inp str = json.dumps c "input" | | | if len inp str 100: | | | inp str = inp str :100 + "..." | | | detail = dim inp str | | | | | | print f" {label} {detail}" | | | | | | print f"\n {dim f'{len calls } total calls' }" | | | | | | | | | def cmd files args : | | | """List files accessed in a session, categorized by type.""" | | | path = find session file args.session id | | | if not path: | | | print f"No session found matching '{args.session id}'", file=sys.stderr | | | sys.exit 1 | | | | | | calls = extract tool calls path | | | | | | files by cat = defaultdict lambda: defaultdict set cat - {filepath - set operations } | | | | | | for c in calls: | | | tool = c "tool" | | | Only Read/Write/Edit; file paths inside shell commands can't be extracted reliably | | | if tool in "Read", "Write", "Edit" : | | | fp = c.get "file", "" | | | if not fp: | | | continue | | | cat = categorize file fp | | | op = tool.lower | | | files by cat cat fp .add op | | | | | | Apply category filters | | | selected cats = set | | | if args.images: selected cats.add "images" | | | if args.code: selected cats.add "code" | | | if args.data: selected cats.add "data" | | | if args.docs: selected cats.add "docs" | | | if args.config: selected cats.add "config" | | | if args.misc: selected cats.add "misc" | | | | | | if not selected cats: | | | selected cats = set EXT CATEGORIES.keys \| {"misc"} | | | | | | if args.json: | | | out = {} | | | for cat in sorted files by cat : | | | if cat not in selected cats: | | | continue | | | out cat = {fp: sorted ops for fp, ops in files by cat cat .items } | | | print json.dumps out, indent=2 | | | return | | | | | | total = 0 | | | for cat in "images", "code", "data", "docs", "config", "misc" : | | | if cat not in selected cats or cat not in files by cat: | | | continue | | | entries = files by cat cat | | | cat color = {"images": magenta, "code": cyan, "data": yellow, "docs": green, "config": dim, "misc": dim} | | | color fn = cat color.get cat, dim | | | print f"\n {bold color fn cat.upper } {len entries } files " | | | for fp, ops in sorted entries.items : | | | ops str = ",".join sorted ops | | | print f" {dim f' {ops str} ' :20s} {fp}" | | | total += 1 | | | | | | print f"\n {dim f'{total} files across {len c for c in files by cat if c in selected cats } categories' }" | | | | | | | | | def extract messages path : | | | """Extract all user/assistant messages from a session. Returns list of role, text tuples.""" | | | messages = | | | for record in iter jsonl path : | | | if record.get "type" not in "user", "assistant" : | | | continue | | | msg = record.get "message", {} | | | role = msg.get "role", record "type" | | | text = extract text msg.get "content", "" | | | text = strip system tags text | | | if text.strip : | | | messages.append role, text | | | return messages | | | | | | | | | def extract git commits path : | | | """Extract git commit messages from Bash tool calls in a session.""" | | | commits = | | | calls = extract tool calls path | | | for c in calls: | | | if c "tool" not in SHELL TOOLS: | | | continue | | | cmd = c.get "command", "" | | | if "git commit" not in cmd: | | | continue | | | Extract the commit message from a bash HEREDOC, a PowerShell here-string, or -m "..." | | | m = re.search r'git commit. ?-m\s+"?\$\ cat <<\'?EOF\'?\n . ? \nEOF', cmd, re.DOTALL | | | if m: | | | commits.append m.group 1 .strip .split "\n" 0 | | | continue | | | m = re.search r'git commit. ?-m\s+@ \'" \r?\n . ? \r?\n \'" @', cmd, re.DOTALL | | | if m: | | | commits.append m.group 1 .strip .split "\n" 0 | | | continue | | | m = re.search r'git commit. ?-m\s+" ^" + "', cmd | | | if m: | | | commits.append m.group 1 .strip .split "\n" 0 | | | continue | | | m = re.search r"git commit. ?-m\s+' ^' + '", cmd | | | if m: | | | commits.append m.group 1 .strip .split "\n" 0 | | | return commits | | | | | | | | | def truncate text, max len, suffix="..." : | | | """Truncate text to max len, appending suffix and char count if truncated.""" | | | if len text <= max len: | | | return text | | | remaining = len text - max len | | | return text :max len + f"{suffix} +{remaining} chars " | | | | | | | | | def extract clean text content : | | | """Extract text from message content, replacing file diffs with placeholders.""" | | | if isinstance content, str : | | | return strip system tags content | | | if not isinstance content, list : | | | return "" | | | parts = | | | for item in content: | | | if not isinstance item, dict : | | | continue | | | itype = item.get "type", "" | | | if itype == "text": | | | parts.append item.get "text", "" | | | elif itype == "tool use": | | | name = item.get "name", "?" | | | inp = item.get "input", {} | | | if name in "Read", "Write", "Edit" : | | | fp = inp.get "file path", "" | | | parts.append f" {name.lower }: {fp} " | | | elif name in SHELL TOOLS: | | | cmd = inp.get "command", "" .split "\n" 0 :80 | | | parts.append f" {name.lower }: {cmd} " | | | elif name.startswith "mcp " : | | | parts.append f" mcp: {name} " | | | else: | | | parts.append f" {name} " | | | elif itype == "tool result": | | | rc = item.get "content", "" | | | rc text = "" | | | if isinstance rc, str : | | | rc text = rc | | | elif isinstance rc, list : | | | rc text = " ".join | | | r.get "text", "" for r in rc | | | if isinstance r, dict and r.get "type" == "text" | | | | | | Detect file diffs/contents and replace with placeholder | | | lines = rc text.split "\n" | | | if len lines 10 and any l.startswith "---", "+++", "@@", "diff " for l in lines :5 : | | | parts.append f" diff output, {len lines } lines " | | | elif len lines 15: | | | parts.append f" output, {len lines } lines " | | | elif rc text.strip : | | | parts.append rc text | | | text = "\n".join parts | | | return strip system tags text | | | | | | | | | def extract all tools text content : | | | """Extract text showing every tool use with full input and every tool result in full.""" | | | if isinstance content, str : | | | return strip system tags content | | | if not isinstance content, list : | | | return "" | | | parts = | | | for item in content: | | | if not isinstance item, dict : | | | continue | | | itype = item.get "type", "" | | | if itype == "text": | | | parts.append item.get "text", "" | | | elif itype == "tool use": | | | name = item.get "name", "?" | | | inp = item.get "input", {} | | | try: | | | inp str = json.dumps inp, indent=2, ensure ascii=False | | | except TypeError, ValueError : | | | inp str = repr inp | | | parts.append f" tool use: {name} \n{inp str}" | | | elif itype == "tool result": | | | rc = item.get "content", "" | | | if isinstance rc, str : | | | rc text = rc | | | elif isinstance rc, list : | | | rc text = "\n".join | | | r.get "text", "" for r in rc | | | if isinstance r, dict and r.get "type" == "text" | | | | | | else: | | | rc text = "" | | | parts.append f" tool result \n{rc text}" | | | text = "\n".join parts | | | return strip system tags text | | | | | | | | | def cmd summary args : | | | """Show a summary of recent sessions: conversations, files, and commits.""" | | | project dirs = resolve project dirs args | | | sessions = list discover sessions project dirs=project dirs | | | sessions.sort key=lambda s: s 4 or 0, reverse=True | | | sessions = sessions :args.limit | | | | | | if not sessions: | | | print " No sessions found." | | | return | | | | | | ── Git commits across recent sessions ── | | | all commits = | | | for sid, proj, path, title, ts in sessions: | | | commits = extract git commits Path path | | | for msg in commits: | | | date str = datetime.fromtimestamp ts .strftime "%Y-%m-%d" if ts else "?" | | | all commits.append date str, proj, msg | | | | | | if all commits: | | | print f"\n {bold 'Git commits' }" | | | print f" {'─' 60}" | | | for date str, proj, msg in all commits :8 : | | | print f" {dim date str } {dim ' ' + proj + ' ' } {msg :80 }" | | | if len all commits 8: | | | print f" {dim f'... +{len all commits - 8} more' }" | | | print | | | | | | ── Recent conversations ── | | | print f" {bold 'Recent conversations' }" | | | print f" {'─' 60}" | | | for sid, proj, path, title, ts in sessions: | | | date str = datetime.fromtimestamp ts .strftime "%Y-%m-%d %H:%M" if ts else "?" | | | short id = sid :8 | | | print f"\n {cyan short id } {dim date str } {dim ' ' + proj + ' ' } {bold title }" | | | | | | messages = extract messages Path path | | | Show first user message 3 lines max | | | for role, text in messages: | | | if role == "user": | | | lines = l for l in text.split "\n" if l.strip :3 | | | for line in lines: | | | print f" {green ' ' } { truncate line, 90 }" | | | if len l for l in text.split "\n" if l.strip 3: | | | print f" {dim '...' }" | | | break | | | | | | Show last assistant message 2 lines max, truncated | | | for role, text in reversed messages : | | | if role == "assistant": | | | lines = l for l in text.split "\n" if l.strip :2 | | | for line in lines: | | | print f" {yellow '<' } { truncate line, 80 }" | | | remaining lines = len l for l in text.split "\n" if l.strip - 2 | | | if remaining lines 0: | | | print f" {dim f' ... +{remaining lines} lines' }" | | | break | | | | | | ── Files across recent sessions ── | | | all files = defaultdict lambda: {"ops": set , "session": None, "ts": 0} | | | for sid, proj, path, title, ts in sessions: | | | calls = extract tool calls Path path | | | for c in calls: | | | if c "tool" in "Read", "Write", "Edit" : | | | fp = c.get "file", "" | | | if not fp: | | | continue | | | entry = all files fp | | | entry "ops" .add c "tool" .lower | | | if ts and ts entry "ts" : | | | entry "ts" = ts | | | entry "session" = sid :8 | | | | | | if all files: | | | by cat = defaultdict list | | | for fp, info in all files.items : | | | cat = categorize file fp | | | by cat cat .append fp, info | | | | | | Sort each category by timestamp descending | | | for cat in by cat: | | | by cat cat .sort key=lambda x: -x 1 "ts" | | | | | | print f"\n\n {bold 'Files touched' }" | | | print f" {'─' 60}" | | | | | | cat order = "images", "code", "data", "docs", "config", "misc" | | | for cat in cat order: | | | if cat not in by cat: | | | continue | | | entries = by cat cat | | | cat color = {"images": magenta, "code": cyan, "data": yellow, "docs": green, "config": dim, "misc": dim} | | | color fn = cat color.get cat, dim | | | | | | shown = entries :3 | | | extra = len entries - 3 | | | print f"\n {color fn cat.upper } {len entries } files " | | | | | | for i, fp, info in enumerate shown : | | | age = f"T-{i}" if i 0 else "T " | | | ops = ",".join sorted info "ops" | | | basename = os.path.basename fp | | | dirname = os.path.dirname fp | | | Shorten home prefix | | | dirname = dirname.replace str Path.home , "~" | | | print f" {dim age } {dim f' {ops} ' :18s} {basename} {dim dirname }" | | | | | | if extra 0: | | | print f" {dim f' +{extra} more' }" | | | | | | print | | | | | | | | | def cmd index args : | | | """Build a term-frequency index across all sessions for fast search.""" | | | print "Building index..." | | | index = {} | | | count = 0 | | | | | | for sid, proj, path, title, ts in discover sessions : | | | count += 1 | | | terms = defaultdict int | | | | | | for record in iter jsonl path : | | | if record.get "type" not in "user", "assistant" : | | | continue | | | text = extract text record.get "message", {} .get "content", "" | | | text = strip system tags text .lower | | | Tokenize: split on non-alphanumeric, keep tokens = 3 chars | | | for word in re.findall r" a-z0-9 {3,}", text : | | | terms word += 1 | | | | | | Keep top 100 terms per session skip ultra-common ones | | | STOPWORDS = { | | | "the", "and", "for", "that", "this", "with", "you", "are", "from", | | | "have", "has", "was", "were", "will", "can", "not", "but", "they", | | | "been", "would", "could", "should", "which", "their", "there", | | | "about", "into", "than", "then", "them", "these", "those", | | | "some", "other", "its", "your", "our", "what", "when", "how", | | | "all", "each", "more", "also", "use", "used", "using", | | | "text", "type", "tool", "name", "content", "message", | | | } | | | filtered = {k: v for k, v in terms.items if k not in STOPWORDS} | | | top = sorted filtered.items , key=lambda x: -x 1 :100 | | | | | | index sid = { | | | "project": proj, | | | "title": title, | | | "timestamp": ts, | | | "date": datetime.fromtimestamp ts .isoformat if ts else None, | | | "terms": {k: v for k, v in top}, | | | } | | | | | | INDEX PATH.parent.mkdir parents=True, exist ok=True | | | with open INDEX PATH, "w", encoding="utf-8" as f: | | | json.dump index, f, indent=1 | | | | | | total terms = sum len v "terms" for v in index.values | | | print f"Indexed {count} sessions, {total terms} unique terms." | | | print f"Index saved to {INDEX PATH}" | | | | | | | | | def cmd projects args : | | | projects = defaultdict int | | | for proj dir in sorted PROJECTS DIR.iterdir : | | | if not proj dir.is dir : | | | continue | | | label = project label proj dir | | | count = sum 1 for in proj dir.glob " .jsonl" | | | projects label = count | | | | | | for proj, count in sorted projects.items , key=lambda x: -x 1 : | | | print f" {cyan f'{count:3d}' } sessions {proj}" | | | | | | | | | def cmd stats args : | | | total sessions = 0 | | | total messages = 0 | | | total bytes = 0 | | | by project = defaultdict lambda: {"sessions": 0, "messages": 0, "bytes": 0} | | | | | | for proj dir in sorted PROJECTS DIR.iterdir : | | | if not proj dir.is dir : | | | continue | | | label = project label proj dir | | | | | | for jsonl file in proj dir.glob " .jsonl" : | | | total sessions += 1 | | | by project label "sessions" += 1 | | | fsize = jsonl file.stat .st size | | | total bytes += fsize | | | by project label "bytes" += fsize | | | | | | for record in iter jsonl jsonl file : | | | if record.get "type" in "user", "assistant" : | | | total messages += 1 | | | by project label "messages" += 1 | | | | | | print f"\n {bold 'Claude Code History Stats' }" | | | print f" {'━' 40}" | | | print f" Sessions: {total sessions}" | | | print f" Messages: {total messages}" | | | print f" Size: {total bytes / 1024 / 1024:.1f} MB" | | | print | | | | | | for proj, s in sorted by project.items , key=lambda x: -x 1 "sessions" : | | | print f" {cyan proj :40s} {s 'sessions' :3d} sessions {s 'messages' :5d} msgs {s 'bytes' /1024:.0f} KB" | | | print | | | | | | | | | ─── Completions ───────────────────────────────────────────────────────────── | | | | | | ZSH COMPLETION = r''' | | | compdef cc-history | | | | | | cc-history { | | | local -a commands | | | commands= | | | 'list:List sessions' | | | 'ls:List sessions' | | | 'search:Search conversations' | | | 's:Search conversations' | | | 'grep:Search conversations' | | | 'read:Read a session' | | | 'r:Read a session' | | | 'show:Read a session' | | | 'summary:Summary of recent sessions' | | | 'tools:List tool/MCP calls' | | | 't:List tool/MCP calls' | | | 'calls:List tool/MCP calls' | | | 'files:List files accessed' | | | 'f:List files accessed' | | | 'index:Build search term index' | | | 'projects:List projects' | | | 'p:List projects' | | | 'stats:Show stats' | | | 'completions:Generate shell completions' | | | | | | | | | arguments -C \ | | | '1:command:- command' \ | | | ' ::arg:- args' | | | | | | case "$state" in | | | command | | | describe -t commands 'cc-history command' commands | | | ;; | | | args | | | case "$words 1 " in | | | list\|ls | | | arguments \ | | | ' -g --global '{-g,--global}' Search all projects ' \ | | | ' -p --project '{-p,--project}' Filter by project :project: cc history projects' \ | | | ' -n --limit '{-n,--limit}' Max sessions to show :limit:' \ | | | ' -d --date '{-d,--date}' Filter by date :date expression:' \ | | | '--json JSON output ' \ | | | '--pick Interactive picker ' \ | | | '--fzf Use fzf for picker ' | | | ;; | | | search\|s\|grep | | | arguments \ | | | '1:search term:' \ | | | ' -g --global '{-g,--global}' Search all projects ' \ | | | ' -E --regex '{-E,--regex}' Treat term as regex ' \ | | | ' -F --fuzzy '{-F,--fuzzy}' Fuzzy match ' \ | | | ' -p --project '{-p,--project}' Filter by project :project: cc history projects' \ | | | ' -d --date '{-d,--date}' Filter by date :date expression:' \ | | | ' -C --context '{-C,--context}' Lines of context :lines:' \ | | | '--json JSON output ' | | | ;; | | | read\|r\|show | | | arguments \ | | | '1:session ID: cc history sessions' \ | | | ' -g --global '{-g,--global}' Pick from all projects ' \ | | | '--ai Show last AI message ' \ | | | '--human Show last human message ' \ | | | '--git Show git commits ' \ | | | '--full Show full unabridged content ' \ | | | '--raw Show raw JSON content ' \ | | | '--no-tools Hide tool blocks ' \ | | | '--all-tools Show every tool call in full ' \ | | | '--fzf Use fzf for picker ' | | | ;; | | | summary | | | arguments \ | | | ' -g --global '{-g,--global}' Include all projects ' \ | | | ' -n --limit '{-n,--limit}' Number of sessions :count:' | | | ;; | | | tools\|t\|calls | | | arguments \ | | | '1:session ID: cc history sessions' \ | | | '--mcp-only Only MCP calls ' \ | | | '--no-bash Hide Bash calls ' \ | | | '--summary Count summary only ' \ | | | '--json JSON output ' | | | ;; | | | files\|f | | | arguments \ | | | '1:session ID: cc history sessions' \ | | | '--images Only image files ' \ | | | '--code Only code files ' \ | | | '--data Only data files ' \ | | | '--docs Only document files ' \ | | | '--config Only config files ' \ | | | '--misc Only uncategorized files ' \ | | | '--json JSON output ' | | | ;; | | | completions | | | arguments '1:shell: zsh bash fish powershell ' | | | ;; | | | esac | | | ;; | | | esac | | | } | | | | | | cc history projects { | | | local -a projects | | | projects= ${ f "$ cc-history projects 2 /dev/null \| sed 's/^ :space: 0-9 sessions :space: //' "} | | | describe -t projects 'project' projects | | | } | | | | | | cc history sessions { | | | local -a sessions | | | local idx="${CLAUDE CONFIG DIR:-$HOME/.claude}/cache/cc-history-index.json" | | | if -f $idx ; then | | | sessions= ${ f "$ python3 -c " | | | import json, sys | | | with open sys.argv 1 , encoding='utf-8' as f: | | | idx = json.load f | | | for sid, info in sorted idx.items , key=lambda x: x 1 .get 'timestamp' or 0, reverse=True :30 : | | | title = info.get 'title', '' .replace ':', ' ' .replace \"'\", '' :60 | | | print f'{sid :8 }:{title}' | | | " "$idx" 2 /dev/null "} | | | else | | | sessions= ${ f "$ cc-history list --limit 30 2 /dev/null \| sed -n 's/^ :space: $ a-f0-9 \{8\}$. /\1/p' "} | | | fi | | | describe -t sessions 'session' sessions | | | } | | | | | | compdef cc-history cc-history | | | ''' | | | | | | BASH COMPLETION = r''' | | | cc history { | | | local cur prev commands | | | COMPREPLY= | | | cur="${COMP WORDS COMP CWORD }" | | | prev="${COMP WORDS COMP CWORD-1 }" | | | | | | commands="list ls search s grep read r show summary tools t calls files f index projects p stats completions" | | | | | | if ${COMP CWORD} -eq 1 ; then | | | COMPREPLY= $ compgen -W "${commands}" -- "${cur}" | | | return 0 | | | fi | | | | | | local subcmd="${COMP WORDS 1 }" | | | | | | case "${subcmd}" in | | | list\|ls | | | COMPREPLY= $ compgen -W "-g --global --project -p --limit -n --date -d --json --pick --fzf" -- "${cur}" | | | if "${prev}" == "-p" \|\| "${prev}" == "--project" ; then | | | local projects | | | projects=$ cc-history projects 2 /dev/null \| sed 's/^ :space: 0-9 sessions :space: //' | | | COMPREPLY= $ compgen -W "${projects}" -- "${cur}" | | | fi | | | ;; | | | search\|s\|grep | | | COMPREPLY= $ compgen -W "-g --global --regex -E --fuzzy -F --project -p --date -d --context -C --json" -- "${cur}" | | | if "${prev}" == "-p" \|\| "${prev}" == "--project" ; then | | | local projects | | | projects=$ cc-history projects 2 /dev/null \| sed 's/^ :space: 0-9 sessions :space: //' | | | COMPREPLY= $ compgen -W "${projects}" -- "${cur}" | | | fi | | | ;; | | | read\|r\|show | | | if ${COMP CWORD} -eq 2 ; then | | | local sessions | | | sessions=$ cc-history list --limit 30 2 /dev/null \| sed -n 's/^ :space: $ a-f0-9 \{8\}$. /\1/p' | | | COMPREPLY= $ compgen -W "${sessions} -g --global --fzf" -- "${cur}" | | | else | | | COMPREPLY= $ compgen -W "--ai --human --git --full --raw --no-tools --all-tools" -- "${cur}" | | | fi | | | ;; | | | summary | | | COMPREPLY= $ compgen -W "-g --global --limit -n" -- "${cur}" | | | ;; | | | tools\|t\|calls | | | if ${COMP CWORD} -eq 2 ; then | | | local sessions | | | sessions=$ cc-history list --limit 30 2 /dev/null \| sed -n 's/^ :space: $ a-f0-9 \{8\}$. /\1/p' | | | COMPREPLY= $ compgen -W "${sessions}" -- "${cur}" | | | else | | | COMPREPLY= $ compgen -W "--mcp-only --no-bash --summary --json" -- "${cur}" | | | fi | | | ;; | | | files\|f | | | if ${COMP CWORD} -eq 2 ; then | | | local sessions | | | sessions=$ cc-history list --limit 30 2 /dev/null \| sed -n 's/^ :space: $ a-f0-9 \{8\}$. /\1/p' | | | COMPREPLY= $ compgen -W "${sessions}" -- "${cur}" | | | else | | | COMPREPLY= $ compgen -W "--images --code --data --docs --config --misc --json" -- "${cur}" | | | fi | | | ;; | | | completions | | | COMPREPLY= $ compgen -W "zsh bash fish powershell" -- "${cur}" | | | ;; | | | esac | | | return 0 | | | } | | | complete -F cc history cc-history | | | ''' | | | | | | FISH COMPLETION = r''' | | | Disable file completions for cc-history | | | complete -c cc-history -f | | | | | | Subcommands | | | complete -c cc-history -n " fish use subcommand" -a "list ls" -d "List sessions" | | | complete -c cc-history -n " fish use subcommand" -a "search s grep" -d "Search conversations" | | | complete -c cc-history -n " fish use subcommand" -a "read r show" -d "Read a session" | | | complete -c cc-history -n " fish use subcommand" -a "summary" -d "Summary of recent sessions" | | | complete -c cc-history -n " fish use subcommand" -a "tools t calls" -d "List tool/MCP calls" | | | complete -c cc-history -n " fish use subcommand" -a "files f" -d "List files accessed" | | | complete -c cc-history -n " fish use subcommand" -a "index" -d "Build search term index" | | | complete -c cc-history -n " fish use subcommand" -a "projects p" -d "List projects" | | | complete -c cc-history -n " fish use subcommand" -a "stats" -d "Show stats" | | | complete -c cc-history -n " fish use subcommand" -a "completions" -d "Generate shell completions" | | | | | | list flags | | | complete -c cc-history -n " fish seen subcommand from list ls" -s p -l project -d "Filter by project" -x -a " cc-history projects 2 /dev/null \| string replace -r '^\s \d+ sessions\s+' '' " | | | complete -c cc-history -n " fish seen subcommand from list ls" -s n -l limit -d "Max sessions" | | | complete -c cc-history -n " fish seen subcommand from list ls" -l json -d "JSON output" | | | complete -c cc-history -n " fish seen subcommand from list ls" -l pick -d "Interactive picker" | | | complete -c cc-history -n " fish seen subcommand from list ls" -l fzf -d "Use fzf for picker" | | | complete -c cc-history -n " fish seen subcommand from list ls" -s d -l date -d "Filter by date" | | | | | | search flags | | | complete -c cc-history -n " fish seen subcommand from search s grep" -s E -l regex -d "Regex mode" | | | complete -c cc-history -n " fish seen subcommand from search s grep" -s F -l fuzzy -d "Fuzzy match" | | | complete -c cc-history -n " fish seen subcommand from search s grep" -s p -l project -d "Filter by project" -x -a " cc-history projects 2 /dev/null \| string replace -r '^\s \d+ sessions\s+' '' " | | | complete -c cc-history -n " fish seen subcommand from search s grep" -s d -l date -d "Filter by date" | | | complete -c cc-history -n " fish seen subcommand from search s grep" -s C -l context -d "Context lines" | | | complete -c cc-history -n " fish seen subcommand from search s grep" -l json -d "JSON output" | | | | | | read flags | | | complete -c cc-history -n " fish seen subcommand from read r show" -l raw -d "Raw JSON content" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l no-tools -d "Hide tool blocks" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l all-tools -d "Show every tool call in full" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l ai -d "Last AI message" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l human -d "Last human message" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l git -d "Show git commits" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l full -d "Full unabridged content" | | | complete -c cc-history -n " fish seen subcommand from read r show" -l fzf -d "Use fzf for picker" | | | | | | summary flags | | | complete -c cc-history -n " fish seen subcommand from summary" -s g -l global -d "Include all projects" | | | complete -c cc-history -n " fish seen subcommand from summary" -s n -l limit -d "Number of sessions" | | | complete -c cc-history -n " fish seen subcommand from read r show" -x -a " cc-history list --limit 30 2 /dev/null \| string replace -r '^\s a-f0-9 {8} . ' '\$1' " | | | | | | tools flags | | | complete -c cc-history -n " fish seen subcommand from tools t calls" -l mcp-only -d "Only MCP calls" | | | complete -c cc-history -n " fish seen subcommand from tools t calls" -l no-bash -d "Hide Bash calls" | | | complete -c cc-history -n " fish seen subcommand from tools t calls" -l summary -d "Count summary" | | | complete -c cc-history -n " fish seen subcommand from tools t calls" -l json -d "JSON output" | | | | | | files flags | | | complete -c cc-history -n " fish seen subcommand from files f" -l images -d "Only images" | | | complete -c cc-history -n " fish seen subcommand from files f" -l code -d "Only code" | | | complete -c cc-history -n " fish seen subcommand from files f" -l data -d "Only data files" | | | complete -c cc-history -n " fish seen subcommand from files f" -l docs -d "Only documents" | | | complete -c cc-history -n " fish seen subcommand from files f" -l config -d "Only config" | | | complete -c cc-history -n " fish seen subcommand from files f" -l misc -d "Only uncategorized" | | | complete -c cc-history -n " fish seen subcommand from files f" -l json -d "JSON output" | | | | | | completions flags | | | complete -c cc-history -n " fish seen subcommand from completions" -x -a "zsh bash fish powershell" | | | ''' | | | | | | POWERSHELL COMPLETION = r''' | | | Register-ArgumentCompleter -Native -CommandName cc-history, cc-history.exe -ScriptBlock { | | | param $wordToComplete, $commandAst, $cursorPosition | | | | | | $commands = ordered @{ | | | 'list' = 'List sessions'; 'search' = 'Search conversations'; 'read' = 'Read a session' | | | 'summary' = 'Summary of recent sessions'; 'tools' = 'List tool/MCP calls' | | | 'files' = 'List files accessed'; 'index' = 'Build search term index' | | | 'projects' = 'List projects'; 'stats' = 'Show stats'; 'completions' = 'Generate shell completions' | | | } | | | $aliases = @{ 'ls' = 'list'; 's' = 'search'; 'grep' = 'search'; 'r' = 'read'; 'show' = 'read' | | | 't' = 'tools'; 'calls' = 'tools'; 'f' = 'files'; 'p' = 'projects' } | | | $flags = @{ | | | 'list' = @ '-g', '--global', '-p', '--project', '-n', '--limit', '-d', '--date', '--json', '--pick', '--fzf' | | | 'search' = @ '-g', '--global', '-E', '--regex', '-F', '--fuzzy', '-p', '--project', '-d', '--date', '-C', '--context', '-T', '--timeout', '--json' | | | 'read' = @ '-g', '--global', '--ai', '--human', '--git', '--full', '--raw', '--no-tools', '--all-tools', '--fzf' | | | 'summary' = @ '-g', '--global', '-n', '--limit' | | | 'tools' = @ '--mcp-only', '--no-bash', '--summary', '--json' | | | 'files' = @ '--images', '--code', '--data', '--docs', '--config', '--misc', '--json' | | | 'completions' = @ 'zsh', 'bash', 'fish', 'powershell' | | | } | | | | | | $words = @ $commandAst.CommandElements \| ForEach-Object { $ .ToString } | | | if $words.Count -lt 2 -or $words.Count -eq 2 -and $wordToComplete { | | | foreach $cmd in $commands.Keys { | | | if $cmd -like "$wordToComplete " { | | | System.Management.Automation.CompletionResult ::new $cmd, $cmd, 'ParameterValue', $commands $cmd | | | } | | | } | | | return | | | } | | | | | | $sub = $words 1 | | | if $aliases.ContainsKey $sub { $sub = $aliases $sub } | | | $candidates = @ | | | if $sub -in 'read', 'tools', 'files' -and -not $wordToComplete.StartsWith '-' { | | | $candidates += @ cc-history list --limit 30 --json 2 $null \| ConvertFrom-Json \| | | | ForEach-Object { $ .session id.Substring 0, 8 } | | | } | | | if $flags.ContainsKey $sub { $candidates += $flags $sub } | | | foreach $c in $candidates { | | | if $c -like "$wordToComplete " { | | | System.Management.Automation.CompletionResult ::new $c, $c, 'ParameterValue', $c | | | } | | | } | | | } | | | ''' | | | | | | | | | def cmd completions args : | | | shell = args.shell | | | if shell is None: | | | shell env = os.environ.get "SHELL", "" | | | if "zsh" in shell env: | | | shell = "zsh" | | | elif "fish" in shell env: | | | shell = "fish" | | | elif IS WINDOWS and not shell env: | | | shell = "powershell" | | | else: | | | shell = "bash" | | | | | | if shell == "zsh": | | | print ZSH COMPLETION.strip | | | elif shell == "bash": | | | print BASH COMPLETION.strip | | | elif shell == "fish": | | | print FISH COMPLETION.strip | | | elif shell == "powershell": | | | print POWERSHELL COMPLETION.strip | | | | | | | | | ─── Main ──────────────────────────────────────────────────────────────────── | | | | | | def main : | | | parser = argparse.ArgumentParser | | | prog="cc-history", | | | description="Browse and search Claude Code conversation history.", | | | | | | sub = parser.add subparsers dest="command" | | | | | | list | | | p list = sub.add parser "list", aliases= "ls" , help="List sessions" | | | p list.add argument "-g", "--global", dest="glob", action="store true", help="Search all projects default: current project only " | | | p list.add argument "--project", "-p", help="Filter by project name substring match " | | | p list.add argument "--limit", "-n", type=int, help="Max sessions to show" | | | p list.add argument "--date", "-d", help="Filter by date e.g. 'yesterday', 'past 3 days', 'before may 5' " | | | p list.add argument "--json", action="store true", help="JSON output" | | | p list.add argument "--pick", action="store true", help="Interactive session picker" | | | p list.add argument "--fzf", action="store true", help="Use fzf for interactive picker" | | | | | | search | | | p search = sub.add parser "search", aliases= "s", "grep" , help="Search conversations" | | | p search.add argument "term", help="Search term plain text or regex with -E " | | | p search.add argument "-g", "--global", dest="glob", action="store true", help="Search all projects default: current project only " | | | p search.add argument "--regex", "-E", action="store true", help="Treat term as a regex pattern" | | | p search.add argument "--fuzzy", "-F", action="store true", help="Fuzzy match typo-tolerant search " | | | p search.add argument "--project", "-p", help="Filter by project" | | | p search.add argument "--date", "-d", help="Filter by date e.g. 'two days ago', 'in the past week' " | | | p search.add argument "--context", "-C", type=int, default=1, help="Lines of context around match" | | | p search.add argument "--timeout", "-T", type=int, default=None, help="Timeout in seconds default: 10 for fuzzy, unlimited otherwise " | | | p search.add argument "--json", action="store true", help="JSON output" | | | | | | read | | | p read = sub.add parser "read", aliases= "r", "show" , help="Read a session" | | | p read.add argument "session id", nargs="?", default=None, help="Session ID prefix match OK, omit for picker " | | | p read.add argument "-g", "--global", dest="glob", action="store true", help="Pick from all projects default: current project only " | | | p read.add argument "--ai", action="store true", help="Show only the last AI message" | | | p read.add argument "--human", action="store true", help="Show only the last human message" | | | p read.add argument "--git", action="store true", help="Show git commits from the session" | | | p read.add argument "--full", action="store true", help="Show full unabridged content including diffs/tool output " | | | p read.add argument "--raw", action="store true", help="Show raw content JSON " | | | p read.add argument "--no-tools", action="store true", help="Hide tool use/tool result blocks" | | | p read.add argument "--all-tools", dest="all tools", action="store true", | | | help="Show every tool use with full input and every tool result in full" | | | p read.add argument "--fzf", action="store true", help="Use fzf for interactive picker" | | | | | | summary | | | p summary = sub.add parser "summary", help="Summary of recent sessions, files, and commits" | | | p summary.add argument "-g", "--global", dest="glob", action="store true", help="Include all projects" | | | p summary.add argument "--limit", "-n", type=int, default=5, help="Number of recent sessions default: 5 " | | | | | | tools | | | p tools = sub.add parser "tools", aliases= "t", "calls" , help="List tool/MCP calls in a session" | | | p tools.add argument "session id", help="Session ID prefix match OK " | | | p tools.add argument "--mcp-only", action="store true", help="Only show MCP tool calls" | | | p tools.add argument "--no-bash", action="store true", help="Hide shell Bash/PowerShell tool calls" | | | p tools.add argument "--summary", action="store true", help="Show call count summary only" | | | p tools.add argument "--json", action="store true", help="JSON output" | | | | | | files | | | p files = sub.add parser "files", aliases= "f" , help="List files accessed in a session" | | | p files.add argument "session id", help="Session ID prefix match OK " | | | p files.add argument "--images", action="store true", help="Only show image files" | | | p files.add argument "--code", action="store true", help="Only show code files" | | | p files.add argument "--data", action="store true", help="Only show data files csv, json, etc. " | | | p files.add argument "--docs", action="store true", help="Only show document files" | | | p files.add argument "--config", action="store true", help="Only show config files" | | | p files.add argument "--misc", action="store true", help="Only show uncategorized files" | | | p files.add argument "--json", action="store true", help="JSON output" | | | | | | index | | | sub.add parser "index", help="Build search term index speeds up zsh session completion " | | | | | | projects | | | sub.add parser "projects", aliases= "p" , help="List projects" | | | | | | stats | | | sub.add parser "stats", help="Show stats" | | | | | | completions | | | p comp = sub.add parser "completions", help="Generate shell completions" | | | p comp.add argument "shell", nargs="?", default=None, choices= "zsh", "bash", "fish", "powershell" , | | | help="Shell type auto-detected if omitted " | | | | | | Exit quietly when piped into head etc. no SIGPIPE on Windows | | | if hasattr signal, "SIGPIPE" : | | | signal.signal signal.SIGPIPE, signal.SIG DFL | | | | | | Don't crash on characters the console/pipe encoding can't represent e.g. cp1252 on Windows | | | for stream in sys.stdout, sys.stderr : | | | try: | | | stream.reconfigure errors="replace" | | | except AttributeError, ValueError : | | | pass | | | | | | args = parser.parse args | | | | | | if args.command not in None, "completions" and not PROJECTS DIR.is dir : | | | print f"No Claude Code history found at {PROJECTS DIR}", file=sys.stderr | | | print "Set CLAUDE CONFIG DIR if your Claude config lives elsewhere.", file=sys.stderr | | | sys.exit 1 | | | | | | if args.command in "list", "ls" : | | | cmd list args | | | elif args.command in "search", "s", "grep" : | | | cmd search args | | | elif args.command in "read", "r", "show" : | | | cmd read args | | | elif args.command == "summary": | | | cmd summary args | | | elif args.command in "tools", "t", "calls" : | | | cmd tools args | | | elif args.command in "files", "f" : | | | cmd files args | | | elif args.command == "index": | | | cmd index args | | | elif args.command in "projects", "p" : | | | cmd projects args | | | elif args.command == "stats": | | | cmd stats args | | | elif args.command == "completions": | | | cmd completions args | | | else: | | | parser.print help | | | | | | | | | if name == " main ": | | | main |