claude-code-tools 0.1.21__tar.gz → 0.2.0__tar.gz

{claude_code_tools-0.1.21 → claude_code_tools-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 0.1.21
+Version: 0.2.0
 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.
@@ -206,6 +229,46 @@ Looks like this --
 
 ![fcs.png](docs/fcs.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
+
+<a id="vault"></a>
 ## 🔐 vault
 
 Centralized encrypted backup for .env files across all your projects using SOPS.
@@ -227,6 +290,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 +316,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 +326,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 +367,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 +390,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 +424,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 +432,7 @@ each using a different LLM.
 - tmux (for tmux-cli functionality)
 - SOPS (for vault functionality)
 
+<a id="development"></a>
 ## 🛠️ Development
 
 ### Setup
@@ -405,6 +489,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 → claude_code_tools-0.2.0}/README.md

@@ -3,6 +3,24 @@
 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.
@@ -36,6 +54,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
@@ -49,9 +68,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
@@ -103,6 +124,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.
@@ -120,11 +142,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
@@ -139,6 +161,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.
@@ -192,6 +215,46 @@ Looks like this --
 
 ![fcs.png](docs/fcs.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
+
+<a id="vault"></a>
 ## 🔐 vault
 
 Centralized encrypted backup for .env files across all your projects using SOPS.
@@ -213,6 +276,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.
@@ -238,6 +302,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
@@ -247,8 +312,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
@@ -285,10 +353,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() {
@@ -306,18 +376,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) - 
@@ -328,6 +410,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+
@@ -335,6 +418,7 @@ each using a different LLM.
 - tmux (for tmux-cli functionality)
 - SOPS (for vault functionality)
 
+<a id="development"></a>
 ## 🛠️ Development
 
 ### Setup
@@ -391,6 +475,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 → claude_code_tools-0.2.0}/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.0"

{claude_code_tools-0.1.21 → claude_code_tools-0.2.0}/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')

claude_code_tools-0.2.0/claude_code_tools/find_codex_session.py

@@ -0,0 +1,458 @@
+#!/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[tuple[str, str]]:
+    """
+    Display matches in interactive UI and get user selection.
+
+    Returns: (session_id, cwd) 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]["session_id"], matches[0]["cwd"]
+
+    try:
+        choice = input(
+            "\nEnter number to resume session (or Enter to cancel): "
+        ).strip()
+        if not choice:
+            return None
+
+        idx = int(choice) - 1
+        if 0 <= idx < len(matches):
+            return matches[idx]["session_id"], matches[idx]["cwd"]
+        else:
+            print("Invalid selection.")
+            return None
+    except (ValueError, KeyboardInterrupt):
+        print("\nCancelled.")
+        return None
+
+
+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
+    result = display_interactive_ui(matches)
+    if result:
+        session_id, cwd = result
+        resume_session(session_id, cwd, args.shell)
+
+
+if __name__ == "__main__":
+    main()

{claude_code_tools-0.1.21 → claude_code_tools-0.2.0}/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.

{claude_code_tools-0.1.21 → claude_code_tools-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-code-tools"
-version = "0.1.21"
+version = "0.2.0"
 description = "Collection of tools for working with Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -16,6 +16,7 @@ dev = ["commitizen>=3.0.0"]
 
 [project.scripts]
 find-claude-session = "claude_code_tools.find_claude_session:main"
+find-codex-session = "claude_code_tools.find_codex_session:main"
 vault = "claude_code_tools.dotenv_vault:main"
 tmux-cli = "claude_code_tools.tmux_cli_controller:main"
 env-safe = "claude_code_tools.env_safe:main"
@@ -42,7 +43,7 @@ exclude = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.1.21"
+version = "0.2.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:version",