claude-code-tools 0.1.21__py3-none-any.whl → 0.2.1__py3-none-any.whl

claude_code_tools/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Tools - Collection of utilities for Claude Code."""
 
-__version__ = "0.1.21"
+__version__ = "0.2.1"

claude_code_tools/find_claude_session.py

@@ -168,35 +168,56 @@ def search_keywords_in_file(filepath: Path, keywords: List[str]) -> tuple[bool,
     return matches, line_count, git_branch
 
 
+def is_system_message(text: str) -> bool:
+    """Check if text is system-generated (XML tags, env context, etc)"""
+    if not text or len(text.strip()) < 5:
+        return True
+    text = text.strip()
+    # Check for XML-like tags (user_instructions, environment_context, etc)
+    if text.startswith("<") and ">" in text[:100]:
+        return True
+    return False
+
+
 def get_session_preview(filepath: Path) -> str:
-    """Get a preview of the session from the first user message."""
+    """Get a preview of the session from the LAST user message."""
+    last_user_message = None
+
     try:
         with open(filepath, 'r', encoding='utf-8') as f:
             for line in f:
                 try:
                     data = json.loads(line.strip())
-                    if data.get('type') == 'message' and data.get('role') == 'user':
-                        content = data.get('content', '')
+                    # Check top-level type for user messages
+                    if data.get('type') == 'user':
+                        message = data.get('message', {})
+                        content = message.get('content', '')
+                        text = None
+
                         if isinstance(content, str):
-                            # Get first 60 chars of the message
-                            preview = content.strip().replace('\n', ' ')[:60]
-                            if len(content) > 60:
-                                preview += "..."
-                            return preview
+                            text = content.strip()
                         elif isinstance(content, list):
                             # Handle structured content
                             for item in content:
                                 if isinstance(item, dict) and item.get('type') == 'text':
-                                    text = item.get('text', '')
-                                    preview = text.strip().replace('\n', ' ')[:60]
-                                    if len(text) > 60:
-                                        preview += "..."
-                                    return preview
+                                    text = item.get('text', '').strip()
+                                    break
+
+                        # Filter out system messages and keep updating to get LAST message
+                        if text and not is_system_message(text):
+                            cleaned = text.replace('\n', ' ')[:400]
+                            # Prefer substantial messages (>20 chars)
+                            if len(cleaned) > 20:
+                                last_user_message = cleaned
+                            elif last_user_message is None:
+                                last_user_message = cleaned
+
                 except (json.JSONDecodeError, KeyError):
                     continue
     except Exception:
         pass
-    return "No preview available"
+
+    return last_user_message if last_user_message else "No preview available"
 
 
 def find_sessions(keywords: List[str], global_search: bool = False, claude_home: Optional[str] = None) -> List[Tuple[str, float, int, str, str, str, Optional[str]]]:
@@ -307,7 +328,7 @@ def display_interactive_ui(sessions: List[Tuple[str, float, int, str, str, str,
     table.add_column("Branch", style="magenta")
     table.add_column("Date", style="blue")
     table.add_column("Lines", style="cyan", justify="right")
-    table.add_column("Preview", style="white", overflow="fold")
+    table.add_column("Preview", style="white", max_width=60, overflow="fold")
     
     for idx, (session_id, mod_time, line_count, project_name, preview, _, git_branch) in enumerate(display_sessions, 1):
         mod_date = datetime.fromtimestamp(mod_time).strftime('%Y-%m-%d %H:%M')
@@ -325,8 +346,8 @@ def display_interactive_ui(sessions: List[Tuple[str, float, int, str, str, str,
     ui_console.print(table)
     ui_console.print("\n[bold]Select a session:[/bold]")
     ui_console.print(f"  • Enter number (1-{len(display_sessions)}) to select")
-    ui_console.print("  • Press Ctrl+C to cancel\n")
-    
+    ui_console.print("  • Press Enter to cancel\n")
+
     while True:
         try:
             # In stderr mode, we need to ensure nothing goes to stdout
@@ -334,39 +355,148 @@ def display_interactive_ui(sessions: List[Tuple[str, float, int, str, str, str,
                 # Temporarily redirect stdout to devnull
                 old_stdout = sys.stdout
                 sys.stdout = open(os.devnull, 'w')
-            
+
             choice = Prompt.ask(
                 "Your choice",
-                choices=[str(i) for i in range(1, len(display_sessions) + 1)],
-                show_choices=False,
+                default="",
+                show_default=False,
                 console=ui_console
             )
-            
-            # Handle empty input
+
+            # Handle empty input - cancel
             if not choice or not choice.strip():
-                ui_console.print("[red]Invalid choice. Please try again.[/red]")
-                continue
-            
+                # Restore stdout first
+                if stderr_mode:
+                    sys.stdout.close()
+                    sys.stdout = old_stdout
+                ui_console.print("[yellow]Cancelled[/yellow]")
+                return None
+
             # Restore stdout
             if stderr_mode:
                 sys.stdout.close()
                 sys.stdout = old_stdout
-            
+
             idx = int(choice) - 1
             if 0 <= idx < len(display_sessions):
                 session_info = display_sessions[idx]
-                return (session_info[0], session_info[5])  # Return (session_id, project_path)
-                
+                return session_info  # Return full session tuple
+            else:
+                ui_console.print("[red]Invalid choice. Please try again.[/red]")
+
         except KeyboardInterrupt:
+            # Restore stdout if needed
+            if stderr_mode and sys.stdout != old_stdout:
+                sys.stdout.close()
+                sys.stdout = old_stdout
             ui_console.print("\n[yellow]Cancelled[/yellow]")
             return None
         except EOFError:
+            # Restore stdout if needed
+            if stderr_mode and sys.stdout != old_stdout:
+                sys.stdout.close()
+                sys.stdout = old_stdout
             ui_console.print("\n[yellow]Cancelled (EOF)[/yellow]")
             return None
         except ValueError:
             ui_console.print("[red]Invalid choice. Please try again.[/red]")
 
 
+def show_action_menu(session_info: Tuple[str, float, int, str, str, str, Optional[str]]) -> Optional[str]:
+    """
+    Show action menu for selected session.
+
+    Returns: action choice ('resume', 'path', 'copy') or None if cancelled
+    """
+    session_id, _, _, project_name, _, project_path, git_branch = session_info
+
+    print(f"\n=== Session: {session_id[:8]}... ===")
+    print(f"Project: {project_name}")
+    if git_branch:
+        print(f"Branch: {git_branch}")
+    print(f"\nWhat would you like to do?")
+    print("1. Resume session (default)")
+    print("2. Show session file path")
+    print("3. Copy session file to file (*.jsonl) or directory")
+    print()
+
+    try:
+        choice = input("Enter choice [1-3] (or Enter for 1): ").strip()
+        if not choice or choice == "1":
+            return "resume"
+        elif choice == "2":
+            return "path"
+        elif choice == "3":
+            return "copy"
+        else:
+            print("Invalid choice.")
+            return None
+    except KeyboardInterrupt:
+        print("\nCancelled.")
+        return None
+
+
+def get_session_file_path(session_id: str, project_path: str, claude_home: Optional[str] = None) -> str:
+    """Get the full file path for a session."""
+    # Convert project path to Claude directory format
+    base_dir = Path(claude_home).expanduser() if claude_home else Path.home() / ".claude"
+    encoded_path = project_path.replace("/", "-")
+    claude_project_dir = base_dir / "projects" / encoded_path
+    return str(claude_project_dir / f"{session_id}.jsonl")
+
+
+def copy_session_file(session_file_path: str) -> None:
+    """Copy session file to user-specified file or directory."""
+    try:
+        dest = input("\nEnter destination file or directory path: ").strip()
+        if not dest:
+            print("Cancelled.")
+            return
+
+        dest_path = Path(dest).expanduser()
+        source = Path(session_file_path)
+
+        # Determine if destination is a directory or file
+        if dest_path.exists():
+            if dest_path.is_dir():
+                # Copy into directory with original filename
+                dest_file = dest_path / source.name
+            else:
+                # Copy to specified file
+                dest_file = dest_path
+        else:
+            # Destination doesn't exist - check if it looks like a directory
+            if dest.endswith('/') or dest.endswith(os.sep):
+                # Treat as directory - create it
+                create = input(f"Directory {dest_path} does not exist. Create it? [y/N]: ").strip().lower()
+                if create in ('y', 'yes'):
+                    dest_path.mkdir(parents=True, exist_ok=True)
+                    dest_file = dest_path / source.name
+                else:
+                    print("Cancelled.")
+                    return
+            else:
+                # Treat as file - create parent directory if needed
+                parent = dest_path.parent
+                if not parent.exists():
+                    create = input(f"Parent directory {parent} does not exist. Create it? [y/N]: ").strip().lower()
+                    if create in ('y', 'yes'):
+                        parent.mkdir(parents=True, exist_ok=True)
+                    else:
+                        print("Cancelled.")
+                        return
+                dest_file = dest_path
+
+        import shutil
+        shutil.copy2(source, dest_file)
+        print(f"\nCopied to: {dest_file}")
+
+    except KeyboardInterrupt:
+        print("\nCancelled.")
+    except Exception as e:
+        print(f"\nError copying file: {e}")
+
+
 def resume_session(session_id: str, project_path: str, shell_mode: bool = False):
     """Resume a Claude session using claude -r command."""
     current_dir = os.getcwd()
@@ -511,10 +641,26 @@ To persist directory changes when resuming sessions:
     
     # If we have rich and there are results, show interactive UI
     if RICH_AVAILABLE and console:
-        result = display_interactive_ui(matching_sessions, keywords, stderr_mode=args.shell, num_matches=args.num_matches)
-        if result:
-            session_id, project_path = result
-            resume_session(session_id, project_path, shell_mode=args.shell)
+        selected_session = display_interactive_ui(matching_sessions, keywords, stderr_mode=args.shell, num_matches=args.num_matches)
+        if selected_session:
+            # Show action menu
+            action = show_action_menu(selected_session)
+            if not action:
+                return
+
+            session_id = selected_session[0]
+            project_path = selected_session[5]
+
+            # Perform selected action
+            if action == "resume":
+                resume_session(session_id, project_path, shell_mode=args.shell)
+            elif action == "path":
+                session_file_path = get_session_file_path(session_id, project_path, args.claude_home)
+                print(f"\nSession file path:")
+                print(session_file_path)
+            elif action == "copy":
+                session_file_path = get_session_file_path(session_id, project_path, args.claude_home)
+                copy_session_file(session_file_path)
     else:
         # Fallback: print session IDs as before
         if not args.shell:

claude_code_tools/find_codex_session.py

@@ -0,0 +1,562 @@
+#!/usr/bin/env python3
+"""
+Find and resume Codex sessions by searching keywords in session history.
+
+Usage:
+    find-codex-session "keywords" [OPTIONS]
+    fcs-codex "keywords" [OPTIONS]  # via shell wrapper
+
+Examples:
+    find-codex-session "langroid,MCP"           # Current project only
+    find-codex-session "error,debugging" -g     # All projects
+    find-codex-session "keywords" -n 5          # Limit results
+    fcs-codex "keywords" --shell                # Via shell wrapper
+"""
+
+import argparse
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+try:
+    from rich.console import Console
+    from rich.table import Table
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+
+def get_codex_home(custom_home: Optional[str] = None) -> Path:
+    """Get the Codex home directory."""
+    if custom_home:
+        return Path(custom_home).expanduser()
+    return Path.home() / ".codex"
+
+
+def extract_session_id_from_filename(filename: str) -> Optional[str]:
+    """
+    Extract session ID from Codex session filename.
+
+    Format: rollout-YYYY-MM-DDTHH-MM-SS-<SESSION_ID>.jsonl
+    Returns: SESSION_ID portion
+    """
+    # Pattern: anything after the timestamp part
+    # e.g., rollout-2025-10-07T13-48-15-0199bfc9-c444-77e1-8c8a-f91c94fcd832.jsonl
+    match = re.match(
+        r"rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-(.+)\.jsonl", filename
+    )
+    if match:
+        return match.group(1)
+    return None
+
+
+def extract_session_metadata(session_file: Path) -> Optional[dict]:
+    """
+    Extract metadata from the first session_meta entry in a Codex session file.
+
+    Returns dict with: id, cwd, branch, timestamp
+    """
+    try:
+        with open(session_file, "r", encoding="utf-8") as f:
+            for line in f:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                    if entry.get("type") == "session_meta":
+                        payload = entry.get("payload", {})
+                        git_info = payload.get("git", {})
+                        return {
+                            "id": payload.get("id", ""),
+                            "cwd": payload.get("cwd", ""),
+                            "branch": git_info.get("branch", ""),
+                            "timestamp": payload.get("timestamp", ""),
+                        }
+                except json.JSONDecodeError:
+                    continue
+        return None
+    except (OSError, IOError):
+        return None
+
+
+def get_project_name(cwd: str) -> str:
+    """Extract project name from working directory path."""
+    if not cwd:
+        return "unknown"
+    path = Path(cwd)
+    return path.name if path.name else "unknown"
+
+
+def is_system_message(text: str) -> bool:
+    """Check if text is system-generated (XML tags, env context, etc)"""
+    if not text or len(text.strip()) < 5:
+        return True
+    text = text.strip()
+    # Check for XML-like tags (user_instructions, environment_context, etc)
+    if text.startswith("<") and ">" in text[:100]:
+        return True
+    return False
+
+
+def search_keywords_in_file(
+    session_file: Path, keywords: list[str]
+) -> tuple[bool, int, Optional[str]]:
+    """
+    Search for keywords in a Codex session file.
+
+    Returns: (found, line_count, preview)
+    - found: True if all keywords found (case-insensitive AND logic)
+    - line_count: total lines in file
+    - preview: best user message content (skips system messages)
+    """
+    keywords_lower = [k.lower() for k in keywords]
+    found_keywords = set()
+    line_count = 0
+    last_user_message = None  # Keep track of the LAST user message
+
+    try:
+        with open(session_file, "r", encoding="utf-8") as f:
+            for line in f:
+                line_count += 1
+                if not line.strip():
+                    continue
+
+                try:
+                    entry = json.loads(line)
+
+                    # Extract user messages (skip system messages)
+                    # Keep updating to get the LAST one
+                    if (
+                        entry.get("type") == "response_item"
+                        and entry.get("payload", {}).get("role") == "user"
+                    ):
+                        content = entry.get("payload", {}).get("content", [])
+                        if isinstance(content, list) and len(content) > 0:
+                            first_item = content[0]
+                            if isinstance(first_item, dict):
+                                text = first_item.get("text", "")
+                                if text and not is_system_message(text):
+                                    # Keep updating with latest message
+                                    cleaned = text[:400].replace("\n", " ").strip()
+                                    # Only keep if it's substantial (>20 chars)
+                                    if len(cleaned) > 20:
+                                        last_user_message = cleaned
+                                    elif last_user_message is None:
+                                        # Keep even short messages if no better option
+                                        last_user_message = cleaned
+
+                    # Search for keywords in all text content
+                    line_lower = line.lower()
+                    for kw in keywords_lower:
+                        if kw in line_lower:
+                            found_keywords.add(kw)
+
+                except json.JSONDecodeError:
+                    continue
+
+        all_found = len(found_keywords) == len(keywords_lower)
+        return all_found, line_count, last_user_message
+
+    except (OSError, IOError):
+        return False, 0, None
+
+
+def find_sessions(
+    codex_home: Path,
+    keywords: list[str],
+    num_matches: int = 10,
+    global_search: bool = False,
+) -> list[dict]:
+    """
+    Find Codex sessions matching keywords.
+
+    Args:
+        codex_home: Path to Codex home directory
+        keywords: List of keywords to search for
+        num_matches: Maximum number of results to return
+        global_search: If False, filter to current directory only
+
+    Returns list of dicts with: session_id, project, branch, date,
+                                 lines, preview, cwd, file_path
+    """
+    sessions_dir = codex_home / "sessions"
+    if not sessions_dir.exists():
+        return []
+
+    # Get current directory for filtering (if not global search)
+    current_cwd = os.getcwd() if not global_search else None
+
+    matches = []
+
+    # Walk through YYYY/MM/DD directory structure
+    for year_dir in sorted(sessions_dir.iterdir(), reverse=True):
+        if not year_dir.is_dir():
+            continue
+
+        for month_dir in sorted(year_dir.iterdir(), reverse=True):
+            if not month_dir.is_dir():
+                continue
+
+            for day_dir in sorted(month_dir.iterdir(), reverse=True):
+                if not day_dir.is_dir():
+                    continue
+
+                # Process all JSONL files in this day
+                session_files = sorted(
+                    day_dir.glob("rollout-*.jsonl"), reverse=True
+                )
+
+                for session_file in session_files:
+                    # Search for keywords
+                    found, line_count, preview = search_keywords_in_file(
+                        session_file, keywords
+                    )
+
+                    if not found:
+                        continue
+
+                    # Extract metadata
+                    metadata = extract_session_metadata(session_file)
+                    if not metadata:
+                        # Fallback: extract session ID from filename
+                        session_id = extract_session_id_from_filename(
+                            session_file.name
+                        )
+                        if not session_id:
+                            continue
+                        metadata = {
+                            "id": session_id,
+                            "cwd": "",
+                            "branch": "",
+                            "timestamp": "",
+                        }
+
+                    # Filter by current directory if not global search
+                    if current_cwd and metadata["cwd"] != current_cwd:
+                        continue
+
+                    # Parse timestamp
+                    timestamp_str = metadata["timestamp"]
+                    if timestamp_str:
+                        try:
+                            dt = datetime.fromisoformat(
+                                timestamp_str.replace("Z", "+00:00")
+                            )
+                            date_str = dt.strftime("%Y-%m-%d %H:%M")
+                        except ValueError:
+                            date_str = timestamp_str[:16]
+                    else:
+                        # Fallback to directory date
+                        date_str = f"{year_dir.name}-{month_dir.name}-{day_dir.name}"
+
+                    matches.append(
+                        {
+                            "session_id": metadata["id"],
+                            "project": get_project_name(metadata["cwd"]),
+                            "branch": metadata["branch"] or "",
+                            "date": date_str,
+                            "lines": line_count,
+                            "preview": preview or "No preview",
+                            "cwd": metadata["cwd"],
+                            "file_path": str(session_file),
+                        }
+                    )
+
+                    # Early exit if we have enough matches
+                    if len(matches) >= num_matches * 3:
+                        break
+
+    # Sort by date (reverse chronological) and limit
+    matches.sort(key=lambda x: x["date"], reverse=True)
+    return matches[:num_matches]
+
+
+def display_interactive_ui(
+    matches: list[dict],
+) -> Optional[dict]:
+    """
+    Display matches in interactive UI and get user selection.
+
+    Returns: selected match dict or None if cancelled
+    """
+    if not matches:
+        print("No matching sessions found.")
+        return None
+
+    if RICH_AVAILABLE:
+        console = Console()
+        table = Table(title="Codex Sessions", show_header=True)
+        table.add_column("#", style="cyan", justify="right")
+        table.add_column("Session ID", style="yellow", no_wrap=True)
+        table.add_column("Project", style="green")
+        table.add_column("Branch", style="magenta")
+        table.add_column("Date", style="blue")
+        table.add_column("Lines", justify="right")
+        table.add_column("Preview", style="dim", max_width=60, overflow="fold")
+
+        for i, match in enumerate(matches, 1):
+            table.add_row(
+                str(i),
+                match["session_id"][:16] + "...",
+                match["project"],
+                match["branch"],
+                match["date"],
+                str(match["lines"]),
+                match["preview"],  # No truncation, let Rich wrap it
+            )
+
+        console.print(table)
+    else:
+        # Fallback to plain text
+        print("\nMatching Codex Sessions:")
+        print("-" * 80)
+        for i, match in enumerate(matches, 1):
+            print(f"{i}. {match['session_id'][:16]}...")
+            print(f"   Project: {match['project']}")
+            print(f"   Branch: {match['branch']}")
+            print(f"   Date: {match['date']}")
+            print(f"   Preview: {match['preview'][:60]}...")
+            print()
+
+    # Get user selection
+    if len(matches) == 1:
+        print(f"\nAuto-selecting only match: {matches[0]['session_id'][:16]}...")
+        return matches[0]
+
+    try:
+        choice = input(
+            "\nEnter number to select session (or Enter to cancel): "
+        ).strip()
+        if not choice:
+            print("Cancelled.")
+            return None
+
+        idx = int(choice) - 1
+        if 0 <= idx < len(matches):
+            return matches[idx]
+        else:
+            print("Invalid selection.")
+            return None
+    except ValueError:
+        print("Invalid input.")
+        return None
+    except KeyboardInterrupt:
+        print("\nCancelled.")
+        return None
+
+
+def show_action_menu(match: dict) -> Optional[str]:
+    """
+    Show action menu for selected session.
+
+    Returns: action choice ('resume', 'path', 'copy') or None if cancelled
+    """
+    print(f"\n=== Session: {match['session_id'][:16]}... ===")
+    print(f"Project: {match['project']}")
+    print(f"Branch: {match['branch']}")
+    print(f"\nWhat would you like to do?")
+    print("1. Resume session (default)")
+    print("2. Show session file path")
+    print("3. Copy session file to file (*.jsonl) or directory")
+    print()
+
+    try:
+        choice = input("Enter choice [1-3] (or Enter for 1): ").strip()
+        if not choice or choice == "1":
+            return "resume"
+        elif choice == "2":
+            return "path"
+        elif choice == "3":
+            return "copy"
+        else:
+            print("Invalid choice.")
+            return None
+    except KeyboardInterrupt:
+        print("\nCancelled.")
+        return None
+
+
+def copy_session_file(file_path: str) -> None:
+    """Copy session file to user-specified file or directory."""
+    try:
+        dest = input("\nEnter destination file or directory path: ").strip()
+        if not dest:
+            print("Cancelled.")
+            return
+
+        dest_path = Path(dest).expanduser()
+        source = Path(file_path)
+
+        # Determine if destination is a directory or file
+        if dest_path.exists():
+            if dest_path.is_dir():
+                # Copy into directory with original filename
+                dest_file = dest_path / source.name
+            else:
+                # Copy to specified file
+                dest_file = dest_path
+        else:
+            # Destination doesn't exist - check if it looks like a directory
+            if dest.endswith('/') or dest.endswith(os.sep):
+                # Treat as directory - create it
+                create = input(f"Directory {dest_path} does not exist. Create it? [y/N]: ").strip().lower()
+                if create in ('y', 'yes'):
+                    dest_path.mkdir(parents=True, exist_ok=True)
+                    dest_file = dest_path / source.name
+                else:
+                    print("Cancelled.")
+                    return
+            else:
+                # Treat as file - create parent directory if needed
+                parent = dest_path.parent
+                if not parent.exists():
+                    create = input(f"Parent directory {parent} does not exist. Create it? [y/N]: ").strip().lower()
+                    if create in ('y', 'yes'):
+                        parent.mkdir(parents=True, exist_ok=True)
+                    else:
+                        print("Cancelled.")
+                        return
+                dest_file = dest_path
+
+        import shutil
+        shutil.copy2(source, dest_file)
+        print(f"\nCopied to: {dest_file}")
+
+    except KeyboardInterrupt:
+        print("\nCancelled.")
+    except Exception as e:
+        print(f"\nError copying file: {e}")
+
+
+def resume_session(
+    session_id: str, cwd: str, shell_mode: bool = False
+) -> None:
+    """
+    Resume a Codex session.
+
+    In shell mode: outputs commands for eval
+    In interactive mode: executes codex resume
+    """
+    if shell_mode:
+        # Output commands for shell eval
+        # Redirect prompts to stderr, commands to stdout
+        if cwd and cwd != os.getcwd():
+            print(f"cd {shlex.quote(cwd)}", file=sys.stdout)
+        print(f"codex resume {shlex.quote(session_id)}", file=sys.stdout)
+    else:
+        # Interactive mode
+        if cwd and cwd != os.getcwd():
+            response = input(
+                f"\nSession is in different directory: {cwd}\n"
+                "Change directory and resume? [Y/n]: "
+            ).strip()
+            if response.lower() in ("", "y", "yes"):
+                try:
+                    os.chdir(cwd)
+                    print(f"Changed to: {cwd}")
+                except OSError as e:
+                    print(f"Error changing directory: {e}")
+                    return
+
+        # Execute codex resume
+        try:
+            os.execvp("codex", ["codex", "resume", session_id])
+        except OSError as e:
+            print(f"Error launching codex: {e}")
+            sys.exit(1)
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Find and resume Codex sessions by keyword search",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  find-codex-session "langroid,MCP"           # Current project only
+  find-codex-session "error,debugging" -g     # All projects
+  find-codex-session "keywords" -n 5          # Limit results
+  fcs-codex "keywords" --shell                # Via shell wrapper
+        """,
+    )
+
+    parser.add_argument(
+        "keywords",
+        help="Comma-separated keywords to search (AND logic)",
+    )
+    parser.add_argument(
+        "-g",
+        "--global",
+        dest="global_search",
+        action="store_true",
+        help="Search all projects (default: current project only)",
+    )
+    parser.add_argument(
+        "-n",
+        "--num-matches",
+        type=int,
+        default=10,
+        help="Number of matches to display (default: 10)",
+    )
+    parser.add_argument(
+        "--shell",
+        action="store_true",
+        help="Output shell commands for eval (enables persistent cd)",
+    )
+    parser.add_argument(
+        "--codex-home",
+        help="Custom Codex home directory (default: ~/.codex)",
+    )
+
+    args = parser.parse_args()
+
+    # Parse keywords
+    keywords = [k.strip() for k in args.keywords.split(",") if k.strip()]
+    if not keywords:
+        print("Error: No keywords provided", file=sys.stderr)
+        sys.exit(1)
+
+    # Get Codex home
+    codex_home = get_codex_home(args.codex_home)
+    if not codex_home.exists():
+        print(f"Error: Codex home not found: {codex_home}", file=sys.stderr)
+        sys.exit(1)
+
+    # Find matching sessions
+    matches = find_sessions(
+        codex_home, keywords, args.num_matches, args.global_search
+    )
+
+    # Display and get selection
+    selected_match = display_interactive_ui(matches)
+    if not selected_match:
+        return
+
+    # Show action menu
+    action = show_action_menu(selected_match)
+    if not action:
+        return
+
+    # Perform selected action
+    if action == "resume":
+        resume_session(
+            selected_match["session_id"],
+            selected_match["cwd"],
+            args.shell
+        )
+    elif action == "path":
+        print(f"\nSession file path:")
+        print(selected_match["file_path"])
+    elif action == "copy":
+        copy_session_file(selected_match["file_path"])
+
+
+if __name__ == "__main__":
+    main()

