claude-code-tools 1.21.0__tar.gz → 1.22.0__tar.gz

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.21.0
+Version: 1.22.0
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/claude_code_tools/__init__.py

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

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/claude_code_tools/aichat.py

@@ -2710,6 +2710,8 @@ def index_stats(index, cwd, claude_home, codex_home):
               help='Limit number of results displayed')
 @click.option('--no-original', is_flag=True, help='Exclude original sessions')
 @click.option('--sub-agent', is_flag=True, help='Include sub-agent sessions (additive)')
+@click.option('--exec-runs', 'exec_runs', is_flag=True,
+              help='Include headless `codex exec` runs (additive)')
 @click.option('--no-trimmed', is_flag=True, help='Exclude trimmed sessions')
 @click.option('--no-rollover', is_flag=True, help='Exclude rollover sessions')
 @click.option('--live', is_flag=True, help='Show only currently running sessions')
@@ -2725,14 +2727,14 @@ def index_stats(index, cwd, claude_home, codex_home):
               help='Output as JSONL for AI agents. Fields per line: session_id, '
                    'agent, project, branch, cwd, lines, created, modified, '
                    'first_msg, last_msg, file_path, derivation_type, '
-                   'is_sidechain, snippet')
+                   'is_sidechain, is_exec_run, snippet')
 @click.option('--by-time', 'by_time', is_flag=True,
               help='Sort results by last-modified time (default: sort by relevance)')
 @click.argument('query', required=False)
 def search(
     claude_home_arg, codex_home_arg, global_search, filter_dir, filter_branch,
-    num_results, no_original, sub_agent, no_trimmed, no_rollover, live, min_lines,
-    after, before, agent, json_output, by_time, query
+    num_results, no_original, sub_agent, exec_runs, no_trimmed, no_rollover, live,
+    min_lines, after, before, agent, json_output, by_time, query
 ):
     """Launch interactive TUI for full-text session search.
 
@@ -2828,6 +2830,8 @@ def search(
         rust_args.append("--no-original")
     if sub_agent:
         rust_args.append("--sub-agent")
+    if exec_runs:
+        rust_args.append("--exec-runs")
     if live:
         rust_args.append("--live")
     if no_trimmed:
@@ -3008,6 +3012,8 @@ def search(
                 rust_args.append("--no-original")
             if filter_state.get("include_sub"):
                 rust_args.append("--sub-agent")
+            if filter_state.get("include_exec"):
+                rust_args.append("--exec-runs")
             if filter_state.get("include_live_only"):
                 rust_args.append("--live")
             if not filter_state.get("include_trimmed", True):

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/claude_code_tools/export_session.py

@@ -408,6 +408,45 @@ def extract_first_last_messages(
     return first_msg, last_msg, first_user_msg
 
 
+def _is_codex_subagent_payload(payload: dict[str, Any]) -> bool:
+    """Return True when a Codex ``session_meta`` payload describes a sub-agent.
+
+    Codex names every thread ``rollout-*.jsonl``, so sub-agent threads can only
+    be told apart by their spawn metadata. A spawned thread records
+    ``thread_source: "subagent"``, a ``source`` object keyed by ``subagent``,
+    and the id of the thread that spawned it.
+
+    Args:
+        payload: The ``payload`` object of a ``session_meta`` record.
+
+    Returns:
+        True when the payload carries any sub-agent spawn marker.
+    """
+    if payload.get("thread_source") == "subagent":
+        return True
+    source = payload.get("source")
+    if isinstance(source, dict) and "subagent" in source:
+        return True
+    return _nonempty_str(payload.get("parent_thread_id"))
+
+
+def _is_codex_exec_payload(payload: dict[str, Any]) -> bool:
+    """Return True when a Codex ``session_meta`` payload describes a headless run.
+
+    Codex records how a thread was launched: ``"exec"`` for a headless
+    ``codex exec`` run (typically spawned by an orchestrating agent or script),
+    ``"cli"`` for the interactive TUI. Sub-agent spawns carry an object here
+    instead, and are reported by :func:`_is_codex_subagent_payload`.
+
+    Args:
+        payload: The ``payload`` object of a ``session_meta`` record.
+
+    Returns:
+        True when the thread was launched headlessly.
+    """
+    return payload.get("source") == "exec"
+
+
 def extract_session_metadata(session_file: Path, agent: str) -> dict[str, Any]:
     """
     Extract metadata from a session JSONL file.
