claude-code-tools 1.24.0__tar.gz → 1.25.0__tar.gz

{claude_code_tools-1.24.0 → claude_code_tools-1.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.24.0
+Version: 1.25.0
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -84,6 +84,11 @@ docs. Click a card below to jump to a feature, or
 </tr>
 <tr>
 <td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/amux/">
+<img src="assets/card-amux.svg" alt="amux" width="200"/>
+</a>
+</td>
+<td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/agent-tunnel/">
 <img src="assets/card-agent-tunnel.svg" alt="agent-tunnel" width="200"/>
 </a>
@@ -152,8 +157,19 @@ docs. Click a card below to jump to a feature, or
 </tr>
 <tr>
 <td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/aichat/port/">
+<img src="assets/card-session-port.svg" alt="session porting" width="200"/>
+</a>
+</td>
+<td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/guides/claude-to-codex/">
-<img src="assets/card-claude-to-codex.svg" alt="Claude to Codex" width="200"/>
+<img src="assets/card-claude-to-codex.svg" alt="Codex dynamic workflows" width="200"/>
+</a>
+</td>
+<td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/github-wake/">
+<img src="assets/card-github-watch.svg"
+     alt="github-watch: wake on github comment" width="200"/>
 </a>
 </td>
 </tr>

{claude_code_tools-1.24.0 → claude_code_tools-1.25.0}/README.md

@@ -58,6 +58,11 @@ docs. Click a card below to jump to a feature, or
 </tr>
 <tr>
 <td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/amux/">
+<img src="assets/card-amux.svg" alt="amux" width="200"/>
+</a>
+</td>
+<td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/agent-tunnel/">
 <img src="assets/card-agent-tunnel.svg" alt="agent-tunnel" width="200"/>
 </a>
@@ -126,8 +131,19 @@ docs. Click a card below to jump to a feature, or
 </tr>
 <tr>
 <td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/aichat/port/">
+<img src="assets/card-session-port.svg" alt="session porting" width="200"/>
+</a>
+</td>
+<td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/guides/claude-to-codex/">
-<img src="assets/card-claude-to-codex.svg" alt="Claude to Codex" width="200"/>
+<img src="assets/card-claude-to-codex.svg" alt="Codex dynamic workflows" width="200"/>
+</a>
+</td>
+<td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/github-wake/">
+<img src="assets/card-github-watch.svg"
+     alt="github-watch: wake on github comment" width="200"/>
 </a>
 </td>
 </tr>

{claude_code_tools-1.24.0 → claude_code_tools-1.25.0}/claude_code_tools/__init__.py

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

claude_code_tools-1.25.0/claude_code_tools/amux/__init__.py

@@ -0,0 +1,5 @@
+"""amux: see and jump between coding agents running in tmux panes."""
+
+from .model import Agent, State, Kind
+
+__all__ = ["Agent", "State", "Kind"]

claude_code_tools-1.25.0/claude_code_tools/amux/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m claude_code_tools.amux`` (used by fzf reload bindings)."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claude_code_tools-1.25.0/claude_code_tools/amux/cache.py

@@ -0,0 +1,80 @@
+"""Cache of the last scan, so the picker opens instantly.
+
+The picker shows cached rows immediately and kicks off a fresh scan in the
+background, replacing the list when it lands. With hundreds of panes, a cold
+scan is noticeable; a warm one is not.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import time
+from pathlib import Path
+
+from .model import Agent
+
+_DEFAULT = Path.home() / ".cache" / "cc-tools" / "amux.json"
+
+
+def cache_path() -> Path:
+    """Location of the cache file (``AMUX_CACHE`` overrides)."""
+    override = os.environ.get("AMUX_CACHE")
+    return Path(override) if override else _DEFAULT
+
+
+def read(max_age: float | None = None) -> tuple[list[Agent], float]:
+    """Load cached agents.
+
+    Args:
+        max_age: If set, return an empty list when the cache is older than
+            this many seconds.
+
+    Returns:
+        ``(agents, age_seconds)``; ``age_seconds`` is ``-1`` when no usable
+        cache exists.
+    """
+    path = cache_path()
+    try:
+        raw = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return [], -1.0
+
+    # Syntactically valid JSON can still be the wrong shape (hand-edited file,
+    # a truncated write from an older version). Never crash over a cache.
+    try:
+        stamp = float(raw.get("time", 0))
+        age = time.time() - stamp
+        # Python's json accepts the NaN literal, and every comparison against
+        # nan is False -- so a NaN age passed both the negative check and the
+        # max_age check, making the cache permanently "fresh".
+        if not math.isfinite(age) or age < 0:
+            return [], -1.0
+        if max_age is not None and age > max_age:
+            return [], age
+        parsed = (
+            Agent.from_dict(d) for d in raw.get("agents", []) if isinstance(d, dict)
+        )
+        agents = [a for a in parsed if a is not None]
+    except (AttributeError, TypeError, ValueError):
+        return [], -1.0
+    return agents, age
+
+
+def write(agents: list[Agent]) -> None:
+    """Persist *agents* atomically, creating the cache directory if needed."""
+    path = cache_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "time": time.time(),
+            "agents": [a.to_dict() for a in agents],
+        }
+        # Per-process temp name: two concurrent `amux scan` runs sharing one
+        # ".tmp" would race, and the loser died on a missing file.
+        tmp = path.with_suffix(f".{os.getpid()}.tmp")
+        tmp.write_text(json.dumps(payload))
+        tmp.replace(path)
+    except OSError:
+        pass  # a missing cache only costs speed, never correctness

claude_code_tools-1.25.0/claude_code_tools/amux/cli.py

@@ -0,0 +1,206 @@
+"""amux -- see and jump between the coding agents running in your tmux panes.
+
+    amux              # interactive picker (fzf): jump to an agent
+    amux list         # table of every live agent
+    amux list --json  # machine-readable
+    amux scan         # refresh the cache (for cron / tmux hooks)
+
+The picker opens on cached rows and refreshes in the background, so it is
+instant even with hundreds of panes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import math
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+from . import cache, render, scan
+from .model import Agent
+
+_FZF_HEADER = (
+    "enter=jump  ctrl-r=refresh  esc=quit    "
+    "input=asking you  busy=working  bg=monitors  idle"
+)
+
+
+def _fresh(write_cache: bool = True) -> list[Agent]:
+    """Scan live panes and refresh the cache."""
+    agents = scan.scan()
+    if write_cache:
+        cache.write(agents)
+    return agents
+
+
+def _agents_for_display(max_age: float) -> tuple[list[Agent], bool]:
+    """Return agents to show now, plus whether they came from cache."""
+    cached, age = cache.read(max_age=max_age)
+    if cached:
+        return cached, True
+    return _fresh(), False
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """Print every live agent as a table or JSON."""
+    agents = cache.read(max_age=args.max_age)[0] if args.cached else _fresh()
+    if not agents and args.cached:
+        agents = _fresh()
+    if args.json:
+        print(render.as_json(agents))
+    else:
+        colour = sys.stdout.isatty() and not args.no_color
+        print(render.table(agents, colour=colour))
+    return 0
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    """Refresh the cache and report what was found."""
+    agents = _fresh()
+    print(f"cached {len(agents)} agents -> {cache.cache_path()}")
+    return 0
+
+
+def cmd_rows(args: argparse.Namespace) -> int:
+    """Emit picker rows (internal: used by fzf's reload binding)."""
+    agents = _fresh() if args.refresh else _agents_for_display(args.max_age)[0]
+    print(render.picker_lines(agents, colour=True))
+    return 0
+
+
+def cmd_pick(args: argparse.Namespace) -> int:
+    """Interactive picker; jumps to the chosen agent's pane."""
+    if not shutil.which("fzf"):
+        print("amux: fzf not found (brew install fzf)", file=sys.stderr)
+        return 1
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        print("amux: no tty -- use 'amux list' for scripted output", file=sys.stderr)
+        return 1
+
+    agents, from_cache = _agents_for_display(args.max_age)
+    if not agents:
+        print("no agents running")
+        return 0
+
+    # fzf runs bind commands through a shell, so the interpreter path must be
+    # quoted: a venv at "/tmp/my venv/bin/python" would otherwise run "/tmp/my".
+    self_cmd = f"{shlex.quote(sys.executable)} -m claude_code_tools.amux"
+    binds = [
+        f"ctrl-r:reload({self_cmd} rows --refresh)",
+        # Opening on cached rows is what makes this instant; refresh the
+        # moment the list is up so stale states self-correct without a keypress.
+        f"load:reload-sync({self_cmd} rows --refresh)" if from_cache else "",
+    ]
+    cmd = [
+        "fzf",
+        "--ansi",
+        "--no-sort",
+        # Field 1 is the pane target, hidden from view; see picker_lines().
+        "--delimiter",
+        "\t",
+        "--with-nth",
+        "2..",
+        "--header",
+        _FZF_HEADER,
+        "--preview",
+        "tmux capture-pane -ep -S -200 -t {1} | grep '[^[:space:]]' | tail -60",
+        "--preview-window",
+        "right:55%:wrap:follow",
+        "--prompt",
+        "agent> ",
+    ]
+    for bind in binds:
+        if bind:
+            cmd += ["--bind", bind]
+
+    # Capture ONLY stdout. capture_output=True also pipes stderr, which is
+    # where fzf draws its interface -- the UI never reaches the terminal and
+    # the picker looks hung, waiting for keys against an invisible prompt.
+    # (fzf reads keystrokes from /dev/tty, so feeding the list on stdin is
+    # fine.)
+    proc = subprocess.run(
+        cmd,
+        input=render.picker_lines(agents),
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return 0
+
+    pane = render.pane_from_selection(proc.stdout)
+    if not pane:
+        return 0
+    scan.switch_to(pane)
+    return 0
+
+
+def _finite_seconds(value: str) -> float:
+    """Parse a --max-age value, rejecting nan/inf.
+
+    argparse's ``type=float`` happily accepts "nan", and every comparison
+    against NaN is False -- so ``--max-age nan`` disabled cache expiry
+    entirely and served arbitrarily stale data.
+    """
+    seconds = float(value)
+    if not math.isfinite(seconds) or seconds < 0:
+        raise argparse.ArgumentTypeError(
+            f"must be a non-negative finite number of seconds, got {value!r}"
+        )
+    return seconds
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="amux",
+        description="See and jump between coding agents running in tmux panes.",
+    )
+    parser.add_argument(
+        "--max-age",
+        type=_finite_seconds,
+        default=30.0,
+        help="seconds a cached scan stays usable (default: 30)",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    pick = sub.add_parser("pick", help="interactive picker (default)")
+    pick.set_defaults(func=cmd_pick)
+
+    lst = sub.add_parser("list", help="print all live agents")
+    lst.add_argument("--json", action="store_true", help="machine-readable output")
+    lst.add_argument("--cached", action="store_true", help="use the cache if fresh")
+    lst.add_argument("--no-color", action="store_true", help="disable colour")
+    lst.set_defaults(func=cmd_list)
+
+    scan_cmd = sub.add_parser("scan", help="refresh the cache")
+    scan_cmd.set_defaults(func=cmd_scan)
+
+    rows = sub.add_parser("rows", help=argparse.SUPPRESS)
+    rows.add_argument("--refresh", action="store_true")
+    rows.set_defaults(func=cmd_rows)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``amux`` console script."""
+    parser = build_parser()
+    raw = list(sys.argv[1:] if argv is None else argv)
+    # Default to the picker, but insert the subcommand rather than reparsing
+    # only ["pick"] -- reparsing dropped global options, so `amux --max-age 0`
+    # silently used the 30s default.
+    known = {"pick", "list", "scan", "rows"}
+    if not any(tok in known for tok in raw):
+        raw.append("pick")
+    args = parser.parse_args(raw)
+    if not scan.tmux_available():
+        print("amux: no tmux server running", file=sys.stderr)
+        return 1
+    return int(args.func(args) or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claude_code_tools-1.25.0/claude_code_tools/amux/detect.py

@@ -0,0 +1,236 @@
+"""Screen-scraping heuristics: what harness is this, and what is it doing.
+
+Everything here is deliberately pure (string in, verdict out) so it can be
+unit-tested against captured fixtures without a live tmux server.
+
+Why screen-scraping at all: ``pane_current_command`` is useless for
+identifying these harnesses -- Claude Code reports a bare version string like
+``2.1.220`` because it runs a versioned binary, and Codex reports ``node``.
+Process *argv* identifies the harness reliably; the *screen* is the only place
+that reveals what it is currently doing.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .model import Kind, State
+
+# --- harness identification (from the pane's child process argv) -----------
+
+#: Interpreters that launch an agent via a script path rather than being the
+#: agent themselves (Codex ships as JS run under node).
+_INTERPRETERS = {"node", "node.exe", "python", "python3", "bun", "deno"}
+
+#: Script-path fragments that identify a harness when run under an interpreter.
+_CODEX_PATH = re.compile(r"@openai/codex|/codex(\.js|-cli)?\b")
+_CLAUDE_PATH = re.compile(r"/claude(\.js|-code)?\b|/\.local/share/claude/")
+
+
+def _basename(token: str) -> str:
+    """Executable name from an argv[0] token."""
+    return token.rsplit("/", 1)[-1]
+
+
+def classify_argv(argv: str) -> Kind | None:
+    """Identify the harness from a single process command line.
+
+    Only the EXECUTABLE decides -- argv[0], or the script path when argv[0] is
+    an interpreter. Searching the whole command line matched arguments too, so
+    an ordinary ``rg claude .`` in a pane was listed as an idle Claude agent.
+
+    Args:
+        argv: One process's command line.
+
+    Returns:
+        ``"codex"``, ``"claude"``, or ``None`` when this is not an agent.
+    """
+    for line in argv.splitlines():
+        tokens = line.split()
+        if not tokens:
+            continue
+        exe = _basename(tokens[0])
+        if exe in ("codex", "codex-cli"):
+            return "codex"
+        if exe in ("claude", "claude-code"):
+            return "claude"
+        # Versioned Claude binaries are named after the version (2.1.220).
+        if re.fullmatch(r"\d+\.\d+\.\d+", exe):
+            return "claude"
+        if exe in _INTERPRETERS and len(tokens) > 1:
+            script = tokens[1]
+            if _CODEX_PATH.search(script):
+                return "codex"
+            if _CLAUDE_PATH.search(script):
+                return "claude"
+    return None
+
+
+# --- state detection (from the pane's visible screen) ----------------------
+
+#: Claude renders AskUserQuestion and permission prompts as numbered choices.
+_ASKING = re.compile(
+    r"❯\s*1\.|Do you want|Would you like|^\s*1\.\s*Yes|\(y/n\)|"
+    r"Select an option|Choose an option",
+    re.MULTILINE,
+)
+#: The MAIN agent is mid-turn. Two forms seen live:
+#:   "✻ Cooked for 14m 17s · esc to interrupt"
+#:   "· Razzmatazzing… (1m 42s · ↓ 4.8k tokens · thought for 14s)"
+#: The second has no "esc to interrupt" at all, so matching only that phrase
+#: reported an actively working pane as idle. The parenthesised
+#: elapsed-time-plus-token-counter is what distinguishes it from a subagent
+#: row, which carries the same counter WITHOUT parentheses.
+_BUSY = re.compile(
+    r"esc to interrupt|\(\d+[ms][^)]*↓[^)]*tokens",
+    re.IGNORECASE,
+)
+#: Background work. Two forms, both taken from live panes:
+#:   "✻ Baked for 16m 24s · 1 monitor still running"
+#:   "  ◯ cache-incremental-evidence  Grepping ...   1m 16s · ↓ 873.5k tokens"
+#: The second is Claude's subagent tree: ◯ marks a subagent still RUNNING
+#: (✓ marks a finished one, and ⏺ is ordinary assistant output, so neither of
+#: those can be used). Without this a pane with a working subagent but a free
+#: main prompt reported as idle.
+_BG = re.compile(
+    r"\b\d+\s+monitors?\b|^\s*◯\s+\S",
+    re.MULTILINE,
+)
+
+#: Codex chrome to ignore when looking for its last content line.
+_CODEX_CHROME = re.compile(
+    r"^\s*[›❯]|·|gpt-[\d.]|^\s*─|esc to|tab to|^\s*$|^\s*[▌│]"
+)
+
+
+#: A pending prompt is at the BOTTOM of the screen. Searching all retained
+#: text made any earlier sentence containing e.g. "Would you like" pin the
+#: pane to `input` until it scrolled off.
+_PROMPT_TAIL_LINES = 12
+
+
+def detect_state(screen: str, kind: Kind) -> State:
+    """Classify what the agent is doing from its visible screen.
+
+    Args:
+        screen: The pane's captured text (escape sequences stripped).
+        kind: Which harness is running, from :func:`classify_argv`.
+
+    Returns:
+        One of ``input`` (waiting on the user), ``busy`` (mid-turn),
+        ``bg`` (background monitors running), or ``idle``.
+    """
+    tail_lines = screen.splitlines()[-_PROMPT_TAIL_LINES:]
+    tail = "\n".join(tail_lines)
+    # An ANSWERED prompt keeps its choices on screen, with Claude's footer
+    # rendered below them. Only treat a prompt as pending when nothing from
+    # the footer appears after it -- otherwise a just-answered
+    # AskUserQuestion stays flagged as blocking until it scrolls off.
+    if _ASKING.search(tail) and not _footer_below_prompt(tail_lines):
+        return "input"
+    # BUSY must be decided before the Codex question heuristic. A visible
+    # spinner is proof the agent is working, whereas the heuristic can only
+    # guess from an older question still on screen: Codex asks, you answer,
+    # it starts working -- and the question is still up there.
+    if _BUSY.search(screen):
+        return "busy"
+    if kind == "codex" and _codex_awaiting_answer(tail):
+        return "input"
+    if _BG.search(screen):
+        return "bg"
+    return "idle"
+
+
+#: Footer chrome Claude renders BELOW a completed exchange. Anchored to the
+#: start of a line: an option in a PENDING prompt can quote this text
+#: ("2. Explain why the status says bypass permissions on") and must not be
+#: mistaken for the footer itself.
+_FOOTER = re.compile(
+    r"^\s*("
+    r"⏵⏵|ctx [█░]|new task\?|✻|※"       # Claude chrome
+    r"|gpt-[\w.\-]+\s|›"                # Codex status line and input box
+    r")"
+)
+
+
+def _footer_below_prompt(lines: list[str]) -> bool:
+    """Whether harness footer chrome appears after the last prompt line."""
+    last_prompt = -1
+    for index, line in enumerate(lines):
+        if _ASKING.search(line):
+            last_prompt = index
+    if last_prompt < 0:
+        return False
+    return any(_FOOTER.search(line) for line in lines[last_prompt + 1 :])
+
+def _codex_awaiting_answer(screen: str) -> bool:
+    """Heuristic: Codex asked a question and stopped.
+
+    Codex has no structured prompt UI, so the only available signal is that
+    the last real content line -- ignoring the input box and status chrome --
+    ends in a question mark. This has false positives (an answer that merely
+    ends in a question) and misses (a question phrased as a statement).
+
+    Only the screen TAIL is considered, and callers must rule out "busy"
+    first: a question further up the scrollback says nothing about whether
+    the agent is still waiting for you.
+    """
+    for line in reversed(screen.splitlines()):
+        if not line.strip() or _CODEX_CHROME.search(line):
+            continue
+        return line.rstrip().endswith("?")
+    return False
+
+
+# --- context extraction ----------------------------------------------------
+
+_CODEX_STATUS = re.compile(r"(gpt-[\w.\-]+)\s+(\w+)?\s*·\s*([^·]+)·\s*([^·\n]+)")
+_CLAUDE_MODEL = re.compile(
+    r"\b(opus[\w.\-\[\]]*|sonnet[\w.\-\[\]]*|haiku[\w.\-\[\]]*|fable[\w.\-\[\]]*)"
+)
+_SEPARATOR_NAME = re.compile(r"─\s([A-Za-z0-9][A-Za-z0-9._-]{3,})\s─")
+_ARGV_NAME = re.compile(r"--(?:resume|name)[= ]([^\s]+)")
+_SPINNER = re.compile(r"^[✳*⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏\s]+")
+
+
+def extract_model(screen: str, kind: Kind) -> str:
+    """Pull the model identifier out of the harness footer, if present."""
+    if kind == "codex":
+        match = _CODEX_STATUS.search(screen)
+        return match.group(1) if match else ""
+    match = _CLAUDE_MODEL.search(screen)
+    return match.group(1) if match else ""
+
+
+def extract_name(argv: str, pane_title: str, screen: str) -> str:
+    """Best-effort agent session name, most reliable source first.
+
+    Order: the harness's own argv (``--resume``/``--name``), then the tmux
+    pane title (Claude sets it to ``✳ <name>``), then an on-screen separator
+    line. Codex rarely carries a name in any of these and returns ``""``.
+    """
+    match = _ARGV_NAME.search(argv)
+    if match:
+        return match.group(1)
+
+    title = _SPINNER.sub("", pane_title).strip()
+    # Shell-set titles are paths, ~[dir] forms, or hostnames -- not names.
+    if title and not re.search(r"[/\[\]]|\.lan$|\.local$", title):
+        return title
+
+    names = _SEPARATOR_NAME.findall(screen)
+    return names[-1] if names else ""
+
+
+def extract_info(screen: str, kind: Kind) -> str:
+    """One line of context for the list view (model, repo, branch, …)."""
+    if kind == "codex":
+        match = _CODEX_STATUS.search(screen)
+        if match:
+            parts = [p.strip() for p in match.groups() if p]
+            return " · ".join(parts)
+    lines = [ln.strip() for ln in screen.splitlines() if ln.strip()]
+    for line in reversed(lines):
+        if _CLAUDE_MODEL.search(line):
+            return re.sub(r"\s{2,}", " ", line)[:80]
+    return lines[-1][:80] if lines else ""