twmux 0.1.0__py3-none-any.whl

twmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

twmux/bin/cli.py

@@ -0,0 +1,263 @@
+"""twmux CLI entry point."""
+
+import json as json_lib
+from typing import Annotated
+
+import typer
+from rich import print as rprint
+
+from twmux import __version__
+
+app = typer.Typer(
+    help="Race-condition-safe tmux wrapper for coding agents",
+    no_args_is_help=True,
+)
+
+# Global options
+json_output: bool = False
+socket_name: str | None = None
+
+
+@app.callback()
+def main(
+    json: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    verbose: Annotated[bool, typer.Option("-v", "--verbose", help="Verbose output")] = False,
+    socket: Annotated[str | None, typer.Option("-L", "--socket", help="Socket name")] = None,
+) -> None:
+    """Configure global options."""
+    global json_output, socket_name
+    json_output = json
+    socket_name = socket
+
+
+def get_pane(target: str):
+    """Resolve target to libtmux Pane object."""
+    from libtmux import Server
+
+    server = Server(socket_name=socket_name)
+
+    # Handle pane ID directly (e.g., %5)
+    if target.startswith("%"):
+        for session in server.sessions:
+            for window in session.windows:
+                for pane in window.panes:
+                    if pane.pane_id == target:
+                        return pane
+        raise typer.BadParameter(f"Pane not found: {target}")
+
+    # Handle session:window.pane format
+    parts = target.split(":")
+    session_name = parts[0] if parts[0] else None
+
+    # Find session
+    if session_name:
+        sessions = [s for s in server.sessions if s.session_name == session_name]
+        if not sessions:
+            raise typer.BadParameter(f"Session not found: {session_name}")
+        session = sessions[0]
+    else:
+        session = server.sessions[0] if server.sessions else None
+        if not session:
+            raise typer.BadParameter("No tmux sessions found")
+
+    # Parse window.pane
+    if len(parts) > 1 and parts[1]:
+        window_pane = parts[1].split(".")
+        window_idx = int(window_pane[0]) if window_pane[0] else 0
+        pane_idx = int(window_pane[1]) if len(window_pane) > 1 else 0
+
+        window = session.windows[window_idx]
+        return window.panes[pane_idx]
+
+    return session.active_window.active_pane
+
+
+def output_result(data: dict) -> None:
+    """Output result in appropriate format."""
+    if json_output:
+        print(json_lib.dumps(data))
+    else:
+        for key, value in data.items():
+            rprint(f"{key}: {value}")
+
+
+@app.command()
+def version() -> None:
+    """Show version."""
+    if json_output:
+        print(json_lib.dumps({"version": __version__}))
+    else:
+        print(f"twmux {__version__}")
+
+
+@app.command()
+def send(
+    text: Annotated[str, typer.Argument(help="Text to send")],
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+    no_enter: Annotated[bool, typer.Option("--no-enter", help="Don't send Enter")] = False,
+    delay: Annotated[float, typer.Option("--delay", help="Enter delay (seconds)")] = 0.05,
+) -> None:
+    """Send text to pane (race-condition safe)."""
+    from twmux.lib.safe_input import send_safe
+
+    pane = get_pane(target)
+    result = send_safe(pane, text, enter=not no_enter, enter_delay=delay)
+
+    output_result({"success": result.success, "attempts": result.attempts})
+
+    if not result.success:
+        raise typer.Exit(1)
+
+
+@app.command(name="exec")
+def exec_cmd(
+    command: Annotated[str, typer.Argument(help="Command to execute")],
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+    timeout: Annotated[float, typer.Option("--timeout", help="Timeout (seconds)")] = 30.0,
+) -> None:
+    """Execute command and capture output + exit code."""
+    from twmux.lib.execution import execute
+
+    pane = get_pane(target)
+    result = execute(pane, command, timeout=timeout)
+
+    output_result(
+        {
+            "output": result.output,
+            "exit_code": result.exit_code,
+            "timed_out": result.timed_out,
+        }
+    )
+
+
+@app.command()
+def capture(
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+    lines: Annotated[int | None, typer.Option("-n", "--lines", help="Number of lines")] = None,
+) -> None:
+    """Capture pane content."""
+    pane = get_pane(target)
+
+    if lines:
+        content = pane.capture_pane(start=-lines)
+    else:
+        content = pane.capture_pane()
+
+    if json_output:
+        print(json_lib.dumps({"content": content}))
+    else:
+        print("\n".join(content))
+
+
+@app.command(name="wait-idle")
+def wait_idle(
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+    timeout: Annotated[float, typer.Option("--timeout", help="Timeout (seconds)")] = 30.0,
+    interval: Annotated[float, typer.Option("--interval", help="Poll interval")] = 0.2,
+) -> None:
+    """Wait for pane output to stabilize."""
+    from twmux.lib.safe_input import wait_for_idle
+
+    pane = get_pane(target)
+    result = wait_for_idle(pane, poll_interval=interval, timeout=timeout)
+
+    output_result({"idle": result.idle, "elapsed": round(result.elapsed, 3)})
+
+    if not result.idle:
+        raise typer.Exit(1)
+
+
+@app.command()
+def interrupt(
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+) -> None:
+    """Send Ctrl+C to pane."""
+    pane = get_pane(target)
+    pane.send_keys("C-c", enter=False)
+
+    output_result({"interrupted": True})
+
+
+@app.command()
+def launch(
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+    command: Annotated[str | None, typer.Option("-c", "--command", help="Command to run")] = None,
+    vertical: Annotated[bool, typer.Option("-v", "--vertical", help="Split vertically")] = False,
+) -> None:
+    """Create new pane (split current window)."""
+    from libtmux.constants import PaneDirection
+
+    pane = get_pane(target)
+
+    direction = PaneDirection.Right if vertical else PaneDirection.Below
+    new_pane = pane.split(direction=direction)
+
+    if command:
+        new_pane.send_keys(command, enter=True)
+
+    output_result({"pane_id": new_pane.pane_id})
+
+
+@app.command()
+def kill(
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+) -> None:
+    """Kill pane."""
+    pane = get_pane(target)
+    pane.kill()
+
+    output_result({"killed": True})
+
+
+@app.command()
+def escape(
+    target: Annotated[str, typer.Option("-t", "--target", help="Target pane")] = "",
+) -> None:
+    """Send Escape key to pane."""
+    pane = get_pane(target)
+    pane.send_keys("Escape", enter=False)
+
+    output_result({"escaped": True})
+
+
+@app.command()
+def status() -> None:
+    """Show tmux state."""
+    from libtmux import Server
+
+    server = Server(socket_name=socket_name)
+
+    sessions_data = []
+    for session in server.sessions:
+        windows_data = []
+        for window in session.windows:
+            panes_data = [{"pane_id": p.pane_id, "pane_index": p.pane_index} for p in window.panes]
+            windows_data.append(
+                {
+                    "window_id": window.window_id,
+                    "window_index": window.window_index,
+                    "window_name": window.window_name,
+                    "panes": panes_data,
+                }
+            )
+        sessions_data.append(
+            {
+                "session_id": session.session_id,
+                "session_name": session.session_name,
+                "windows": windows_data,
+            }
+        )
+
+    if json_output:
+        print(json_lib.dumps({"sessions": sessions_data}, indent=2))
+    else:
+        for s in sessions_data:
+            rprint(f"[bold]{s['session_name']}[/bold] ({s['session_id']})")
+            for w in s["windows"]:
+                rprint(f"  {w['window_index']}: {w['window_name']} ({w['window_id']})")
+                for p in w["panes"]:
+                    rprint(f"    .{p['pane_index']}: {p['pane_id']}")
+
+
+if __name__ == "__main__":
+    app()

