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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.21.0
+Version: 1.23.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.23.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.23.0"

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

@@ -1768,7 +1768,9 @@ def port_session(
     """
     import sys
 
+    from claude_code_tools.port_render import PortDisplay
     from claude_code_tools.port_service import (
+        PortAmbiguityError,
         PortSessionError,
         port_claude_session,
         port_codex_session,
@@ -1782,56 +1784,54 @@ def port_session(
     claude_home = claude_home or root_obj.get("claude_home")
     codex_home = codex_home or root_obj.get("codex_home")
 
+    display = PortDisplay(session)
+    display.start()
     try:
-        resolved = resolve_port_session(
-            session, claude_home=claude_home, codex_home=codex_home
-        )
+        with display.resolving():
+            resolved = resolve_port_session(
+                session,
+                claude_home=claude_home,
+                codex_home=codex_home,
+            )
+    except PortAmbiguityError as error:
+        try:
+            resolved = display.choose_candidate(error)
+        except (EOFError, KeyboardInterrupt):
+            display.error(str(error))
+            sys.exit(1)
+        if resolved is None:
+            display.cancelled()
+            sys.exit(1)
     except PortSessionError as e:
-        print(f"Error: {e}", file=sys.stderr)
+        display.error(str(e))
         sys.exit(1)
 
+    display.resolved(resolved)
     if resolved.agent == "claude":
-        print("Detected source agent: claude — porting to Codex")
         try:
-            result = port_claude_session(
-                resolved.session_file, codex_home=codex_home
-            )
+            with display.porting(resolved.agent):
+                result = port_claude_session(
+                    resolved.session_file,
+                    codex_home=codex_home,
+                )
         except PortSessionError as e:
-            print(f"Error: {e}", file=sys.stderr)
+            display.error(str(e))
             sys.exit(1)
-
-        print()
-        print(f"New Codex session id:  {result.new_session_id}")
-        print(f"Output file:           {result.output_file}")
-        print(f"Session cwd:           {result.cwd}")
-        print()
-        print("To resume:")
-        print(f"  {result.resume_hint}")
-        print()
-        print(
-            "Tip: codex's /import can also import Claude sessions "
-            "natively (interactive alternative)."
-        )
+        display.complete(result, resolved.agent)
         return
 
-    print("Detected source agent: codex — porting to Claude Code")
     try:
-        result = port_codex_session(
-            resolved.session_file, claude_home=claude_home
-        )
+        with display.porting(resolved.agent):
+            result = port_codex_session(
+                resolved.session_file,
+                claude_home=claude_home,
+            )
     except PortSessionError as e:
         # Expected failure modes (missing/empty session, filesystem
         # or encoding errors) become a clean error, not a traceback.
-        print(f"Error: {e}", file=sys.stderr)
+        display.error(str(e))
         sys.exit(1)
-
-    print()
-    print(f"New Claude session id: {result.new_session_id}")
-    print(f"Output file:           {result.output_file}")
-    print(f"Session cwd:           {result.cwd}")
-    print()
-    print("To resume:")
-    print(f"  {result.resume_hint}")
+    display.complete(result, resolved.agent)
 
 
 @main.command("query")
@@ -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.23.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.23.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