gchamon · October 24, 2025 14:29
diff --git a/README.md b/README.md
diff --git a/claude-sessions b/claude-sessions
 #!/usr/bin/env bash
 # Claude Code session management utility
 # Wrapper around extract-sessions.py for easier CLI usage

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 EXTRACTOR="$SCRIPT_DIR/extract-sessions.py"

 usage() {
    cat <<EOF
 Usage: claude-sessions [COMMAND] [OPTIONS]

 Commands:
    list [--by-project] [--limit N] [--project PATH]
        List all sessions (default command)

    find KEYWORD
        Find sessions by keyword and display with session IDs

    restore KEYWORD
        Find and restore a session by keyword (launches claude -r)

    projects
        List all projects

    recent [PROJECT_PATH]
        Show recent sessions for a project (defaults to current directory)

    help
        Show this help message

 Options:
    --limit N           Limit number of results
    --project PATH      Filter by project path
    --by-project        Group results by project

 Examples:
    # List all sessions
    claude-sessions list

    # List sessions grouped by project
    claude-sessions list --by-project

    # Find sessions containing "invoice"
    claude-sessions find invoice

    # Restore a session by keyword
    claude-sessions restore "implement dark mode"

    # List all projects
    claude-sessions projects

    # Show recent sessions for current directory
    claude-sessions recent

    # Show recent sessions for specific project
    claude-sessions recent /path/to/project

 EOF
 }

 cmd_list() {
    python3 "$EXTRACTOR" "$@"
 }

 cmd_find() {
    local keyword="$1"
    if [ -z "$keyword" ]; then
        echo "Error: keyword required" >&2
        echo "Usage: claude-sessions find KEYWORD" >&2
        exit 1
    fi

    python3 "$EXTRACTOR" | \
        jq -r ".sessions[] | select(.session_name | contains(\"$keyword\")) | \"\(.session_id) | \(.date) | \(.session_name[:80])\""
 }

 cmd_restore() {
    local keyword="$1"
    if [ -z "$keyword" ]; then
        echo "Error: keyword required" >&2
        echo "Usage: claude-sessions restore KEYWORD" >&2
        exit 1
    fi

    local session_id=$(python3 "$EXTRACTOR" | \
        jq -r ".sessions[] | select(.session_name | contains(\"$keyword\")) | .session_id" | \
        head -1)

    if [ -n "$session_id" ]; then
        echo "Restoring session: $session_id"
        claude -r "$session_id"
    else
        echo "No session found matching: $keyword" >&2
        exit 1
    fi
 }

 cmd_projects() {
    python3 "$EXTRACTOR" --by-project | jq -r 'keys[]'
 }

 cmd_recent() {
    local project="${1:-$(pwd)}"
    python3 "$EXTRACTOR" --project "$project" --limit 10 | \
        jq -r '.sessions[] | "\(.date) | \(.session_name[:80])"'
 }

 # Main command dispatcher
 case "${1:-list}" in
    list)
        shift
        cmd_list "$@"
        ;;
    find)
        shift
        cmd_find "$@"
        ;;
    restore)
        shift
        cmd_restore "$@"
        ;;
    projects)
        cmd_projects
        ;;
    recent)
        shift
        cmd_recent "$@"
        ;;
    help|--help|-h)
        usage
        ;;
    *)
        echo "Error: Unknown command '$1'" >&2
        echo "Run 'claude-sessions help' for usage information" >&2
        exit 1
        ;;
 esac
