claude-code-tools 1.0.6__py3-none-any.whl → 1.4.6__py3-none-any.whl

claude_code_tools/search_index.py

@@ -2,14 +2,25 @@
 
 import json
 import math
+import shutil
 import sys
 from dataclasses import dataclass
 from datetime import datetime
+from importlib.metadata import version as get_pkg_version
 from pathlib import Path
 from typing import Any, Optional
 
+from claude_code_tools.export_session import _is_meta_user_message
 from claude_code_tools.session_utils import is_valid_session
 
+
+def _get_package_version() -> str:
+    """Get installed package version for automatic index rebuilding."""
+    try:
+        return get_pkg_version("claude-code-tools")
+    except Exception:
+        return "unknown"
+
 # Lazy imports to allow module to load even if deps not installed
 try:
     import yaml
@@ -167,6 +178,7 @@ class SessionIndex:
         self.schema_builder.add_text_field("first_msg_content", stored=True)
         self.schema_builder.add_text_field("last_msg_role", stored=True)
         self.schema_builder.add_text_field("last_msg_content", stored=True)
+        self.schema_builder.add_text_field("first_user_msg_content", stored=True)
 
         # Session type fields (for filtering in TUI)
         self.schema_builder.add_text_field("derivation_type", stored=True)
@@ -176,6 +188,9 @@ class SessionIndex:
         # Use "raw" tokenizer so paths are indexed as single tokens for exact matching
         self.schema_builder.add_text_field("claude_home", stored=True, tokenizer_name="raw")
 
+        # Custom title field (from /rename command)
+        self.schema_builder.add_text_field("custom_title", stored=True)
+
         # Searchable content field
         self.schema_builder.add_text_field("content", stored=True)
 
@@ -184,10 +199,43 @@ class SessionIndex:
         # Create or open index
         self.index_path.mkdir(parents=True, exist_ok=True)
 
-        if (self.index_path / "meta.json").exists():
-            self.index = tantivy.Index(self.schema, path=str(self.index_path))
-        else:
-            self.index = tantivy.Index(self.schema, path=str(self.index_path))
+        # Check index version - rebuild if package version changed
+        version_file = self.index_path / "VERSION"
+        current_version = _get_package_version()
+        needs_rebuild = False
+
+        if version_file.exists():
+            try:
+                stored_version = version_file.read_text().strip()
+                if stored_version != current_version:
+                    needs_rebuild = True
+                    print(
+                        f"Package version changed ({stored_version} -> {current_version}), "
+                        "rebuilding index..."
+                    )
+            except IOError:
+                needs_rebuild = True
+                print("Index version file corrupted, rebuilding...")
+        elif (self.index_path / "meta.json").exists():
+            # Index exists but no VERSION file - legacy index, rebuild
+            needs_rebuild = True
+            print("Upgrading index to versioned format, rebuilding...")
+
+        if needs_rebuild:
+            # Clear index directory contents (but keep the directory itself)
+            for item in self.index_path.iterdir():
+                if item.is_file():
+                    item.unlink()
+                elif item.is_dir():
+                    shutil.rmtree(item)
+            # Reset state tracker
+            self.state = IndexState(self.index_path / "index_state.json")
+
+        # Create or open index
+        self.index = tantivy.Index(self.schema, path=str(self.index_path))
+
+        # Write current version
+        version_file.write_text(current_version)
 
     def _parse_export_file(self, export_path: Path) -> Optional[dict[str, Any]]:
         """
@@ -275,10 +323,12 @@ class SessionIndex:
             # First and last message fields
             first_msg = metadata.get("first_msg", {}) or {}
             last_msg = metadata.get("last_msg", {}) or {}
+            first_user_msg = metadata.get("first_user_msg", {}) or {}
             doc.add_text("first_msg_role", first_msg.get("role", ""))
             doc.add_text("first_msg_content", first_msg.get("content", ""))
             doc.add_text("last_msg_role", last_msg.get("role", ""))
             doc.add_text("last_msg_content", last_msg.get("content", ""))
+            doc.add_text("first_user_msg_content", first_user_msg.get("content", ""))
 
             # Session type fields
             doc.add_text("derivation_type", metadata.get("derivation_type", "") or "")
@@ -287,6 +337,9 @@ class SessionIndex:
                 "true" if metadata.get("is_sidechain") else "false"
             )
 
+            # Custom title (from /rename command)
+            doc.add_text("custom_title", metadata.get("customTitle", "") or "")
+
             doc.add_text("content", parsed["content"])
 
             writer.add_document(doc)
@@ -356,10 +409,12 @@ class SessionIndex:
             # First and last message fields
             first_msg = metadata.get("first_msg", {}) or {}
             last_msg = metadata.get("last_msg", {}) or {}
+            first_user_msg = metadata.get("first_user_msg", {}) or {}
             doc.add_text("first_msg_role", first_msg.get("role", ""))
             doc.add_text("first_msg_content", first_msg.get("content", ""))
             doc.add_text("last_msg_role", last_msg.get("role", ""))
             doc.add_text("last_msg_content", last_msg.get("content", ""))
+            doc.add_text("first_user_msg_content", first_user_msg.get("content", ""))
 
             # Session type fields
             doc.add_text(
@@ -370,6 +425,9 @@ class SessionIndex:
                 "true" if metadata.get("is_sidechain") else "false"
             )
 
+            # Custom title (from /rename command)
+            doc.add_text("custom_title", metadata.get("customTitle", "") or "")
+
             doc.add_text("content", parsed["content"])
 
             writer.add_document(doc)
@@ -426,7 +484,7 @@ class SessionIndex:
 
     def _extract_session_content(
         self, jsonl_path: Path, agent: str
-    ) -> tuple[str, int]:
+    ) -> tuple[str, int, str]:
         """
         Extract searchable content from a session file.
 