{claude_code_tools-0.1.21.dist-info → claude_code_tools-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 0.1.21
+Version: 0.2.1
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -17,6 +17,24 @@ Description-Content-Type: text/markdown
 A collection of practical tools, hooks, and utilities for enhancing Claude Code
 and other CLI coding agents.
 
+## Table of Contents
+
+- [🎮 tmux-cli: Bridging Claude Code and Interactive CLIs — "playwright for the terminal"](#tmux-cli-bridging-claude-code-and-interactive-clis)
+- [🚀 Quick Start](#quick-start)
+- [🎮 tmux-cli Deep Dive](#tmux-cli-deep-dive)
+- [🚀 lmsh (Experimental) — natural language to shell commands](#lmsh-experimental)
+- [🔍 find-claude-session — search and resume Claude sessions](#find-claude-session)
+- [🔍 find-codex-session — search and resume Codex sessions](#find-codex-session)
+- [🔐 vault — encrypted .env backup & sync](#vault)
+- [🔍 env-safe — inspect .env safely without values](#env-safe)
+- [🛡️ Claude Code Safety Hooks — guardrails for bash, git, env, files](#claude-code-safety-hooks)
+- [🤖 Using Claude Code with Open-weight Anthropic API-compatible LLM Providers](#using-claude-code-with-open-weight-anthropic-api-compatible-llm-providers)
+- [📚 Documentation](#documentation)
+- [📋 Requirements](#requirements)
+- [🛠️ Development](#development)
+- [📄 License](#license)
+
+<a id="tmux-cli-bridging-claude-code-and-interactive-clis"></a>
 ## 🎮 tmux-cli: Bridging Claude Code and Interactive CLIs
 
 > **Note**: While the description below focuses on Claude Code, tmux-cli works with any CLI coding agent.
@@ -50,6 +68,7 @@ use tmux-cli behind the scenes.
 
 **Works anywhere**: Automatically handles both local tmux panes and remote sessions.
 
+<a id="quick-start"></a>
 ## 🚀 Quick Start
 
 ```bash
@@ -63,9 +82,11 @@ uv tool install git+https://github.com/pchalasani/claude-code-tools
 This gives you:
 - `tmux-cli` - The interactive CLI controller we just covered
 - `find-claude-session` - Search and resume Claude Code sessions by keywords
+- `find-codex-session` - Search and resume Codex sessions by keywords
 - `vault` - Encrypted backup for your .env files
 - `env-safe` - Safely inspect .env files without exposing values
 
+<a id="tmux-cli-deep-dive"></a>
 ## 🎮 tmux-cli Deep Dive
 
 ### What Claude Code Can Do With tmux-cli
@@ -117,6 +138,7 @@ claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer
 
 For detailed instructions, see [docs/tmux-cli-instructions.md](docs/tmux-cli-instructions.md).
 
+<a id="lmsh-experimental"></a>
 ## 🚀 lmsh (Experimental)
 
 Natural language shell - type what you want in plain English, get an editable command.
@@ -134,11 +156,11 @@ docker ps -n 5  # <-- Edit before running
 
 **Features:**
 - Rust-based for instant startup (<1ms binary load time)
-- Translates natural language to shell commands using Claude
+- Translates natural language to shell commands using Claude Code CLI
 - Commands are editable before execution - full control
 - Preserves your shell environment
 
-**Note:** Claude API adds ~3-5s latency. Future versions may use local models for instant response.
+**Note:** Requires Claude Code CLI (`claude` command) to be installed. The translation adds ~2-3s due to Claude Code CLI startup.
 
 **Installation:**
 ```bash
@@ -153,6 +175,7 @@ cp target/release/lmsh ~/.cargo/bin/
 
 See [docs/lmsh.md](docs/lmsh.md) for details.
 
+<a id="find-claude-session"></a>
 ## 🔍 find-claude-session
 
 Search and resume Claude Code sessions by keywords with an interactive UI.
@@ -202,10 +225,54 @@ won't persist after exiting Claude Code.
 
 For detailed documentation, see [docs/find-claude-session.md](docs/find-claude-session.md).
 
-Looks like this -- 
+Looks like this --
 
-![fcs.png](docs/fcs.png)
+![find-claude-session.png](demos/find-claude-session.png)
 
+<a id="find-codex-session"></a>
+## 🔍 find-codex-session
+
+Search and resume Codex sessions by keywords. Usage is similar to `find-claude-session` above, but works with Codex session files instead.
+
+### Key Differences from find-claude-session
+
+- Searches `~/.codex/sessions/` (organized by YYYY/MM/DD directories)
+- Extracts metadata from `session_meta` entries in Codex JSONL files
+- Resumes sessions with `codex resume <session-id>`
+
+### Usage
+
+```bash
+# Search in current project only (default)
+find-codex-session "keyword1,keyword2"
+
+# Search across all projects
+find-codex-session "keywords" -g
+find-codex-session "keywords" --global
+
+# Limit number of results
+find-codex-session "keywords" -n 5
+
+# Custom Codex home directory
+find-codex-session "keywords" --codex-home /custom/path
+```
+
+### Features
+
+- **Project filtering**: Search current project only (default) or all projects with `-g`
+- Case-insensitive AND keyword search across all session content
+- Interactive session selection with Rich table display
+- Shows project name, git branch, date, line count, and preview of last user message
+- Automatic session resumption with `codex resume`
+- Cross-project session support with directory change prompts
+- Reverse chronological ordering (most recent first)
+- Multi-line preview wrapping for better readability
+
+Looks like this --
+
+![find-codex-session.png](demos/find-codex-session.png)
+
+<a id="vault"></a>
 ## 🔐 vault
 
 Centralized encrypted backup for .env files across all your projects using SOPS.
@@ -227,6 +294,7 @@ vault status    # Check sync status for current project
 
 For detailed documentation, see [docs/vault-documentation.md](docs/vault-documentation.md).
 
+<a id="env-safe"></a>
 ## 🔍 env-safe
 
 Safely inspect .env files without exposing sensitive values. Designed for Claude Code and other automated tools that need to work with environment files without accidentally leaking secrets.
@@ -252,6 +320,7 @@ env-safe --help                  # See all options
 
 Claude Code is completely blocked from directly accessing .env files - no reading, writing, or editing allowed. This prevents both accidental exposure of API keys and unintended modifications. The `env-safe` command provides the only approved way for Claude Code to inspect environment configuration safely, while any modifications must be done manually outside of Claude Code.
 
+<a id="claude-code-safety-hooks"></a>
 ## 🛡️ Claude Code Safety Hooks
 
 This repository includes a comprehensive set of safety hooks that enhance Claude
@@ -261,8 +330,11 @@ Code's behavior and prevent dangerous operations.
 
 - **File Deletion Protection** - Blocks `rm` commands, enforces TRASH directory
   pattern
-- **Git Safety** - Prevents dangerous `git add -A`, unsafe checkouts, and
-  accidental data loss  
+- **Git Safety** - Advanced git add protection with:
+  - Hard blocks: `git add .`, `git add ../`, `git add *`, `git add -A/--all`
+  - Speed bumps: Shows files before staging directories (e.g., `git add src/`)
+  - Commit speed bump: Warns on first attempt, allows on second
+  - Prevents unsafe checkouts and accidental data loss
 - **Environment Security** - Blocks all .env file operations (read/write/edit),
   suggests `env-safe` command for safe inspection
 - **Context Management** - Blocks reading files >500 lines to prevent context
@@ -299,10 +371,12 @@ Code's behavior and prevent dangerous operations.
 
 For complete documentation, see [hooks/README.md](hooks/README.md).
 
+<a id="using-claude-code-with-open-weight-anthropic-api-compatible-llm-providers"></a>
 ## 🤖 Using Claude Code with Open-weight Anthropic API-compatible LLM Providers
 
 You can use Claude Code with alternative LLMs served via Anthropic-compatible
-APIs. Add these functions to your shell config (.bashrc/.zshrc):
+APIs, e.g. Kimi-k2, GLM4.5 (from zai), Deepseek-v3.1. 
+Add these functions to your shell config (.bashrc/.zshrc):
 
 ```bash
 kimi() {
@@ -320,18 +394,30 @@ zai() {
         claude "$@"
     )
 }
+
+dseek() {
+    (
+        export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
+        export ANTHROPIC_AUTH_TOKEN=${DEEPSEEK_API_KEY}
+        export ANTHROPIC_MODEL=deepseek-chat
+        export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat        
+        claude "$@"
+    )
+}
 ```
 
 After adding these functions:
-- Set your API keys: `export KIMI_API_KEY=your-kimi-key` and 
-  `export Z_API_KEY=your-z-key`
+- Set your API keys: `export KIMI_API_KEY=your-kimi-key`,
+  `export Z_API_KEY=your-z-key`, `export DEEPSEEK_API_KEY=your-deepseek-key`
 - Run `kimi` to use Claude Code with the Kimi K2 LLM
 - Run `zai` to use Claude Code with the GLM-4.5 model
+- Run `dseek` to use Claude Code with the DeepSeek model
 
 The functions use subshells to ensure the environment variables don't affect 
 your main shell session, so you could be running multiple instances of Claude Code,
 each using a different LLM.
 
+<a id="documentation"></a>
 ## 📚 Documentation
 
 - [tmux-cli detailed instructions](docs/tmux-cli-instructions.md) - 
@@ -342,6 +428,7 @@ each using a different LLM.
   Complete guide for the .env backup system
 - [Hook configuration](hooks/README.md) - Setting up Claude Code hooks
 
+<a id="requirements"></a>
 ## 📋 Requirements
 
 - Python 3.11+
@@ -349,6 +436,7 @@ each using a different LLM.
 - tmux (for tmux-cli functionality)
 - SOPS (for vault functionality)
 
+<a id="development"></a>
 ## 🛠️ Development
 
 ### Setup
@@ -405,6 +493,7 @@ Run `make help` to see all available commands:
 - `make release` - Bump patch version and install globally
 - `make patch/minor/major` - Version bump commands
 
+<a id="license"></a>
 ## 📄 License
 
 MIT

{claude_code_tools-0.1.21.dist-info → claude_code_tools-0.2.1.dist-info}/RECORD

@@ -1,8 +1,9 @@
-claude_code_tools/__init__.py,sha256=qRAVB_-ZIkNZrN86fSSuzUt33irrFIhEkjnCus9Eyr0,90
+claude_code_tools/__init__.py,sha256=AzSPIlHglKw2AVy9dWwJmnRBYKIN4vLOFYIfPXvjtqE,89
 claude_code_tools/codex_bridge_mcp.py,sha256=0roYm3YgEFB6y2MvGovzHyY7avKtire4qBtz3kVaYoY,12596
 claude_code_tools/dotenv_vault.py,sha256=KPI9NDFu5HE6FfhQUYw6RhdR-miN0ScJHsBg0OVG61k,9617
 claude_code_tools/env_safe.py,sha256=TSSkOjEpzBwNgbeSR-0tR1-pAW_qmbZNmn3fiAsHJ4w,7659
-claude_code_tools/find_claude_session.py,sha256=TfQWW2zMDJAnfLREt_P23BB6e9Qb-XS22SSEU80K-4Y,23524
+claude_code_tools/find_claude_session.py,sha256=06xGZCG5kGN2IxSKf0oCVKl_CrC8JYbInl8c7OKwUm8,28929
+claude_code_tools/find_codex_session.py,sha256=NvFATapn8aGTXOJmhu8tis9PA12ZpKz7cWYRsZ4vMSQ,19003
 claude_code_tools/tmux_cli_controller.py,sha256=5QDrDlv3oabIghRHuP8jMhUfxPeyYZxizNWW5sVuJIg,34607
 claude_code_tools/tmux_remote_controller.py,sha256=eY1ouLtUzJ40Ik4nqUBvc3Gl1Rx0_L4TFW4j708lgvI,9942
 docs/cc-codex-instructions.md,sha256=5E9QotkrcVYIE5VrvJGi-sg7tdyITDrsbhaqBKr4MUk,1109
@@ -10,12 +11,12 @@ docs/claude-code-chutes.md,sha256=jCnYAAHZm32NGHE0CzGGl3vpO_zlF_xdmr23YxuCjPg,80
 docs/claude-code-tmux-tutorials.md,sha256=S-9U3a1AaPEBPo3oKpWuyOfKK7yPFOIu21P_LDfGUJk,7558
 docs/dot-zshrc.md,sha256=DC2fOiGrUlIzol6N_47CW53a4BsnMEvCnhlRRVxFCTc,7160
 docs/find-claude-session.md,sha256=fACbQP0Bj5jqIpNWk0lGDOQQaji-K9Va3gUv2RA47VQ,4284
-docs/lmsh.md,sha256=S3o9WHzK0hytb7f05IoHFoN-azXJxUDeUPOuxPHvZM0,1230
+docs/lmsh.md,sha256=o2TNP1Yfl3zW23GzEqK8Bx6z1hQof_lplaeEucuHNRU,1335
 docs/reddit-post.md,sha256=ZA7kPoJNi06t6F9JQMBiIOv039ADC9lM8YXFt8UA_Jg,2345
 docs/tmux-cli-instructions.md,sha256=hKGOdaPdBlb5XFzHfi0Mm7CVlysBuJUAfop3GHreyuw,5008
 docs/vault-documentation.md,sha256=5XzNpHyhGU38JU2hKEWEL1gdPq3rC2zBg8yotK4eNF4,3600
-claude_code_tools-0.1.21.dist-info/METADATA,sha256=quyxwy3WCzHdg_Xp3wXYeMOQL2FicmC5DarhWJBzRbA,13341
-claude_code_tools-0.1.21.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-claude_code_tools-0.1.21.dist-info/entry_points.txt,sha256=AdJXTNrrAbUp0EhSRQuA0IBjFLBUXdqh7nuBYVFEAig,224
-claude_code_tools-0.1.21.dist-info/licenses/LICENSE,sha256=BBQdOBLdFB3CEPmb3pqxeOThaFCIdsiLzmDANsCHhoM,1073
-claude_code_tools-0.1.21.dist-info/RECORD,,
+claude_code_tools-0.2.1.dist-info/METADATA,sha256=hRnH4OIKTQL9oTuoG0XEMPn-LPT78EJkaLYiA9fAbqg,17034
+claude_code_tools-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+claude_code_tools-0.2.1.dist-info/entry_points.txt,sha256=rAHzNUN7b_HIRbFlvpYwK38FG6jREYWaO0ssnhAVPrg,287
+claude_code_tools-0.2.1.dist-info/licenses/LICENSE,sha256=BBQdOBLdFB3CEPmb3pqxeOThaFCIdsiLzmDANsCHhoM,1073
+claude_code_tools-0.2.1.dist-info/RECORD,,

{claude_code_tools-0.1.21.dist-info → claude_code_tools-0.2.1.dist-info}/entry_points.txt

@@ -1,5 +1,6 @@
 [console_scripts]
 env-safe = claude_code_tools.env_safe:main
 find-claude-session = claude_code_tools.find_claude_session:main
+find-codex-session = claude_code_tools.find_codex_session:main
 tmux-cli = claude_code_tools.tmux_cli_controller:main
 vault = claude_code_tools.dotenv_vault:main

docs/lmsh.md

@@ -40,9 +40,9 @@ lmsh --version                # Version info
 
 - **Editable commands** - Review and modify before execution
 - **Fast startup** - Optimized Rust binary (~1ms)
-- **Claude-powered** - Uses Claude for natural language understanding
+- **Claude-powered** - Leverages your existing Claude Code CLI by calling `claude -p <prompt>` in non-interactive mode
 - **Shell preservation** - Maintains your shell environment and aliases
 
 ## Note
 
-Claude's API startup adds ~2-3s latency. Future versions may explore faster local models for instant response.
+This tool requires the Claude Code CLI (`claude` command) to be installed and configured. The translation step adds ~2-3s latency due to Claude Code CLI startup time.