diff --git a/extract-sessions.py b/extract-sessions.py
 #!/usr/bin/env python3
 """
 Extract Claude Code session information for easy querying and restoration.

 This script parses the Claude Code data directory to extract:
 - Session ID (UUID)
 - Session name (first user message)
 - Project path
 - Timestamp

 Output is JSON format suitable for querying with jq or other tools.
 """

 import json
 import os
 from pathlib import Path
 from typing import Dict, List, Optional
 from collections import defaultdict
 from datetime import datetime


 def parse_history_jsonl(history_file: Path) -> List[Dict]:
    """Parse history.jsonl and return list of entries."""
    entries = []
    if not history_file.exists():
        return entries

    with open(history_file, 'r') as f:
        for line in f:
            line = line.strip()
            if line:
                try:
                    entries.append(json.loads(line))
                except json.JSONDecodeError:
                    continue
    return entries


 def get_debug_sessions(debug_dir: Path) -> Dict[str, datetime]:
    """Get session IDs from debug directory with their modification times."""
    sessions = {}
    if not debug_dir.exists():
        return sessions

    for debug_file in debug_dir.glob("*.txt"):
        # Skip the 'latest' symlink
        if debug_file.name == "latest":
            continue

        # Extract UUID from filename (remove .txt extension)
        session_id = debug_file.stem

        # Get file modification time
        mtime = datetime.fromtimestamp(debug_file.stat().st_mtime)
        sessions[session_id] = mtime

    return sessions


 def correlate_sessions(history_entries: List[Dict], sessions: Dict[str, datetime]) -> List[Dict]:
    """
    Correlate history entries with sessions to build session database.

    Groups consecutive history entries by project and timestamp proximity
    to identify distinct sessions.
    """
    # Group history entries by project
    project_entries = defaultdict(list)
    for entry in history_entries:
        project = entry.get("project")
        if project:
            project_entries[project].append(entry)

    # Build session records
    session_records = []

    # For each session ID found in debug directory
    for session_id, session_time in sorted(sessions.items(), key=lambda x: x[1]):
        # Try to find matching history entries
        # Look for entries within a reasonable time window (±5 minutes)
        session_timestamp_ms = int(session_time.timestamp() * 1000)
        time_window_ms = 5 * 60 * 1000  # 5 minutes

        matching_entries = []
        session_project = None

        for project, entries in project_entries.items():
            for entry in entries:
                entry_time = entry.get("timestamp", 0)
                if abs(entry_time - session_timestamp_ms) < time_window_ms:
                    matching_entries.append(entry)
                    session_project = project

        # Use the first matching entry as the session name
        if matching_entries:
            # Sort by timestamp to get the first message
            matching_entries.sort(key=lambda x: x.get("timestamp", 0))
            first_entry = matching_entries[0]

            session_name = first_entry.get("display", "").strip()
            session_project = first_entry.get("project")
            session_timestamp = first_entry.get("timestamp")

            session_records.append({
                "session_id": session_id,
                "session_name": session_name[:100],  # Truncate long names
                "project": session_project,
                "timestamp": session_timestamp,
                "date": datetime.fromtimestamp(session_timestamp / 1000).isoformat() if session_timestamp else None
            })

    return session_records


 def extract_sessions_by_project(session_records: List[Dict]) -> Dict[str, List[Dict]]:
    """Group sessions by project."""
    by_project = defaultdict(list)

    for record in session_records:
        project = record.get("project")
        if project:
            by_project[project].append({
                "session_id": record["session_id"],
                "session_name": record["session_name"],
                "timestamp": record["timestamp"],
                "date": record["date"]
            })

    # Sort each project's sessions by timestamp (newest first)
    for project in by_project:
        by_project[project].sort(key=lambda x: x.get("timestamp", 0), reverse=True)

    return dict(by_project)


 def main():
    """Main entry point."""
    import argparse

    parser = argparse.ArgumentParser(
        description="Extract Claude Code session information",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
 Examples:
  # List all sessions as JSON
  %(prog)s

  # List sessions for a specific project
  %(prog)s --project /path/to/project

  # Get session ID for restoration
  %(prog)s | jq -r '.sessions[] | select(.session_name | contains("search term")) | .session_id'

  # List all projects
  %(prog)s --by-project | jq -r 'keys[]'
        """
    )

    parser.add_argument(
        "--claude-dir",
        type=Path,
        default=Path.home() / ".claude",
        help="Path to Claude Code data directory (default: ~/.claude)"
    )

    parser.add_argument(
        "--project",
        type=str,
        help="Filter sessions by project path"
    )

    parser.add_argument(
        "--by-project",
        action="store_true",
        help="Group output by project"
    )

    parser.add_argument(
        "--limit",
        type=int,
        help="Limit number of sessions returned per project"
    )

    args = parser.parse_args()

    # Parse data
    history_file = args.claude_dir / "history.jsonl"
    debug_dir = args.claude_dir / "debug"

    history_entries = parse_history_jsonl(history_file)
    sessions = get_debug_sessions(debug_dir)

    # Correlate and build session records
    session_records = correlate_sessions(history_entries, sessions)

    # Apply filters
    if args.project:
        session_records = [r for r in session_records if r.get("project") == args.project]

    # Format output
    if args.by_project:
        output = extract_sessions_by_project(session_records)

        # Apply limit per project
        if args.limit:
            for project in output:
                output[project] = output[project][:args.limit]

        print(json.dumps(output, indent=2))
    else:
        # Sort by timestamp (newest first)
        session_records.sort(key=lambda x: x.get("timestamp", 0), reverse=True)

        # Apply limit
        if args.limit:
            session_records = session_records[:args.limit]

        print(json.dumps({"sessions": session_records}, indent=2))


 if __name__ == "__main__":
    main()
diff --git a/SESSION-TOOLS.md b/SESSION-TOOLS.md
	#!/usr/bin/env bash
	# Claude Code session management utility
	# Wrapper around extract-sessions.py for easier CLI usage

	SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
	EXTRACTOR="$SCRIPT_DIR/extract-sessions.py"

	usage() {
	cat <<EOF
	Usage: claude-sessions [COMMAND] [OPTIONS]

	Commands:
	list [--by-project] [--limit N] [--project PATH]
	List all sessions (default command)

	find KEYWORD
	Find sessions by keyword and display with session IDs

	restore KEYWORD
	Find and restore a session by keyword (launches claude -r)

	projects
	List all projects

	recent [PROJECT_PATH]
	Show recent sessions for a project (defaults to current directory)

	help
	Show this help message

	Options:
	--limit N Limit number of results
	--project PATH Filter by project path
	--by-project Group results by project

	Examples:
	# List all sessions
	claude-sessions list

	# List sessions grouped by project
	claude-sessions list --by-project

	# Find sessions containing "invoice"
	claude-sessions find invoice

	# Restore a session by keyword
	claude-sessions restore "implement dark mode"

	# List all projects
	claude-sessions projects

	# Show recent sessions for current directory
	claude-sessions recent

	# Show recent sessions for specific project
	claude-sessions recent /path/to/project

	EOF
	}

	cmd_list() {
	python3 "$EXTRACTOR" "$@"
	}

	cmd_find() {
	local keyword="$1"
	if [ -z "$keyword" ]; then
	echo "Error: keyword required" >&2
	echo "Usage: claude-sessions find KEYWORD" >&2
	exit 1
	fi

	python3 "$EXTRACTOR" \| \
	jq -r ".sessions[] \| select(.session_name \| contains(\"$keyword\")) \| \"\(.session_id) \| \(.date) \| \(.session_name[:80])\""
	}

	cmd_restore() {
	local keyword="$1"
	if [ -z "$keyword" ]; then
	echo "Error: keyword required" >&2
	echo "Usage: claude-sessions restore KEYWORD" >&2
	exit 1
	fi

	local session_id=$(python3 "$EXTRACTOR" \| \
	jq -r ".sessions[] \| select(.session_name \| contains(\"$keyword\")) \| .session_id" \| \
	head -1)

	if [ -n "$session_id" ]; then
	echo "Restoring session: $session_id"
	claude -r "$session_id"
	else
	echo "No session found matching: $keyword" >&2
	exit 1
	fi
	}

	cmd_projects() {
	python3 "$EXTRACTOR" --by-project \| jq -r 'keys[]'
	}

	cmd_recent() {
	local project="${1:-$(pwd)}"
	python3 "$EXTRACTOR" --project "$project" --limit 10 \| \
	jq -r '.sessions[] \| "\(.date) \| \(.session_name[:80])"'
	}

	# Main command dispatcher
	case "${1:-list}" in
	list)
	shift
	cmd_list "$@"
	;;
	find)
	shift
	cmd_find "$@"
	;;
	restore)
	shift
	cmd_restore "$@"
	;;
	projects)
	cmd_projects
	;;
	recent)
	shift
	cmd_recent "$@"
	;;
	help\|--help\|-h)
	usage
	;;
	*)
	echo "Error: Unknown command '$1'" >&2
	echo "Run 'claude-sessions help' for usage information" >&2
	exit 1
	;;
	esac
	#!/usr/bin/env python3
	"""
	Extract Claude Code session information for easy querying and restoration.

	This script parses the Claude Code data directory to extract:
	- Session ID (UUID)
	- Session name (first user message)
	- Project path
	- Timestamp

	Output is JSON format suitable for querying with jq or other tools.
	"""

	import json
	import os
	from pathlib import Path
	from typing import Dict, List, Optional
	from collections import defaultdict
	from datetime import datetime


	def parse_history_jsonl(history_file: Path) -> List[Dict]:
	"""Parse history.jsonl and return list of entries."""
	entries = []
	if not history_file.exists():
	return entries

	with open(history_file, 'r') as f:
	for line in f:
	line = line.strip()
	if line:
	try:
	entries.append(json.loads(line))
	except json.JSONDecodeError:
	continue
	return entries


	def get_debug_sessions(debug_dir: Path) -> Dict[str, datetime]:
	"""Get session IDs from debug directory with their modification times."""
	sessions = {}
	if not debug_dir.exists():
	return sessions

	for debug_file in debug_dir.glob("*.txt"):
	# Skip the 'latest' symlink
	if debug_file.name == "latest":
	continue

	# Extract UUID from filename (remove .txt extension)
	session_id = debug_file.stem

	# Get file modification time
	mtime = datetime.fromtimestamp(debug_file.stat().st_mtime)
	sessions[session_id] = mtime

	return sessions


	def correlate_sessions(history_entries: List[Dict], sessions: Dict[str, datetime]) -> List[Dict]:
	"""
	Correlate history entries with sessions to build session database.

	Groups consecutive history entries by project and timestamp proximity
	to identify distinct sessions.
	"""
	# Group history entries by project
	project_entries = defaultdict(list)
	for entry in history_entries:
	project = entry.get("project")
	if project:
	project_entries[project].append(entry)

	# Build session records
	session_records = []

	# For each session ID found in debug directory
	for session_id, session_time in sorted(sessions.items(), key=lambda x: x[1]):
	# Try to find matching history entries
	# Look for entries within a reasonable time window (±5 minutes)
	session_timestamp_ms = int(session_time.timestamp() * 1000)
	time_window_ms = 5 * 60 * 1000 # 5 minutes

	matching_entries = []
	session_project = None

	for project, entries in project_entries.items():
	for entry in entries:
	entry_time = entry.get("timestamp", 0)
	if abs(entry_time - session_timestamp_ms) < time_window_ms:
	matching_entries.append(entry)
	session_project = project

	# Use the first matching entry as the session name
	if matching_entries:
	# Sort by timestamp to get the first message
	matching_entries.sort(key=lambda x: x.get("timestamp", 0))
	first_entry = matching_entries[0]

	session_name = first_entry.get("display", "").strip()
	session_project = first_entry.get("project")
	session_timestamp = first_entry.get("timestamp")

	session_records.append({
	"session_id": session_id,
	"session_name": session_name[:100], # Truncate long names
	"project": session_project,
	"timestamp": session_timestamp,
	"date": datetime.fromtimestamp(session_timestamp / 1000).isoformat() if session_timestamp else None
	})

	return session_records


	def extract_sessions_by_project(session_records: List[Dict]) -> Dict[str, List[Dict]]:
	"""Group sessions by project."""
	by_project = defaultdict(list)

	for record in session_records:
	project = record.get("project")
	if project:
	by_project[project].append({
	"session_id": record["session_id"],
	"session_name": record["session_name"],
	"timestamp": record["timestamp"],
	"date": record["date"]
	})

	# Sort each project's sessions by timestamp (newest first)
	for project in by_project:
	by_project[project].sort(key=lambda x: x.get("timestamp", 0), reverse=True)

	return dict(by_project)


	def main():
	"""Main entry point."""
	import argparse

	parser = argparse.ArgumentParser(
	description="Extract Claude Code session information",
	formatter_class=argparse.RawDescriptionHelpFormatter,
	epilog="""
	Examples:
	# List all sessions as JSON
	%(prog)s

	# List sessions for a specific project
	%(prog)s --project /path/to/project

	# Get session ID for restoration
	%(prog)s \| jq -r '.sessions[] \| select(.session_name \| contains("search term")) \| .session_id'

	# List all projects
	%(prog)s --by-project \| jq -r 'keys[]'
	"""
	)

	parser.add_argument(
	"--claude-dir",
	type=Path,
	default=Path.home() / ".claude",
	help="Path to Claude Code data directory (default: ~/.claude)"
	)

	parser.add_argument(
	"--project",
	type=str,
	help="Filter sessions by project path"
	)

	parser.add_argument(
	"--by-project",
	action="store_true",
	help="Group output by project"
	)

	parser.add_argument(
	"--limit",
	type=int,
	help="Limit number of sessions returned per project"
	)

	args = parser.parse_args()

	# Parse data
	history_file = args.claude_dir / "history.jsonl"
	debug_dir = args.claude_dir / "debug"

	history_entries = parse_history_jsonl(history_file)
	sessions = get_debug_sessions(debug_dir)

	# Correlate and build session records
	session_records = correlate_sessions(history_entries, sessions)

	# Apply filters
	if args.project:
	session_records = [r for r in session_records if r.get("project") == args.project]

	# Format output
	if args.by_project:
	output = extract_sessions_by_project(session_records)

	# Apply limit per project
	if args.limit:
	for project in output:
	output[project] = output[project][:args.limit]

	print(json.dumps(output, indent=2))
	else:
	# Sort by timestamp (newest first)
	session_records.sort(key=lambda x: x.get("timestamp", 0), reverse=True)

	# Apply limit
	if args.limit:
	session_records = session_records[:args.limit]

	print(json.dumps({"sessions": session_records}, indent=2))


	if __name__ == "__main__":
	main()