twmux/lib/execution.py

@@ -0,0 +1,121 @@
+"""Marker-based command execution with exit code capture."""
+
+import os
+import re
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from libtmux import Pane
+
+# Progressive capture expansion levels
+EXPANSION_LEVELS: list[int | None] = [100, 500, 2000, None]
+
+
+@dataclass
+class ExecResult:
+    """Result of command execution."""
+
+    output: str
+    exit_code: int  # -1 = timeout/markers not found
+    timed_out: bool
+
+
+def generate_markers() -> tuple[str, str]:
+    """Generate unique start and end markers.
+
+    Uses PID + nanosecond timestamp for uniqueness.
+    """
+    unique_id = f"{os.getpid()}_{time.time_ns()}"
+    start_marker = f"__TWMUX_START_{unique_id}__"
+    end_marker = f"__TWMUX_END_{unique_id}__"
+    return start_marker, end_marker
+
+
+def wrap_command(cmd: str, start_marker: str, end_marker: str) -> str:
+    """Wrap command with markers to capture output and exit code."""
+    return f"echo {start_marker}; {{ {cmd}; }} 2>&1; echo {end_marker}:$?"
+
+
+def parse_output(captured: str, start_marker: str, end_marker: str) -> ExecResult:
+    """Parse captured output to extract command output and exit code.
+
+    Returns:
+        ExecResult with parsed output and exit code, or exit_code=-1 if markers not found
+    """
+    if start_marker not in captured:
+        return ExecResult(output=captured, exit_code=-1, timed_out=False)
+
+    # Find end marker with exit code
+    end_pattern = re.escape(end_marker) + r":(\d+)"
+    end_match = re.search(end_pattern, captured)
+
+    if not end_match:
+        return ExecResult(output=captured, exit_code=-1, timed_out=False)
+
+    exit_code = int(end_match.group(1))
+
+    # Extract output between markers (use rfind to get LAST occurrence,
+    # since the marker also appears in the echoed command line)
+    start_idx = captured.rfind(start_marker) + len(start_marker)
+    end_idx = end_match.start()
+
+    output = captured[start_idx:end_idx].strip()
+
+    return ExecResult(output=output, exit_code=exit_code, timed_out=False)
+
+
+def execute(
+    pane: "Pane",
+    cmd: str,
+    timeout: float = 30.0,
+    poll_interval: float = 0.2,
+) -> ExecResult:
+    """Execute command and capture output with exit code.
+
+    Uses unique markers to reliably capture command output and exit code.
+    Polls with progressive expansion to handle long outputs efficiently.
+
+    Args:
+        pane: libtmux Pane object
+        cmd: Command to execute
+        timeout: Maximum seconds to wait for completion
+        poll_interval: Seconds between polls
+
+    Returns:
+        ExecResult with output, exit code, and timeout status
+    """
+    start_marker, end_marker = generate_markers()
+    wrapped = wrap_command(cmd, start_marker, end_marker)
+
+    # Send wrapped command
+    pane.send_keys(wrapped, enter=True)
+
+    start_time = time.monotonic()
+
+    while True:
+        elapsed = time.monotonic() - start_time
+        if elapsed >= timeout:
+            return ExecResult(output="", exit_code=-1, timed_out=True)
+
+        # Try progressive expansion levels
+        for lines in EXPANSION_LEVELS:
+            if lines is None:
+                captured = "\n".join(pane.capture_pane())
+            else:
+                captured = "\n".join(pane.capture_pane(start=-lines))
+
+            # Check if end marker present
+            end_pattern = re.escape(end_marker) + r":(\d+)"
+            if re.search(end_pattern, captured):
+                # Verify start marker also present
+                if start_marker in captured:
+                    return parse_output(captured, start_marker, end_marker)
+                # End found but not start - need more lines
+                continue
+            else:
+                # End not found - wait and poll again
+                break
+
+        time.sleep(poll_interval)