@@ -425,9 +464,12 @@ def extract_session_metadata(session_file: Path, agent: str) -> dict[str, Any]:
     Returns:
         Dict with extracted metadata
     """
-    # Detect sidechain from filename pattern (agent-* prefix)
+    # Detect sidechain from filename pattern (agent-* prefix).
     # This is more reliable than checking isSidechain field in JSON,
-    # which can be set on individual messages within main sessions
+    # which can be set on individual messages within main sessions.
+    # Claude sub-agent transcripts are written as agent-*.jsonl; Codex writes
+    # every thread as rollout-*.jsonl, so Codex sub-agents are detected from
+    # the session_meta record below instead.
     is_sidechain = session_file.name.startswith("agent-")
 
     metadata: dict[str, Any] = {
@@ -438,6 +480,7 @@ def extract_session_metadata(session_file: Path, agent: str) -> dict[str, Any]:
         "branch": None,
         "derivation_type": None,
         "is_sidechain": is_sidechain,
+        "is_exec_run": False,  # Codex: launched headlessly via `codex exec`
         "session_type": None,  # "helper" for SDK/headless sessions
         "parent_session_id": None,
         "parent_session_file": None,
@@ -451,6 +494,13 @@ def extract_session_metadata(session_file: Path, agent: str) -> dict[str, Any]:
     # Track session start timestamp from JSON metadata
     session_start_timestamp: str | None = None
 
+    # A forked Codex rollout replays its ancestors' session_meta records into
+    # the same file (1951 of 6880 real rollouts carry more than one, up to 29).
+    # Only the first one describes THIS session, so the launch-kind flags are
+    # taken from it alone -- otherwise an interactive fork of a headless
+    # ancestor inherits is_exec_run and vanishes from default search results.
+    codex_meta_seen = False
+
     try:
         with open(
             session_file, "r", encoding="utf-8", errors="replace"
@@ -554,6 +604,12 @@ def extract_session_metadata(session_file: Path, agent: str) -> dict[str, Any]:
                         metadata["cwd"] = payload["cwd"]
                     if _nonempty_str(payload.get("id")):
                         metadata["session_id"] = payload["id"]
+                    if not codex_meta_seen:
+                        codex_meta_seen = True
+                        if _is_codex_subagent_payload(payload):
+                            metadata["is_sidechain"] = True
+                        if _is_codex_exec_payload(payload):
+                            metadata["is_exec_run"] = True
                     if session_start_timestamp is None and _nonempty_str(
                         data.get("timestamp")
                     ):
@@ -701,6 +757,8 @@ def generate_yaml_frontmatter(metadata: dict[str, Any]) -> str:
         yaml_data["derivation_type"] = metadata["derivation_type"]
     if metadata.get("is_sidechain"):
         yaml_data["is_sidechain"] = metadata["is_sidechain"]
+    if metadata.get("is_exec_run"):
+        yaml_data["is_exec_run"] = metadata["is_exec_run"]
     if metadata.get("parent_session_id"):
         yaml_data["parent_session_id"] = metadata["parent_session_id"]
     if metadata.get("parent_session_file"):

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/claude_code_tools/node_menu_ui.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 import json
 import os
+import shlex
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -17,11 +19,90 @@ from typing import Any, Callable, Dict, Iterable, List
 
 SessionDict = Dict[str, Any]
 
+#: Runtime npm packages ``menu.js`` imports directly. A checkout that is
+#: missing any of them cannot render a menu, so we check before spawning Node
+#: rather than letting Node print a raw ``ERR_MODULE_NOT_FOUND`` stack trace.
+NODE_UI_REQUIRED_PACKAGES = (
+    "chalk",
+    "figures",
+    "ink",
+    "ink-select-input",
+    "meow",
+    "react",
+)
+
+
+def _node_ui_dir() -> Path:
+    """Return the directory holding the bundled Node UI."""
+    here = Path(__file__).resolve()
+    return here.parent.parent / "node_ui"
+
 
 def _node_script_path() -> Path:
     """Return path to the bundled Node UI script."""
-    here = Path(__file__).resolve()
-    return here.parent.parent / "node_ui" / "menu.js"
+    return _node_ui_dir() / "menu.js"
+
+
+def _missing_node_ui_packages(node_ui_dir: Path | None = None) -> List[str]:
+    """Return the required Node UI packages that are not installed.
+
+    Args:
+        node_ui_dir: Directory to inspect. Defaults to the bundled ``node_ui``.
+
+    Returns:
+        Names of missing packages, empty when every requirement is present.
+    """
+    root = node_ui_dir if node_ui_dir is not None else _node_ui_dir()
+    node_modules = root / "node_modules"
+    if not node_modules.is_dir():
+        return list(NODE_UI_REQUIRED_PACKAGES)
+    return [
+        name
+        for name in NODE_UI_REQUIRED_PACKAGES
+        if not (node_modules / name).is_dir()
+    ]
+
+
+def _quote_path(path: Path) -> str:
+    """Quote a path for the shell the user is most likely pasting into.
+
+    ``shlex.quote`` emits POSIX single quotes, which ``cmd.exe`` treats as
+    literal characters, so a Windows path containing spaces would be split.
+
+    Args:
+        path: Path to embed in a suggested command line.
+
+    Returns:
+        The path, quoted only when it needs to be.
+    """
+    text = str(path)
+    if os.name == "nt":
+        # cmd.exe splits on & | ^ < > as well as spaces, so always quote.
+        return f'"{text}"'
+    return shlex.quote(text)
+
+
+def _no_node_message() -> str:
+    """Build the message shown when the Node runtime is unavailable."""
+    return (
+        "aichat could not start its interactive menu: 'node' was not found "
+        "on PATH.\nInstall Node.js (>=18) and try again."
+    )
+
+
+def _node_ui_setup_message(missing: List[str], node_ui_dir: Path) -> str:
+    """Build an actionable message for a Node UI with missing dependencies."""
+    return (
+        "aichat could not start its interactive menu: the Node UI "
+        f"dependencies are missing ({', '.join(missing)}).\n"
+        f"Expected them in: {node_ui_dir / 'node_modules'}\n"
+        "\n"
+        "This happens when aichat runs from a source checkout (an editable\n"
+        "install) whose Node dependencies were never installed. Install them\n"
+        "with either of:\n"
+        f"  npm ci --prefix {_quote_path(node_ui_dir)} --omit=dev\n"
+        "  make install   # from that checkout (needs GNU make)\n"
+    )
 
 
 def _write_payload(
@@ -63,15 +144,33 @@ def _write_payload(
 def _run_node(data_path: Path, out_path: Path, stderr_mode: bool = False) -> int:
     """Invoke the Node UI process.
 