@@ -437,10 +495,11 @@ class SessionIndex:
             agent: Agent type ('claude' or 'codex')
 
         Returns:
-            Tuple of (content_string, user_message_count)
+            Tuple of (content_string, user_message_count, custom_title)
         """
         messages = []
         user_count = 0  # Count only user messages for the "lines" metric
+        custom_title = ""  # Session name from /rename command
 
         try:
             with open(jsonl_path, "r", encoding="utf-8") as f:
@@ -454,6 +513,11 @@ class SessionIndex:
                     except json.JSONDecodeError:
                         continue
 
+                    # Check for custom-title (from /rename command)
+                    if data.get("type") == "custom-title":
+                        custom_title = data.get("customTitle", "")
+                        continue
+
                     role: Optional[str] = None
                     text: str = ""
 
@@ -467,9 +531,10 @@ class SessionIndex:
                         message = data.get("message", {})
                         content = message.get("content")
 
-                        # Count user messages, but exclude tool results
-                        # Tool results have content as list with {"type": "tool_result"}
-                        # Real user messages have content as string or list with text
+                        # Count user messages, but exclude:
+                        # - Tool results (content is list with {"type": "tool_result"})
+                        # - Meta messages (isMeta: true, e.g., "Caveat:" warnings)
+                        # - Local command messages (<command-name>, <local-command-stdout>)
                         if role == "user":
                             is_tool_result = (
                                 isinstance(content, list)
@@ -477,7 +542,12 @@ class SessionIndex:
                                 and isinstance(content[0], dict)
                                 and content[0].get("type") == "tool_result"
                             )
-                            if not is_tool_result:
+                            # Check for meta/non-genuine messages
+                            text_content = content if isinstance(content, str) else ""
+                            if (
+                                not is_tool_result
+                                and not _is_meta_user_message(data, text_content)
+                            ):
                                 user_count += 1
 
                         if not content:
@@ -496,6 +566,12 @@ class SessionIndex:
                                     elif block.get("type") == "tool_use":
                                         tool_name = block.get("name", "")
                                         text += f"[Tool: {tool_name}]\n"
+                                        # Index tool input content
+                                        tool_input = block.get("input", {})
+                                        if isinstance(tool_input, dict):
+                                            for value in tool_input.values():
+                                                if isinstance(value, str) and value:
+                                                    text += f"{value}\n"
                                     elif block.get("type") == "tool_result":
                                         result = block.get("content", "")
                                         if isinstance(result, str):
@@ -511,13 +587,23 @@ class SessionIndex:
                             continue
 
                         role = payload.get("role")
-                        if role == "user":
-                            user_count += 1
                         content = payload.get("content", [])
 
                         if not isinstance(content, list):
                             continue
 
+                        # Extract text first to check for meta patterns
+                        codex_text = ""
+                        for block in content:
+                            if isinstance(block, dict):
+                                if block.get("type") in ("input_text", "output_text"):
+                                    codex_text += block.get("text", "")
+
+                        # Count user messages, but exclude non-genuine messages
+                        if role == "user":
+                            if not _is_meta_user_message({}, codex_text):
+                                user_count += 1
+
                         for block in content:
                             if not isinstance(block, dict):
                                 continue
@@ -532,7 +618,7 @@ class SessionIndex:
         except (OSError, IOError):
             pass
 
-        return "\n\n".join(messages), user_count
+        return "\n\n".join(messages), user_count, custom_title
 
     def _parse_jsonl_session(self, jsonl_path: Path) -> Optional[dict[str, Any]]:
         """