twmux/lib/safe_input.py

@@ -0,0 +1,120 @@
+"""Race-condition-safe tmux input operations."""
+
+import hashlib
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from libtmux import Pane
+
+
+@dataclass
+class SendResult:
+    """Result of a safe send operation."""
+
+    success: bool
+    attempts: int
+
+
+@dataclass
+class WaitResult:
+    """Result of wait_for_idle operation."""
+
+    idle: bool
+    elapsed: float
+
+
+def _hash_content(content: list[str]) -> str:
+    """Hash pane content for comparison."""
+    text = "\n".join(content)
+    return hashlib.md5(text.encode()).hexdigest()
+
+
+def wait_for_idle(
+    pane: "Pane",
+    poll_interval: float = 0.2,
+    stable_count: int = 3,
+    timeout: float = 30.0,
+) -> WaitResult:
+    """Wait until pane output stabilizes.
+
+    Args:
+        pane: libtmux Pane object
+        poll_interval: Seconds between content checks
+        stable_count: Number of consecutive identical hashes required
+        timeout: Maximum seconds to wait
+
+    Returns:
+        WaitResult with idle=True if stabilized, False if timeout
+    """
+    start = time.monotonic()
+    last_hash = None
+    consecutive = 0
+
+    while True:
+        elapsed = time.monotonic() - start
+        if elapsed >= timeout:
+            return WaitResult(idle=False, elapsed=elapsed)
+
+        content = pane.capture_pane()
+        current_hash = _hash_content(content)
+
+        if current_hash == last_hash:
+            consecutive += 1
+            if consecutive >= stable_count:
+                return WaitResult(idle=True, elapsed=elapsed)
+        else:
+            consecutive = 1
+            last_hash = current_hash
+
+        time.sleep(poll_interval)
+
+
+def send_safe(
+    pane: "Pane",
+    text: str,
+    enter: bool = True,
+    enter_delay: float = 0.05,
+    max_retries: int = 3,
+    retry_delay: float = 0.1,
+) -> SendResult:
+    """Send text to pane with optional Enter verification.
+
+    Args:
+        pane: libtmux Pane object
+        text: Text to send
+        enter: Whether to send Enter after text
+        enter_delay: Delay between text and Enter (race condition mitigation)
+        max_retries: Maximum Enter retry attempts
+        retry_delay: Delay between retries
+
+    Returns:
+        SendResult indicating success and attempt count
+    """
+    # Send the text without Enter first
+    pane.send_keys(text, enter=False)
+
+    if not enter:
+        return SendResult(success=True, attempts=1)
+
+    # Delay before Enter to avoid race condition
+    time.sleep(enter_delay)
+
+    # Capture content before Enter for verification
+    content_before = pane.capture_pane()
+
+    for attempt in range(1, max_retries + 1):
+        pane.enter()
+        time.sleep(enter_delay)
+
+        content_after = pane.capture_pane()
+
+        # Verify Enter was received: content should change
+        if content_after != content_before:
+            return SendResult(success=True, attempts=attempt)
+
+        # Retry with increasing delay
+        time.sleep(retry_delay * attempt)
+
+    return SendResult(success=False, attempts=max_retries)