-    Returns the process return code.
+    Returns the process return code. A missing Node runtime or missing Node UI
+    dependencies are reported as an actionable message and return code 1.
     """
+    # Check the runtime before its packages: on a machine without Node, telling
+    # the user to run npm is useless advice.
+    if shutil.which("node") is None:
+        print(_no_node_message(), file=sys.stderr)
+        return 1
+
+    node_ui_dir = _node_ui_dir()
+    missing = _missing_node_ui_packages(node_ui_dir)
+    if missing:
+        print(_node_ui_setup_message(missing, node_ui_dir), file=sys.stderr)
+        return 1
+
     script = _node_script_path()
     cmd = ["node", str(script), "--data", str(data_path), "--out", str(out_path)]
     env = os.environ.copy()
     if stderr_mode:
         env["NODE_UI_STDERR"] = "1"
 
-    proc = subprocess.run(cmd, env=env)
+    try:
+        proc = subprocess.run(cmd, env=env)
+    except FileNotFoundError:
+        # Node disappeared between the check above and the spawn.
+        print(_no_node_message(), file=sys.stderr)
+        return 1
     return proc.returncode
 
 

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/claude_code_tools/search_index.py

@@ -2,6 +2,7 @@
 
 import json
 import math
+import os
 import shutil
 import sys
 from dataclasses import dataclass
@@ -14,12 +15,26 @@ 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."""
+#: Revision of the indexing logic itself. Bump this whenever a change alters
+#: what gets stored for a session (new field, corrected detection), so existing
+#: indexes rebuild even when the package version has not changed -- an editable
+#: install keeps the same version across every code change.
+#: rev 2: Codex sub-agent (is_sidechain) detection.
+#: rev 3: headless `codex exec` run (is_exec_run) detection.
+#: rev 4: launch flags read from the session's own session_meta record only.
+INDEX_LOGIC_REVISION = 4
+
+
+def _get_index_version() -> str:
+    """Return the index identity: package version plus indexing-logic revision.
+
+    A mismatch against the stored value triggers a full rebuild.
+    """
     try:
-        return get_pkg_version("claude-code-tools")
+        version = get_pkg_version("claude-code-tools")
     except Exception:
-        return "unknown"
+        version = "unknown"
+    return f"{version}+idx{INDEX_LOGIC_REVISION}"
 
 # Lazy imports to allow module to load even if deps not installed
 try:
@@ -129,9 +144,18 @@ class IndexState:
             or stat.st_size != stored.get("size")
         )
 
-    def mark_indexed(self, file_path: Path):
-        """Mark file as indexed with current metadata."""
-        stat = file_path.stat()
+    def mark_indexed(
+        self, file_path: Path, stat_result: Optional[os.stat_result] = None
+    ):
+        """Mark file as indexed.
+
+        Args:
+            file_path: Session file that was processed.
+            stat_result: File state to record. Pass the state captured BEFORE
+                reading the file, so content appended while it was being read
+                is not recorded as already indexed. Defaults to current state.
+        """
+        stat = stat_result if stat_result is not None else file_path.stat()
         self.indexed_files[str(file_path)] = {
             "mtime": stat.st_mtime,
             "size": stat.st_size,
@@ -183,6 +207,9 @@ class SessionIndex:
         # Session type fields (for filtering in TUI)
         self.schema_builder.add_text_field("derivation_type", stored=True)
         self.schema_builder.add_text_field("is_sidechain", stored=True)  # "true"/"false"
+        # Codex sessions launched headlessly via `codex exec` (agent-spawned
+        # workers). Excluded from results by default, like sub-agents.
+        self.schema_builder.add_text_field("is_exec_run", stored=True)  # "true"/"false"
 
         # Claude home field (for filtering by source Claude home directory)
         # Use "raw" tokenizer so paths are indexed as single tokens for exact matching
@@ -201,7 +228,7 @@ class SessionIndex:
 
         # Check index version - rebuild if package version changed
         version_file = self.index_path / "VERSION"
-        current_version = _get_package_version()
+        current_version = _get_index_version()
         needs_rebuild = False
 
         if version_file.exists():
@@ -209,17 +236,23 @@ class SessionIndex:
                 stored_version = version_file.read_text().strip()
                 if stored_version != current_version:
                     needs_rebuild = True
+                    # stderr, not stdout: `aichat search --json` emits JSONL on
+                    # stdout, and an upgrade notice there is invalid output.
                     print(
-                        f"Package version changed ({stored_version} -> {current_version}), "
-                        "rebuilding index..."
+                        f"Index version changed ({stored_version} -> {current_version}), "
+                        "rebuilding index...",
+                        file=sys.stderr,
                     )
             except IOError:
                 needs_rebuild = True
-                print("Index version file corrupted, rebuilding...")
+                print("Index version file corrupted, rebuilding...", file=sys.stderr)
         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...")
+            print(
+                "Upgrading index to versioned format, rebuilding...",
+                file=sys.stderr,
+            )
 
         if needs_rebuild:
             # Clear index directory contents (but keep the directory itself)
@@ -336,6 +369,10 @@ class SessionIndex:
                 "is_sidechain",
                 "true" if metadata.get("is_sidechain") else "false"
             )
+            doc.add_text(
+                "is_exec_run",
+                "true" if metadata.get("is_exec_run") else "false"
+            )
 
             # Custom title (from /rename command)
             doc.add_text("custom_title", metadata.get("customTitle", "") or "")
@@ -424,6 +461,10 @@ class SessionIndex:
                 "is_sidechain",
                 "true" if metadata.get("is_sidechain") else "false"
             )