@@ -556,8 +642,14 @@ class SessionIndex:
             from claude_code_tools.export_session import extract_session_metadata
             metadata = extract_session_metadata(jsonl_path, agent)
 
-            # Extract content for full-text search
-            content, msg_count = self._extract_session_content(jsonl_path, agent)
+            # Extract content for full-text search (also extracts custom_title)
+            content, msg_count, custom_title = self._extract_session_content(
+                jsonl_path, agent
+            )
+
+            # Add custom_title to metadata (extracted during content scan)
+            if custom_title:
+                metadata["customTitle"] = custom_title
 
             if msg_count == 0:
                 return {"_skip_reason": "empty"}
@@ -565,6 +657,7 @@ class SessionIndex:
             # Map metadata fields to expected format
             first_msg = metadata.get("first_msg") or {"role": "", "content": ""}
             last_msg = metadata.get("last_msg") or {"role": "", "content": ""}
+            first_user_msg = metadata.get("first_user_msg") or {"role": "", "content": ""}
 
             # Always use filename-derived session_id (the canonical identifier)
             # Internal sessionId field can be stale in forked sessions
@@ -585,10 +678,12 @@ class SessionIndex:
                     "is_sidechain": metadata.get("is_sidechain", False),
                     "derivation_type": metadata.get("derivation_type", "") or "",
                     "session_type": metadata.get("session_type"),
+                    "customTitle": metadata.get("customTitle", "") or "",
                 },
                 "content": content,
                 "first_msg": first_msg,
                 "last_msg": last_msg,
+                "first_user_msg": first_user_msg,
                 "lines": msg_count,
                 "file_path": str(jsonl_path),
             }
@@ -671,6 +766,7 @@ class SessionIndex:
             metadata = parsed["metadata"]
             first_msg = parsed["first_msg"]
             last_msg = parsed["last_msg"]
+            first_user_msg = parsed.get("first_user_msg", {}) or {}
 
             # Skip helper sessions (SDK/headless sessions used for analysis)
             if metadata.get("session_type") == "helper":
@@ -714,6 +810,7 @@ class SessionIndex:
                 doc.add_text("first_msg_content", first_msg.get("content", ""))
                 doc.add_text("last_msg_role", last_msg.get("role", ""))
                 doc.add_text("last_msg_content", last_msg.get("content", ""))
+                doc.add_text("first_user_msg_content", first_user_msg.get("content", ""))
 
                 # Session type fields
                 doc.add_text(
@@ -724,6 +821,9 @@ class SessionIndex:
                     "true" if metadata.get("is_sidechain") else "false"
                 )
 
+                # Custom title (from /rename command)
+                doc.add_text("custom_title", metadata.get("customTitle", "") or "")
+
                 # Source home (for filtering by source directory)
                 # Detect from path whether this is a Claude or Codex session
                 agent = metadata.get("agent", "")
@@ -933,6 +1033,7 @@ class SessionIndex:
             first_msg_content = doc.get_first("first_msg_content") or ""
             last_msg_role = doc.get_first("last_msg_role") or ""
             last_msg_content = doc.get_first("last_msg_content") or ""
+            first_user_msg_content = doc.get_first("first_user_msg_content") or ""
 
             results.append({
                 "session_id": session_id,
@@ -950,6 +1051,7 @@ class SessionIndex:
                 "first_msg_content": first_msg_content,
                 "last_msg_role": last_msg_role,
                 "last_msg_content": last_msg_content,
+                "first_user_msg_content": first_user_msg_content,
             })
 
             if len(results) >= limit:
@@ -1013,6 +1115,7 @@ class SessionIndex:
                 "first_msg_content": doc.get_first("first_msg_content") or "",
                 "last_msg_role": doc.get_first("last_msg_role") or "",
                 "last_msg_content": doc.get_first("last_msg_content") or "",
+                "first_user_msg_content": doc.get_first("first_user_msg_content") or "",
                 "claude_home": doc.get_first("claude_home") or "",
             })
 
@@ -1112,6 +1215,7 @@ class SessionIndex:
                 "first_msg_content": doc.get_first("first_msg_content") or "",
                 "last_msg_role": doc.get_first("last_msg_role") or "",
                 "last_msg_content": doc.get_first("last_msg_content") or "",
+                "first_user_msg_content": doc.get_first("first_user_msg_content") or "",
                 "derivation_type": doc.get_first("derivation_type") or "",
                 "is_sidechain": doc.get_first("is_sidechain") or "false",
             }

claude_code_tools/session_menu_cli.py

@@ -424,7 +424,7 @@ Examples:
         }
 
         def handler(session_dict_in, action, kwargs=None):
-            execute_action(
+            return execute_action(
                 action,
                 agent,
                 session_file,

claude_code_tools/session_utils.py

@@ -604,7 +604,7 @@ def is_valid_session(filepath: Path) -> bool:
 
     # Whitelist of resumable message types
     # Claude Code types (require sessionId)
-    claude_valid_types = {"user", "assistant", "tool_result", "tool_use"}
+    claude_valid_types = {"user", "assistant", "tool_result", "tool_use", "system"}
     # Codex types (conversation content types)
     codex_valid_types = {"event_msg", "response_item", "turn_context"}
 
@@ -1167,7 +1167,7 @@ This session continues from a previous conversation. The prior session log is:
 
   {session_file}
 
-The file is in JSONL format. You can use sub-agents to explore it if needed.
+The file is in JSONL format. Since it can be large, use appropriate strategies (such as sub-agents if available) to carefully explore it if you need context.
 
 Do not do anything yet. Simply greet the user and await instructions on how they want to continue the work based on the above session."""
     else:
@@ -1182,7 +1182,7 @@ This session continues from a chain of prior conversations. Here are the JSONL s
 - "trimmed" = Long messages were truncated to free up context. Full content in parent session.
 - "rolled over" = Work handed off to fresh session.
 
-You can use sub-agents to explore these files if you need context.
+Since these files can be large, use appropriate strategies (such as sub-agents if available) to carefully explore them if you need context.
 
 Do not do anything yet. Simply greet the user and await instructions on how they want to continue the work based on the above sessions."""
 

claude_code_tools/smart_trim.py

@@ -12,7 +12,7 @@ from typing import List, Optional
 
 from claude_code_tools.smart_trim_core import identify_trimmable_lines_cli, SMART_TRIM_THRESHOLD
 from claude_code_tools.trim_session import detect_agent, inject_lineage_into_first_user_message
-from claude_code_tools.session_utils import get_claude_home, resolve_session_path
+from claude_code_tools.session_utils import get_claude_home, get_session_uuid, resolve_session_path
 
 
 def trim_lines(
@@ -334,18 +334,28 @@ def main():
     line_indices = [item[0] for item in trimmable]
 
     # Determine output file
-    output_dir = args.output_dir or session_file.parent
-    output_dir.mkdir(parents=True, exist_ok=True)
-
     # Use agent type already detected earlier
     if agent == "claude":
-        # Generate new UUID for trimmed session
+        # Claude: output in same directory or specified output_dir
+        output_dir = args.output_dir or session_file.parent
+        output_dir.mkdir(parents=True, exist_ok=True)
         new_uuid = str(uuid.uuid4())
         output_file = output_dir / f"{new_uuid}.jsonl"
     else:
-        # Codex style
-        timestamp = datetime.datetime.now().strftime("%Y-%m-%dT%H-%M-%S")
+        # Codex: new session goes in today's date folder (YYYY/MM/DD)
+        now = datetime.datetime.now()
+        timestamp = now.strftime("%Y-%m-%dT%H-%M-%S")
+        date_path = now.strftime("%Y/%m/%d")
         new_uuid = str(uuid.uuid4())
+
+        if args.output_dir:
+            output_dir = args.output_dir / date_path
+        else:
+            # Find sessions root by going up from input file (sessions/YYYY/MM/DD/file.jsonl)
+            sessions_root = session_file.parent.parent.parent.parent
+            output_dir = sessions_root / date_path
+
+        output_dir.mkdir(parents=True, exist_ok=True)
         output_file = output_dir / f"rollout-{timestamp}-{new_uuid}.jsonl"
 
     # Perform trimming (pass descriptions for truncation summaries)
@@ -407,7 +417,7 @@ def main():
     print(f"   Tokens saved (est): ~{stats['tokens_saved']:,}")
     print()
     print(f"📄 Output: {output_file}")
-    print(f"   Session ID: {output_file.stem}")
+    print(f"   Session ID: {get_session_uuid(output_file.name)}")
 
 
 if __name__ == "__main__":

claude_code_tools/smart_trim_core.py

@@ -8,6 +8,7 @@ from typing import List, Optional, Any, Dict
 from claude_code_tools.session_utils import (
     get_codex_home,
     get_claude_home,
+    get_session_uuid,
     encode_claude_project_path,
     mark_session_as_helper,
 )
@@ -181,8 +182,8 @@ def analyze_session_with_cli(
 
     session_content = "\n".join(content_parts)
 
-    # Extract session_id from filename
-    session_id = session_file.stem
+    # Extract session_id (UUID) from filename - works for both Claude and Codex formats
+    session_id = get_session_uuid(session_file.name)
 
     # Determine if this is a Codex session (for output directory placement)
     # Resolve paths to handle ~ and relative paths correctly
@@ -224,6 +225,7 @@ def analyze_session_with_cli(
             result = subprocess.run(
                 [
                     "claude", "-p",
+                    "--no-session-persistence",
                     "--output-format", "json",
                     "--permission-mode", "bypassPermissions",
                     prompt,

claude_code_tools/tmux_cli_controller.py

@@ -145,13 +145,19 @@ class TmuxCLIController:
     
     def format_pane_identifier(self, pane_id: str) -> str:
         """Convert pane ID to session:window.pane format."""
+        # Validate pane_id is not empty
+        if not pane_id:
+            return pane_id
+
         try:
             # Get session, window index, and pane index for this pane
             session_output, session_code = self._run_tmux_command(['display-message', '-t', pane_id, '-p', '#{session_name}'])
             window_output, window_code = self._run_tmux_command(['display-message', '-t', pane_id, '-p', '#{window_index}'])
             pane_output, pane_code = self._run_tmux_command(['display-message', '-t', pane_id, '-p', '#{pane_index}'])
-            
-            if session_code == 0 and window_code == 0 and pane_code == 0:
+
+            # Check both return codes AND that outputs are non-empty
+            if (session_code == 0 and window_code == 0 and pane_code == 0 and
+                session_output and window_output and pane_output):
                 return f"{session_output}:{window_output}.{pane_output}"
             else:
                 # Fallback to pane ID
@@ -275,31 +281,36 @@ class TmuxCLIController:
         """
         # Get the current window ID to ensure pane is created in this window
         current_window_id = self.get_current_window_id()
-        
-        cmd = ['split-window']
-        
+
+        # Build base command
+        base_cmd = ['split-window']
+
         # Target the specific window where tmux-cli was called from
         if current_window_id:
-            cmd.extend(['-t', current_window_id])
-        
+            base_cmd.extend(['-t', current_window_id])
+
         if vertical:
-            cmd.append('-h')
+            base_cmd.append('-h')
         else:
-            cmd.append('-v')
-        
-        if size:
-            cmd.extend(['-p', str(size)])
-        
-        cmd.extend(['-P', '-F', '#{pane_id}'])
-        
-        if start_command:
-            cmd.append(start_command)
-        
-        output, code = self._run_tmux_command(cmd)
-        
-        if code == 0:
-            self.target_pane = output
-            return output
+            base_cmd.append('-v')
+
+        # Try -l first (tmux 3.4+), fall back to -p (older versions)
+        # tmux 3.4 removed -p, but 3.5+ has both; older versions only have -p
+        for size_flag in (['-l', f'{size}%'], ['-p', str(size)]) if size else [[]]:
+            cmd = base_cmd.copy()
+            if size_flag:
+                cmd.extend(size_flag)
+            cmd.extend(['-P', '-F', '#{pane_id}'])
+            if start_command:
+                cmd.append(start_command)
+
+            output, code = self._run_tmux_command(cmd)
+
+            # Validate: code must be 0 and output must be a valid pane ID (starts with %)
+            if code == 0 and output and output.startswith('%'):
+                self.target_pane = output
+                return output
+
         return None
     
     def select_pane(self, pane_id: Optional[str] = None, pane_index: Optional[int] = None):
@@ -686,7 +697,6 @@ class CLI:
         else:
             # Remote mode - pass pane_id directly
             content = self.controller.capture_pane(pane_id=pane, lines=lines)
-        print(content)
         return content
     
     def interrupt(self, pane: Optional[str] = None):
@@ -925,4 +935,4 @@ def main():
 
 
 if __name__ == '__main__':
-    main()
+    main()

claude_code_tools/trim_session.py

@@ -365,6 +365,9 @@ def create_placeholder(tool_name: str, original_length: int) -> str:
     )
 
 
+MIN_TOKEN_SAVINGS = 300  # Minimum tokens saved to consider trim worthwhile
+
+
 def trim_and_create_session(
     agent: Optional[str],
     input_file: Path,
@@ -372,6 +375,7 @@ def trim_and_create_session(
     threshold: int,
     output_dir: Optional[Path] = None,
     trim_assistant_messages: Optional[int] = None,
+    min_token_savings: int = MIN_TOKEN_SAVINGS,
 ) -> dict:
     """
     Trim tool results and assistant messages, creating a new session file.
@@ -386,16 +390,19 @@ def trim_and_create_session(
             - Positive N: trim first N assistant messages exceeding threshold
             - Negative N: trim all except last abs(N) assistant messages exceeding threshold
             - None: don't trim assistant messages
+        min_token_savings: Minimum tokens saved to consider trim worthwhile.
+            If savings are below this, deletes output file and sets nothing_to_trim=True.
 
     Returns:
         Dict with:
-            - session_id: New session UUID
-            - output_file: Path to new session file
+            - session_id: New session UUID (None if nothing_to_trim)
+            - output_file: Path to new session file (None if nothing_to_trim)
             - num_tools_trimmed: Number of tool results trimmed
             - num_assistant_trimmed: Number of assistant messages trimmed
             - chars_saved: Characters saved
             - tokens_saved: Estimated tokens saved
             - detected_agent: Detected agent type
+            - nothing_to_trim: True if savings below min_token_savings threshold
     """
     import json
     from datetime import datetime, timezone
@@ -471,6 +478,9 @@ def trim_and_create_session(
         try:
             # Parse first line and add metadata fields
             first_line_data = json.loads(lines[0])
+            # Remove continue_metadata if present - a session is either trimmed OR
+            # continued, not both. The trim_metadata.parent_file preserves ancestry.
+            first_line_data.pop("continue_metadata", None)
             first_line_data.update(metadata_fields)
             lines[0] = json.dumps(first_line_data) + "\n"
 
@@ -481,6 +491,21 @@ def trim_and_create_session(
             # If first line is not valid JSON, leave file as-is
             pass
 
+    # Check if savings are worth it
+    if tokens_saved < min_token_savings:
+        # Not worth trimming - delete output file and return nothing_to_trim flag
+        output_path.unlink(missing_ok=True)
+        return {
+            "session_id": None,
+            "output_file": None,
+            "num_tools_trimmed": num_tools_trimmed,
+            "num_assistant_trimmed": num_assistant_trimmed,
+            "chars_saved": chars_saved,
+            "tokens_saved": tokens_saved,
+            "detected_agent": agent,
+            "nothing_to_trim": True,
+        }
+
     # Inject parent session lineage into first user message
     inject_lineage_into_first_user_message(output_path, input_file, agent)
 
@@ -492,6 +517,7 @@ def trim_and_create_session(
         "chars_saved": chars_saved,
         "tokens_saved": tokens_saved,
         "detected_agent": agent,
+        "nothing_to_trim": False,
     }