twmux-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: twmux
+Version: 0.1.0
+Summary: Race-condition-safe tmux wrapper for coding agents
+Author-email: sysid <sysid@gmx.de>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: libtmux>=0.46
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+
+<p align="center">
+  <img src="docs/logo_264x264.png" alt="twmux logo" width="200">
+</p>
+
+Race-condition-safe tmux wrapper for coding agents.
+
+## Installation
+
+```bash
+uv pip install -e .
+```
+
+## Usage
+
+```bash
+twmux [OPTIONS] COMMAND [ARGS]
+```
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON (for programmatic use) |
+| `-L, --socket NAME` | Connect to specific tmux socket |
+| `-v, --verbose` | Verbose output |
+
+## Commands
+
+### send - Send text safely
+
+Send text to a pane with race-condition-safe Enter handling.
+
+```bash
+twmux send -t %5 "echo hello"
+twmux send -t main:0.1 "make test" --delay 0.1
+twmux send -t %5 "partial text" --no-enter
+```
+
+### exec - Execute and capture
+
+Execute a command and capture output with exit code.
+
+```bash
+twmux exec -t %5 "ls -la"
+twmux --json exec -t main:0 "make test" --timeout 60
+```
+
+Returns:
+- `output`: Command stdout/stderr
+- `exit_code`: Command exit code (-1 if timeout)
+- `timed_out`: Whether command timed out
+
+### capture - Capture pane content
+
+```bash
+twmux capture -t %5
+twmux capture -t %5 -n 50  # Last 50 lines
+twmux --json capture -t main:0
+```
+
+### wait-idle - Wait for output stabilization
+
+Wait until pane output stops changing.
+
+```bash
+twmux wait-idle -t %5
+twmux wait-idle -t %5 --timeout 10 --interval 0.1
+```
+
+### interrupt - Send Ctrl+C
+
+```bash
+twmux interrupt -t %5
+```
+
+### escape - Send Escape key
+
+```bash
+twmux escape -t %5
+```
+
+### launch - Create new pane
+
+Split current pane to create a new one.
+
+```bash
+twmux launch -t %5                      # Split below
+twmux launch -t %5 -v                   # Split right (vertical)
+twmux launch -t %5 -c "python3"         # Split and run command
+```
+
+### kill - Kill pane
+
+```bash
+twmux kill -t %5
+```
+
+### status - Show tmux state
+
+```bash
+twmux status
+twmux --json status
+```
+
+## Target Addressing
+
+The `-t` option accepts tmux target syntax to identify panes.
+
+### Pane ID (Recommended)
+
+Direct pane reference using tmux pane ID:
+
+```bash
+twmux send -t %5 "echo hello"      # Pane ID %5
+twmux exec -t %12 "ls"             # Pane ID %12
+```
+
+Get pane IDs with `twmux status` or `tmux list-panes -a`.
+
+### Session:Window.Pane Format
+
+Hierarchical addressing:
+
+```bash
+# Full path: session:window.pane
+twmux send -t main:0.1 "echo hello"    # Session "main", window 0, pane 1
+twmux send -t dev:2.0 "make test"      # Session "dev", window 2, pane 0
+
+# Partial paths
+twmux send -t main:0 "echo hello"      # Session "main", window 0, active pane
+twmux send -t main: "echo hello"       # Session "main", active window/pane
+twmux send -t :0.1 "echo hello"        # First session, window 0, pane 1
+```
+
+### Target Resolution
+
+| Target | Meaning |
+|--------|---------|
+| `%5` | Pane with ID %5 (absolute) |
+| `main:0.1` | Session "main", window 0, pane 1 |
+| `main:0` | Session "main", window 0, active pane |
+| `main:` | Session "main", active window and pane |
+| `:0.1` | First session, window 0, pane 1 |
+| `:0` | First session, window 0, active pane |
+| (empty) | First session, active window and pane |
+
+### Examples
+
+```bash
+# Start a REPL in a new pane and interact with it
+twmux launch -t %5 -c "python3"
+# Returns: {"pane_id": "%12"}
+
+# Send commands to the new pane
+twmux send -t %12 "print('hello')"
+twmux wait-idle -t %12
+
+# Capture output
+twmux capture -t %12 -n 10
+
+# Execute and get result
+twmux --json exec -t %12 "print(1+1)"
+# Returns: {"output": "2", "exit_code": 0, "timed_out": false}
+
+# Clean up
+twmux kill -t %12
+```
+
+## JSON Output
+
+All commands support `--json` for programmatic use:
+
+```bash
+$ twmux --json exec -t %5 "echo hello"
+{"output": "hello", "exit_code": 0, "timed_out": false}
+
+$ twmux --json send -t %5 "test"
+{"success": true, "attempts": 1}
+
+$ twmux --json status
+{
+  "sessions": [
+    {
+      "session_id": "$0",
+      "session_name": "main",
+      "windows": [...]
+    }
+  ]
+}
+```
+
+## How It Works
+
+### Race-Condition-Safe Send
+
+The `send` command:
+1. Sends text without Enter
+2. Waits (configurable delay)
+3. Captures pane content
+4. Sends Enter
+5. Verifies content changed
+6. Retries if needed
+
+### Marker-Based Execution
+
+The `exec` command:
+1. Generates unique markers
+2. Wraps command: `echo START; { cmd; } 2>&1; echo END:$?`
+3. Polls pane with progressive expansion (100 → 500 → 2000 → all lines)
+4. Parses output between markers
+5. Extracts exit code
+
+### Output Stabilization
+
+The `wait-idle` command:
+1. Hashes pane content (MD5)
+2. Polls at configurable interval
+3. Returns when N consecutive hashes match
+4. Times out if content keeps changing
+
+## Development
+
+```bash
+make install   # Install dependencies
+make test      # Run tests
+make lint      # Check code style
+make format    # Auto-format code
+make check     # Run lint + test
+```
+
+## License
+
+MIT
+
+
+### Prior Art, Inspiration
+- [GitHub - pchalasani/claude-code-tools](https://github.com/pchalasani/claude-code-tools)

twmux-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+twmux/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+twmux/bin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+twmux/bin/cli.py,sha256=hXiFpNhKV6N3yQnylRrc8_xOzFJBr7Sn6y65-H2sTQo,7914
+twmux/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+twmux/lib/execution.py,sha256=VLVOWaVnKIAUAxpPwGTpnpIrA-ZmH-jytogdx8VkX84,3801
+twmux/lib/safe_input.py,sha256=y9nrhb_AIecMTZA_WpDsowktGujM5PXI0ABYkMkeLOQ,3040
+twmux-0.1.0.dist-info/METADATA,sha256=6xeAQYwzETiYGw3o2kX7XYCAAh9sSiTiWID2T3vaanY,5428
+twmux-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+twmux-0.1.0.dist-info/entry_points.txt,sha256=ReZKwESJxhZyrSQNXPV4U1jvOb0g14E_81KVPXzlKno,44
+twmux-0.1.0.dist-info/top_level.txt,sha256=qpZCQer5e2-eXJ_ztdXMMLdyKZBXiItxGcRXu-dlaPs,6
+twmux-0.1.0.dist-info/RECORD,,

twmux-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

twmux-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+twmux = twmux.bin.cli:app

twmux-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+twmux