+            doc.add_text(
+                "is_exec_run",
+                "true" if metadata.get("is_exec_run") else "false"
+            )
 
             # Custom title (from /rename command)
             doc.add_text("custom_title", metadata.get("customTitle", "") or "")
@@ -685,6 +726,7 @@ class SessionIndex:
                     "created": metadata.get("created", "") or "",
                     "modified": metadata.get("modified", "") or "",
                     "is_sidechain": metadata.get("is_sidechain", False),
+                    "is_exec_run": metadata.get("is_exec_run", False),
                     "derivation_type": metadata.get("derivation_type", "") or "",
                     "session_type": metadata.get("session_type"),
                     "customTitle": metadata.get("customTitle", "") or "",
@@ -753,11 +795,21 @@ class SessionIndex:
                 stats["skipped"] += 1
                 continue
 
+            # Snapshot the file state BEFORE reading it. A live session can
+            # append while we read; recording the post-read state would mark
+            # that new content as already indexed and hide the session until
+            # its next write.
+            try:
+                file_stat = jsonl_path.stat()
+            except OSError:
+                stats["skipped"] += 1
+                continue
+
             # Skip invalid sessions (metadata-only files like file-history-snapshot)
             if not is_valid_session(jsonl_path):
                 stats["skipped"] += 1
                 # Mark as indexed so we don't re-check next time
-                self.state.mark_indexed(jsonl_path)
+                self.state.mark_indexed(jsonl_path, file_stat)
                 continue
 
             # Parse JSONL file
@@ -768,6 +820,10 @@ class SessionIndex:
                     reason = parsed.get("_skip_reason", "unknown")
                     if reason == "empty":
                         stats["empty"] += 1
+                        # Mark as indexed so we don't re-parse it every launch.
+                        # If the session later gains messages its mtime/size
+                        # changes, which re-triggers indexing.
+                        self.state.mark_indexed(jsonl_path, file_stat)
                     elif reason == "parse_error":
                         stats["parse_error"] += 1
                 continue
@@ -781,7 +837,7 @@ class SessionIndex:
             if metadata.get("session_type") == "helper":
                 stats["skipped"] += 1
                 # Mark as indexed so we don't re-check next time
-                self.state.mark_indexed(jsonl_path)
+                self.state.mark_indexed(jsonl_path, file_stat)
                 continue
 
             # Skip sessions run from inside claude_home or codex_home directories
@@ -791,6 +847,10 @@ class SessionIndex:
                 or (codex_home_str and cwd.startswith(codex_home_str))
             ):
                 stats["skipped"] += 1
+                # Deliberately NOT recorded in the index state: this exclusion
+                # depends on the claude_home/codex_home passed on the command
+                # line, so caching it would keep the session out of the index
+                # after a later run with different homes.
                 continue
 
             try:
@@ -829,6 +889,10 @@ class SessionIndex:
                     "is_sidechain",
                     "true" if metadata.get("is_sidechain") else "false"
                 )
+                doc.add_text(
+                    "is_exec_run",
+                    "true" if metadata.get("is_exec_run") else "false"
+                )
 
                 # Custom title (from /rename command)
                 doc.add_text("custom_title", metadata.get("customTitle", "") or "")
@@ -846,7 +910,7 @@ class SessionIndex:
                 doc.add_text("content", parsed["content"])
 
                 writer.add_document(doc)
-                self.state.mark_indexed(jsonl_path)
+                self.state.mark_indexed(jsonl_path, file_stat)
                 stats["indexed"] += 1
             except Exception:
                 stats["failed"] += 1

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/claude_code_tools/tmux_cli_controller.py

@@ -254,6 +254,11 @@ class TmuxCLIController:
         for line in output.split('\n'):
             if line:
                 parts = line.split('|')
+                # tmux emits six fields; anything shorter is not a pane line
+                # (an error string, a truncated read) and is skipped rather
+                # than indexed into.
+                if len(parts) < 5:
+                    continue
                 pane_id = parts[0]
                 panes.append({
                     'id': pane_id,

{claude_code_tools-1.21.0 → claude_code_tools-1.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-code-tools"
-version = "1.21.0"
+version = "1.22.0"
 description = "Collection of tools for working with Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -111,7 +111,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.21.0"
+version = "1.22.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:version",