tui-input 0.1.0__py3-none-any.whl

tui_input/__init__.py

@@ -0,0 +1,5 @@
+"""tui-input: A terminal companion that pins a persistent input bar at the bottom of tmux."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

tui_input/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m tui_input`."""
+
+from tui_input.cli import main
+
+main()

tui_input/cli.py

@@ -0,0 +1,116 @@
+"""CLI entry point for tui-input."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tui_input import __version__
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Main entry point for the tui-input CLI."""
+    parser = argparse.ArgumentParser(
+        prog="tui-input",
+        description="A terminal companion that pins a persistent input bar at the bottom of tmux.",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Command to run in the top pane (e.g., 'claude', 'codex', 'vim file.py')",
+    )
+    parser.add_argument(
+        "--companion",
+        action="store_true",
+        help=argparse.SUPPRESS,  # Internal flag
+    )
+    parser.add_argument(
+        "--target-pane",
+        help=argparse.SUPPRESS,  # Internal flag
+    )
+    parser.add_argument(
+        "--fix-layout",
+        action="store_true",
+        help=argparse.SUPPRESS,  # Internal flag
+    )
+    parser.add_argument(
+        "--agent-pane",
+        help=argparse.SUPPRESS,  # Internal flag
+    )
+    parser.add_argument(
+        "--companion-pane",
+        help=argparse.SUPPRESS,  # Internal flag
+    )
+
+    args = parser.parse_args(argv)
+
+    # Internal: fix layout after split
+    if args.fix_layout:
+        if not args.agent_pane or not args.companion_pane:
+            print(
+                "Error: --agent-pane and --companion-pane are required with --fix-layout",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        _fix_layout(args.agent_pane, args.companion_pane)
+        return
+
+    # Internal: run as companion widget
+    if args.companion:
+        if not args.target_pane:
+            print("Error: --target-pane is required with --companion", file=sys.stderr)
+            sys.exit(1)
+        _run_companion(args.target_pane)
+        return
+
+    # User-facing: launch agent + companion
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    command = " ".join(args.command)
+    _launch(command)
+
+
+def _launch(command: str) -> None:
+    """Validate environment and launch the tmux split."""
+    from tui_input.tmux import TmuxNotInstalledError, ensure_tmux_installed
+
+    try:
+        ensure_tmux_installed()
+    except TmuxNotInstalledError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    from tui_input.launcher import launch
+
+    launch(command)
+
+
+def _run_companion(target_pane: str) -> None:
+    """Run the companion app."""
+    from tui_input.companion import run_companion
+
+    run_companion(target_pane)
+
+
+def _fix_layout(agent_pane: str, companion_pane: str) -> None:
+    """Rejoin companion pane below agent if layout was broken by a split."""
+    from tui_input.launcher import COMPANION_HEIGHT
+    from tui_input.tmux import pane_width, rejoin_companion
+
+    agent_w = pane_width(agent_pane)
+    companion_w = pane_width(companion_pane)
+    if agent_w != companion_w:
+        rejoin_companion(agent_pane, companion_pane, COMPANION_HEIGHT)
+
+
+# Support running as `python -m tui_input`
+if __name__ == "__main__":
+    main()

tui_input/companion.py

@@ -0,0 +1,444 @@
+"""Textual companion app — pinned input bar at the bottom of a tmux split."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar
+
+from textual import on
+from textual.app import App, ComposeResult
+from textual.widgets import Static, TextArea
+
+from tui_input.history import History
+from tui_input.tmux import (
+    cancel_copy_mode,
+    pane_alive,
+    pane_height,
+    pane_pid,
+    resize_pane,
+    send_keys,
+    send_raw,
+    submit_to_pane,
+    unset_hook,
+)
+
+if TYPE_CHECKING:
+    from textual.events import Key
+    from textual.timer import Timer
+
+# ---------------------------------------------------------------------------
+# Layout constants
+# ---------------------------------------------------------------------------
+
+MIN_HEIGHT = 7
+MAX_HEIGHT = 12
+PROCESS_CHECK_INTERVAL = 0.3
+
+# IME commit delay — short enough to be imperceptible, long enough for
+# terminal IME to settle after a key event.
+_IME_COMMIT_DELAY = 0.05
+
+CSS_PATH = Path(__file__).parent / "companion.tcss"
+
+# Rough bytes-per-token ratio used for the status bar estimate.
+_BYTES_PER_TOKEN = 4
+
+# ---------------------------------------------------------------------------
+# Key mapping tables
+#
+# Each table maps a Textual key name to a value that determines how the
+# key is forwarded to the agent pane.
+# ---------------------------------------------------------------------------
+
+# Keys that insert a newline (terminal-dependent names for Shift+Enter).
+_NEWLINE_KEYS: frozenset[str] = frozenset(
+    {
+        "shift+enter",
+        "shift+return",
+        "alt+enter",
+        "meta+enter",
+        "ctrl+j",
+    }
+)
+
+# Keys that are ALWAYS forwarded to the agent pane as raw bytes,
+# regardless of whether the companion has text.
+_ALWAYS_FORWARD_KEYS: dict[str, str] = {
+    "ctrl+c": "\x03",
+}
+
+# Keys forwarded to the agent only when the companion is empty (raw bytes).
+_EMPTY_FORWARD_RAW: dict[str, str] = {
+    "escape": "\x1b",
+    "ctrl+d": "\x04",
+    "ctrl+l": "\x0c",
+    "ctrl+z": "\x1a",
+}
+
+# Keys forwarded to the agent only when the companion is empty (tmux key names).
+_EMPTY_FORWARD_NAMED: dict[str, str] = {
+    "left": "Left",
+    "right": "Right",
+    "up": "Up",
+    "down": "Down",
+    "tab": "Tab",
+    "shift+tab": "BTab",
+}
+
+# Known interactive shells — used by ``_is_shell`` to distinguish a shell
+# wrapper from a directly-executed agent process.
+_KNOWN_SHELLS: frozenset[str] = frozenset(
+    {
+        "zsh",
+        "bash",
+        "sh",
+        "fish",
+        "dash",
+        "ksh",
+        "tcsh",
+        "csh",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Process inspection helpers
+# ---------------------------------------------------------------------------
+
+
+def _estimate_tokens(text: str) -> int:
+    """Rough token estimate based on UTF-8 byte length."""
+    if not text:
+        return 0
+    return max(1, len(text.encode("utf-8")) // _BYTES_PER_TOKEN)
+
+
+def _has_children(pid: int) -> bool:
+    """Return True if *pid* has any child processes (requires ``pgrep``)."""
+    result = subprocess.run(
+        ["pgrep", "-P", str(pid)],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def _is_shell(pid: int) -> bool:
+    """Return True if *pid* is a known interactive shell."""
+    try:
+        result = subprocess.run(
+            ["ps", "-p", str(pid), "-o", "comm="],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        # Login shells are prefixed with "-" (e.g. "-zsh").
+        comm = result.stdout.strip().lstrip("-")
+        return comm in _KNOWN_SHELLS
+    except subprocess.CalledProcessError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# InputArea — custom TextArea with key forwarding
+# ---------------------------------------------------------------------------
+
+
+class InputArea(TextArea):
+    """Custom TextArea that replaces the agent CLI's input area.
+
+    Intercepts specific keys (Enter, Shift+Enter, Ctrl+C, …) and either
+    forwards them to the agent pane or performs local actions (newline,
+    send, history navigation).  All other keys are delegated to the
+    parent ``TextArea``.
+    """
+
+    _pending_enter_timer: Timer | None = None
+
+    # -- Timer management ----------------------------------------------------
+
+    def _cancel_pending_enter(self) -> None:
+        """Cancel any pending deferred Enter/newline timer."""
+        if self._pending_enter_timer is not None:
+            self._pending_enter_timer.stop()
+            self._pending_enter_timer = None
+
+    # -- Deferred actions (IME-safe) -----------------------------------------
+
+    def _deferred_send(self) -> None:
+        """Schedule ``_send`` after the IME commit delay."""
+
+        def _callback() -> None:
+            self._pending_enter_timer = None
+            self._send()
+
+        self._pending_enter_timer = self.set_timer(_IME_COMMIT_DELAY, _callback)
+
+    def _deferred_newline(self) -> None:
+        """Schedule newline insertion after the IME commit delay."""
+
+        def _callback() -> None:
+            self._pending_enter_timer = None
+            self.insert("\n")
+
+        self._pending_enter_timer = self.set_timer(_IME_COMMIT_DELAY, _callback)
+
+    def _deferred_enter(self) -> None:
+        """Schedule Enter action after the IME commit delay.
+
+        After the delay: if empty, forward ``\\r`` to agent; otherwise send.
+        """
+
+        def _callback() -> None:
+            self._pending_enter_timer = None
+            if not self.text:
+                self._forward_raw("\r")
+            else:
+                self._send()
+
+        self._pending_enter_timer = self.set_timer(_IME_COMMIT_DELAY, _callback)
+
+    # -- Text submission -----------------------------------------------------
+
+    def _send(self) -> None:
+        """Send text to the target pane and clear the editor."""
+        app = self.app
+        if not isinstance(app, CompanionApp):
+            return
+        text = self.text.strip()
+        if not text:
+            return
+        try:
+            submit_to_pane(app.target_pane, text)
+        except Exception:
+            app.bell()
+            return
+        app.history.add(text)
+        self.text = ""
+        if app.companion_pane:
+            with contextlib.suppress(subprocess.CalledProcessError):
+                resize_pane(app.companion_pane, MIN_HEIGHT)
+        self._scroll_target_to_bottom()
+
+    def _scroll_target_to_bottom(self) -> None:
+        """Exit copy-mode on the target pane so it scrolls to the bottom."""
+        if not isinstance(self.app, CompanionApp):
+            return
+        with contextlib.suppress(Exception):
+            cancel_copy_mode(self.app.target_pane)
+
+    # -- Key forwarding helpers ----------------------------------------------
+
+    def _forward_raw(self, data: str) -> None:
+        """Forward raw bytes to the agent pane."""
+        if not isinstance(self.app, CompanionApp):
+            return
+        with contextlib.suppress(subprocess.CalledProcessError):
+            send_raw(self.app.target_pane, data)
+
+    def _forward_key(self, tmux_key: str) -> None:
+        """Forward a named key to the agent pane via ``tmux send-keys``."""
+        if not isinstance(self.app, CompanionApp):
+            return
+        with contextlib.suppress(subprocess.CalledProcessError):
+            send_keys(self.app.target_pane, tmux_key)
+
+    # -- Key event dispatch --------------------------------------------------
+
+    async def _on_key(self, event: Key) -> None:
+        """Handle all key input with contextual forwarding."""
+        app = self.app
+        is_empty = not self.text
+
+        # --- Always forward to agent (e.g. Ctrl+C) ---
+        if event.key in _ALWAYS_FORWARD_KEYS:
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            self._forward_raw(_ALWAYS_FORWARD_KEYS[event.key])
+            return
+
+        # --- Forward to agent when companion is empty (raw bytes) ---
+        if is_empty and event.key in _EMPTY_FORWARD_RAW:
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            self._forward_raw(_EMPTY_FORWARD_RAW[event.key])
+            return
+
+        # --- Forward to agent when companion is empty (named keys) ---
+        if is_empty and event.key in _EMPTY_FORWARD_NAMED:
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            self._forward_key(_EMPTY_FORWARD_NAMED[event.key])
+            return
+
+        # --- Escape with text: clear companion ---
+        if event.key == "escape":
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            self.text = ""
+            if isinstance(app, CompanionApp):
+                app.history.reset_navigation()
+            return
+
+        # --- Newline insertion (Shift+Enter / Alt+Enter / Ctrl+J) ---
+        if event.key in _NEWLINE_KEYS:
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            self._deferred_newline()
+            return
+
+        # --- Enter: deferred for IME composition ---
+        if event.key == "enter":
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            self._deferred_enter()
+            return
+
+        # --- History navigation (Ctrl+Up/Down, empty companion only) ---
+        if not isinstance(app, CompanionApp):
+            await super()._on_key(event)
+            return
+        history = app.history
+
+        if event.key == "ctrl+up" and is_empty:
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            prev = history.get_previous()
+            if prev is not None:
+                self.text = prev
+                self.move_cursor_relative(rows=999, columns=999)
+            return
+
+        if event.key == "ctrl+down" and is_empty:
+            self._cancel_pending_enter()
+            event.prevent_default()
+            event.stop()
+            nxt = history.get_next()
+            if nxt is not None:
+                self.text = nxt
+                self.move_cursor_relative(rows=999, columns=999)
+            else:
+                self.text = ""
+            return
+
+        # --- Everything else: let TextArea handle ---
+        await super()._on_key(event)
+
+
+# ---------------------------------------------------------------------------
+# CompanionApp — Textual application
+# ---------------------------------------------------------------------------
+
+
+class CompanionApp(App[None]):
+    """A companion input widget that sends text to a target tmux pane."""
+
+    CSS_PATH: ClassVar[str | Path] = CSS_PATH
+
+    def __init__(
+        self,
+        target_pane: str,
+        companion_pane: str | None = None,
+        target_pid: int | None = None,
+    ) -> None:
+        super().__init__()
+        self.target_pane = target_pane
+        self.companion_pane = companion_pane
+        self.target_pid = target_pid
+        self.history = History()
+
+    def compose(self) -> ComposeResult:
+        yield InputArea(id="editor")
+        yield Static("0 chars · 0 bytes · ~0 tokens", id="stats")
+
+    def on_mount(self) -> None:
+        editor = self.query_one("#editor", InputArea)
+        editor.show_line_numbers = False
+        editor.soft_wrap = True
+        editor.tab_behavior = "indent"
+        self.set_interval(PROCESS_CHECK_INTERVAL, self._check_target_alive)
+
+    def on_unmount(self) -> None:
+        """Clean up tmux hook when companion exits."""
+        if self.companion_pane:
+            with contextlib.suppress(Exception):
+                unset_hook("after-split-window", self.companion_pane)
+
+    @on(TextArea.Changed)
+    def _on_text_changed(self, event: TextArea.Changed) -> None:
+        """Adjust pane height based on line count and update stats."""
+        text = event.text_area.text
+
+        # Resize companion pane (only expand, never shrink).
+        line_count = text.count("\n") + 1 if text else 1
+        # +2 accounts for editor chrome (border) and stats footer.
+        target_height = max(MIN_HEIGHT, min(line_count + 2, MAX_HEIGHT))
+        if self.companion_pane:
+            with contextlib.suppress(subprocess.CalledProcessError):
+                current = pane_height(self.companion_pane)
+                if target_height > current:
+                    resize_pane(self.companion_pane, target_height)
+
+        # Update stats footer.
+        chars = len(text)
+        byte_count = len(text.encode("utf-8"))
+        tokens = _estimate_tokens(text)
+        stats = self.query_one("#stats", Static)
+        stats.update(f"{chars} chars · {byte_count} bytes · ~{tokens} tokens")
+
+    def _check_target_alive(self) -> None:
+        """Check if the agent pane is still alive; exit if not.
+
+        Two modes depending on what process owns the target pane:
+
+        * **Shell mode** (inside-tmux): the pane runs a shell (zsh/bash)
+          that spawned the agent as a child.  When the agent exits, the
+          shell has no children → companion exits.
+        * **Direct mode** (outside-tmux): the pane runs the agent
+          directly (no shell wrapper).  We simply check if the pane
+          process is still alive.
+        """
+        if not pane_alive(self.target_pane):
+            self.exit()
+            return
+        if self.target_pid is None:
+            return
+        if _is_shell(self.target_pid):
+            if not _has_children(self.target_pid):
+                self.exit()
+        else:
+            try:
+                os.kill(self.target_pid, 0)
+            except ProcessLookupError:
+                self.exit()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def run_companion(target_pane: str) -> None:
+    """Run the companion app targeting a specific tmux pane."""
+    # Use TMUX_PANE env var to get the companion's own pane ID.
+    # ``current_pane_id()`` uses ``tmux display-message -p`` which returns
+    # the *selected* pane (the agent), not the pane we're running in.
+    companion_pane = os.environ.get("TMUX_PANE")
+    target_pid: int | None = None
+    with contextlib.suppress(Exception):
+        target_pid = pane_pid(target_pane)
+    CompanionApp(
+        target_pane=target_pane,
+        companion_pane=companion_pane,
+        target_pid=target_pid,
+    ).run()

tui_input/companion.tcss

@@ -0,0 +1,19 @@
+Screen {
+    layout: vertical;
+}
+
+#editor {
+    height: 1fr;
+    border: round $foreground 30%;
+}
+
+#editor:focus {
+    border: round $foreground 50%;
+}
+
+#stats {
+    height: 1;
+    text-align: right;
+    color: $text-muted;
+    padding: 0 1;
+}

tui_input/history.py

@@ -0,0 +1,124 @@
+"""JSON-based input history management."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_HISTORY_PATH = Path.home() / ".local" / "share" / "tui-input" / "history.json"
+MAX_ENTRIES = 100
+
+
+@dataclass
+class HistoryEntry:
+    """A single history entry."""
+
+    text: str
+    timestamp: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Serialize to a JSON-compatible dict."""
+        return {"text": self.text, "timestamp": self.timestamp}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> HistoryEntry:
+        """Deserialize from a dict."""
+        return cls(text=str(data["text"]), timestamp=str(data["timestamp"]))
+
+
+@dataclass
+class History:
+    """Manages a JSON-based input history file.
+
+    Entries are stored as a JSON array of objects with 'text' and 'timestamp' fields.
+    Duplicate entries are moved to the end (most recent position).
+    Maximum entries are capped at ``MAX_ENTRIES``.
+    """
+
+    path: Path = field(default_factory=lambda: DEFAULT_HISTORY_PATH)
+    entries: list[HistoryEntry] = field(default_factory=list)
+    _index: int = field(default=-1, repr=False)
+
+    def __post_init__(self) -> None:
+        self.load()
+
+    def load(self) -> None:
+        """Load history from the JSON file.
+
+        Falls back to an empty list on missing file or corruption.
+        """
+        if not self.path.exists():
+            self.entries = []
+            return
+        try:
+            raw = self.path.read_text(encoding="utf-8")
+            data = json.loads(raw)
+            if not isinstance(data, list):
+                self.entries = []
+                return
+            self.entries = [HistoryEntry.from_dict(item) for item in data]
+        except (json.JSONDecodeError, KeyError, TypeError, OSError):
+            self.entries = []
+
+    def save(self) -> None:
+        """Persist current entries to the JSON file."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        data = [entry.to_dict() for entry in self.entries]
+        self.path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def add(self, text: str) -> None:
+        """Add a new entry. Duplicates are moved to the end.
+
+        Empty or whitespace-only text is silently ignored.
+        """
+        if not text or not text.strip():
+            return
+        # Remove existing duplicate.
+        self.entries = [e for e in self.entries if e.text != text]
+        self.entries.append(
+            HistoryEntry(
+                text=text,
+                timestamp=datetime.now(tz=timezone.utc).isoformat(),
+            )
+        )
+        # Trim to max entries.
+        if len(self.entries) > MAX_ENTRIES:
+            self.entries = self.entries[-MAX_ENTRIES:]
+        self.save()
+        self._index = -1
+
+    def get_previous(self) -> str | None:
+        """Navigate backward in history. Returns None if at the beginning."""
+        if not self.entries:
+            return None
+        if self._index == -1:
+            self._index = len(self.entries) - 1
+        elif self._index > 0:
+            self._index -= 1
+        else:
+            return self.entries[0].text
+        return self.entries[self._index].text
+
+    def get_next(self) -> str | None:
+        """Navigate forward in history. Returns None if past the end."""
+        if not self.entries or self._index == -1:
+            return None
+        if self._index < len(self.entries) - 1:
+            self._index += 1
+            return self.entries[self._index].text
+        # Past the end — reset index.
+        self._index = -1
+        return None
+
+    def reset_navigation(self) -> None:
+        """Reset the navigation index."""
+        self._index = -1
+
+    def clear(self) -> None:
+        """Clear all history entries."""
+        self.entries = []
+        self._index = -1
+        self.save()

tui_input/launcher.py

@@ -0,0 +1,89 @@
+"""Tmux environment setup — splits pane and launches companion + agent."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import sys
+
+from tui_input.tmux import (
+    create_session_with_split,
+    current_pane_id,
+    in_tmux,
+    set_hook,
+    split_window,
+)
+
+COMPANION_HEIGHT = 7
+SESSION_NAME = "tui-input"
+
+
+def launch(command: str) -> None:
+    """Set up tmux split and launch the companion alongside the given command.
+
+    If already inside tmux, splits the current pane.
+    If outside tmux, creates a new session with the split.
+
+    The current process is replaced by the agent command (top pane).
+    """
+    tui_input_bin = _find_tui_input_bin()
+    companion_base = f"{tui_input_bin} --companion --target-pane"
+
+    if in_tmux():
+        _launch_inside_tmux(command, tui_input_bin, companion_base)
+    else:
+        _launch_outside_tmux(command, companion_base)
+
+
+def _find_tui_input_bin() -> str:
+    """Return a shell command that invokes tui-input via the current interpreter."""
+    return f"{sys.executable} -m tui_input"
+
+
+def _launch_inside_tmux(command: str, tui_input_bin: str, companion_base: str) -> None:
+    """Split the current tmux pane and launch companion in the bottom."""
+    top_pane = current_pane_id()
+    companion_cmd = f"{companion_base} {top_pane}"
+
+    # Split current pane: companion goes to the bottom.
+    companion_pane = split_window(COMPANION_HEIGHT, companion_cmd)
+
+    # Register hook to fix layout when agent pane is split.
+    fix_layout_cmd = (
+        f"run-shell '{tui_input_bin} --fix-layout"
+        f" --agent-pane {top_pane} --companion-pane {companion_pane}'"
+    )
+    set_hook("after-split-window", fix_layout_cmd, target=top_pane)
+
+    # Replace current process with the agent command.
+    args = shlex.split(command)
+    _validate_command(args[0])
+    os.execvp(args[0], args)  # noqa: S606 — command is validated above
+
+
+def _launch_outside_tmux(command: str, companion_base: str) -> None:
+    """Create a new tmux session with agent + companion split."""
+    # The companion command will resolve the target pane at startup.
+    companion_cmd = (
+        f"sleep 0.5 && TARGET=$(tmux list-panes -t {SESSION_NAME}: "
+        f"-F '#{{pane_id}}' | head -1) && "
+        f"{companion_base} $TARGET"
+    )
+
+    create_session_with_split(
+        session_name=SESSION_NAME,
+        main_command=command,
+        companion_command=companion_cmd,
+        companion_height=COMPANION_HEIGHT,
+    )
+
+
+def _validate_command(executable: str) -> None:
+    """Verify that *executable* exists on PATH before ``execvp``.
+
+    Raises:
+        SystemExit: If the executable cannot be found.
+    """
+    if shutil.which(executable) is None:
+        raise SystemExit(f"Error: command not found: {executable}")

tui_input/tmux.py

@@ -0,0 +1,292 @@
+"""Tmux utility functions for pane management and text pasting."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+
+
+class TmuxNotInstalledError(RuntimeError):
+    """Raised when tmux is not found on the system."""
+
+
+class TmuxCommandError(RuntimeError):
+    """Raised when a tmux subcommand fails with additional context."""
+
+
+def ensure_tmux_installed() -> None:
+    """Check that tmux is installed and raise a helpful error if not."""
+    if shutil.which("tmux") is None:
+        raise TmuxNotInstalledError(
+            "tmux is required but not installed.\n"
+            "Install it with:\n"
+            "  macOS:  brew install tmux\n"
+            "  Ubuntu: sudo apt install tmux\n"
+            "  Fedora: sudo dnf install tmux"
+        )
+
+
+def in_tmux() -> bool:
+    """Return True if the current process is running inside a tmux session."""
+    return "TMUX" in os.environ
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _run_tmux(*args: str) -> str:
+    """Run a tmux subcommand and return stripped stdout.
+
+    Raises:
+        TmuxCommandError: If the tmux command exits with a non-zero status.
+    """
+    try:
+        result = subprocess.run(
+            ["tmux", *args],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        cmd_str = " ".join(["tmux", *args])
+        stderr = (exc.stderr or "").strip()
+        raise TmuxCommandError(f"tmux command failed: {cmd_str!r} — {stderr}") from exc
+    return result.stdout.strip()
+
+
+def _paste_via_buffer(pane_id: str, data: bytes, *, bracketed: bool = False) -> None:
+    """Write *data* to a temp file, load it into a tmux buffer, and paste it.
+
+    Args:
+        pane_id: Target tmux pane.
+        data: Raw bytes to paste.
+        bracketed: If True, use bracketed-paste mode (``-p``).
+    """
+    with tempfile.NamedTemporaryFile(mode="wb", suffix=".txt", delete=False) as f:
+        f.write(data)
+        tmp_path = f.name
+    try:
+        _run_tmux("load-buffer", tmp_path)
+        paste_args = ["paste-buffer", "-d", "-t", pane_id]
+        if bracketed:
+            paste_args.insert(1, "-p")
+        _run_tmux(*paste_args)
+    finally:
+        os.unlink(tmp_path)
+
+
+# ---------------------------------------------------------------------------
+# Public API — pane queries
+# ---------------------------------------------------------------------------
+
+
+def current_pane_id() -> str:
+    """Return the pane ID (e.g. '%3') of the current tmux pane."""
+    return _run_tmux("display-message", "-p", "#{pane_id}")
+
+
+def pane_exists(pane_id: str) -> bool:
+    """Check if a tmux pane still exists."""
+    try:
+        result = subprocess.run(
+            ["tmux", "list-panes", "-a", "-F", "#{pane_id}"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return pane_id in result.stdout.splitlines()
+    except subprocess.CalledProcessError:
+        return False
+
+
+def pane_pid(pane_id: str) -> int | None:
+    """Return the PID of the process running in a tmux pane, or None."""
+    try:
+        result = _run_tmux("display-message", "-t", pane_id, "-p", "#{pane_pid}")
+        return int(result)
+    except (TmuxCommandError, ValueError):
+        return None
+
+
+def pane_alive(pane_id: str) -> bool:
+    """Check if a tmux pane exists AND its process is still running.
+
+    Returns False if the pane doesn't exist or its process has exited
+    (even if the pane remains due to ``remain-on-exit``).
+    """
+    try:
+        result = subprocess.run(
+            ["tmux", "display-message", "-t", pane_id, "-p", "#{pane_dead}"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip() != "1"
+    except subprocess.CalledProcessError:
+        return False
+
+
+def pane_height(pane_id: str) -> int:
+    """Return the height in lines of a tmux pane."""
+    return int(_run_tmux("display-message", "-t", pane_id, "-p", "#{pane_height}"))
+
+
+def pane_width(pane_id: str) -> int:
+    """Return the width in columns of a tmux pane."""
+    return int(_run_tmux("display-message", "-t", pane_id, "-p", "#{pane_width}"))
+
+
+# ---------------------------------------------------------------------------
+# Public API — pane actions
+# ---------------------------------------------------------------------------
+
+
+def split_window(size: int, command: str | None = None) -> str:
+    """Split the current pane vertically and return the new pane ID.
+
+    Args:
+        size: Height in lines for the new (bottom) pane.
+        command: Optional shell command to run in the new pane.
+
+    Returns:
+        The pane ID of the newly created pane.
+    """
+    args = ["split-window", "-v", "-l", str(size), "-P", "-F", "#{pane_id}"]
+    if command:
+        args.append(command)
+    return _run_tmux(*args)
+
+
+def send_keys(pane_id: str, keys: str) -> None:
+    """Send a named key (e.g. 'Enter', 'Escape', 'C-c') to a tmux pane."""
+    _run_tmux("send-keys", "-t", pane_id, keys)
+
+
+def send_raw(pane_id: str, data: str) -> None:
+    """Send raw bytes to a tmux pane via load-buffer + paste-buffer.
+
+    Unlike send_keys, this sends arbitrary data without key name interpretation.
+    Useful for forwarding control characters (Ctrl+C = ``\\x03``, etc.).
+    """
+    _paste_via_buffer(pane_id, data.encode("utf-8"))
+
+
+def paste_to_pane(pane_id: str, text: str) -> None:
+    """Paste text into a tmux pane using bracketed paste for safe multi-line handling."""
+    _paste_via_buffer(pane_id, text.encode("utf-8"), bracketed=True)
+
+
+def submit_to_pane(pane_id: str, text: str) -> None:
+    """Paste text into a pane, then send Enter separately.
+
+    The text and the submit keystroke are sent as two distinct operations
+    so that the target application (e.g. Claude Code) reliably treats
+    Enter as a submit action rather than part of the pasted content.
+    """
+    _paste_via_buffer(pane_id, text.encode("utf-8"))
+    _run_tmux("send-keys", "-t", pane_id, "Enter")
+
+
+def resize_pane(pane_id: str, height: int) -> None:
+    """Resize a tmux pane to the given height."""
+    _run_tmux("resize-pane", "-t", pane_id, "-y", str(height))
+
+
+def set_hook(hook_name: str, command: str, target: str) -> None:
+    """Register a tmux hook at window scope."""
+    _run_tmux("set-hook", "-w", "-t", target, hook_name, command)
+
+
+def unset_hook(hook_name: str, target: str) -> None:
+    """Remove a tmux hook at window scope."""
+    _run_tmux("set-hook", "-u", "-w", "-t", target, hook_name)
+
+
+def rejoin_companion(agent_pane: str, companion_pane: str, height: int) -> None:
+    """Move companion pane below agent pane with join-pane."""
+    _run_tmux("join-pane", "-v", "-s", companion_pane, "-t", agent_pane, "-l", str(height))
+
+
+def cancel_copy_mode(pane_id: str) -> None:
+    """Exit copy-mode on a pane so it scrolls to the bottom.
+
+    If the pane is not in copy-mode, the enter/cancel sequence is harmless.
+    """
+    _run_tmux("copy-mode", "-t", pane_id)
+    _run_tmux("send-keys", "-t", pane_id, "-X", "cancel")
+
+
+# ---------------------------------------------------------------------------
+# Session management
+# ---------------------------------------------------------------------------
+
+
+def create_session_with_split(
+    session_name: str,
+    main_command: str,
+    companion_command: str,
+    companion_height: int = 3,
+) -> None:
+    """Create a new tmux session with a vertical split.
+
+    The main command runs in the top pane; the companion runs in the bottom.
+    This function replaces the current process with ``tmux attach``.
+
+    Args:
+        session_name: Name for the tmux session.
+        main_command: Shell command to run in the top pane.
+        companion_command: Shell command to run in the bottom pane.
+        companion_height: Height in lines for the bottom pane.
+    """
+    # Kill any stale session with the same name before creating a new one.
+    subprocess.run(
+        ["tmux", "kill-session", "-t", session_name],
+        capture_output=True,
+    )
+    subprocess.run(
+        [
+            "tmux",
+            "new-session",
+            "-d",
+            "-s",
+            session_name,
+            "-x",
+            "200",
+            "-y",
+            "50",
+            main_command,
+        ],
+        check=True,
+    )
+    # Grab the top pane's ID before splitting (works regardless of base-index).
+    top_pane = (
+        subprocess.run(
+            ["tmux", "list-panes", "-t", f"{session_name}:", "-F", "#{pane_id}"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        .stdout.strip()
+        .splitlines()[0]
+    )
+    subprocess.run(
+        [
+            "tmux",
+            "split-window",
+            "-t",
+            f"{session_name}:",
+            "-v",
+            "-l",
+            str(companion_height),
+            companion_command,
+        ],
+        check=True,
+    )
+    # Select the top pane so the user interacts with the agent.
+    subprocess.run(["tmux", "select-pane", "-t", top_pane], check=True)
+    # User-provided command is already validated by the CLI layer.
+    os.execvp("tmux", ["tmux", "attach-session", "-t", session_name])  # noqa: S606

tui_input-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: tui-input
+Version: 0.1.0
+Summary: A terminal companion that pins a persistent input bar at the bottom of your tmux pane, so you can scroll freely through long TUI agent output while composing your response.
+Project-URL: Homepage, https://github.com/maked-dev/tui-input
+Project-URL: Repository, https://github.com/maked-dev/tui-input
+Project-URL: Issues, https://github.com/maked-dev/tui-input/issues
+Project-URL: Changelog, https://github.com/maked-dev/tui-input/blob/main/CHANGELOG.md
+Author: maked-dev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,codex,input,terminal,tmux,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: textual>=0.85.0
+Description-Content-Type: text/markdown
+
+# tui-input
+
+[![CI](https://github.com/maked-dev/tui-input/actions/workflows/ci.yml/badge.svg)](https://github.com/maked-dev/tui-input/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tui-input)](https://pypi.org/project/tui-input/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A terminal companion that pins a persistent input bar at the bottom of your tmux pane. Scroll freely through long TUI agent output while composing your response.
+
+<!-- TODO: demo GIF -->
+<!-- ![demo](https://github.com/maked-dev/tui-input/assets/demo.gif) -->
+
+## The Problem
+
+When using TUI-based AI agents (Claude Code, Codex CLI, etc.), long outputs force you to scroll up to read, then scroll back down to type. You end up:
+
+- Losing your place in the output
+- Writing responses in a separate editor, then copy-pasting
+- Fighting the terminal scroll position
+
+## The Solution
+
+`tui-input` splits your terminal into two panes:
+
+```
+┌─────────────────────────────────────┐
+│  Top pane (Claude Code / Codex etc) │
+│  Scroll freely through long output  │
+├─────────────────────────────────────┤  ← 3-10 lines, auto-resizing
+│  Type your response here...         │
+│  Enter to send · Shift+Enter: newline│
+└─────────────────────────────────────┘
+```
+
+## Features
+
+- **Pinned input bar** — always visible at the bottom, regardless of scroll position
+- **Auto-resize** — companion grows from 3 to 10 lines as you type multi-line input
+- **Bracketed paste** — safe multi-line text transfer via tmux buffers
+- **Input history** — press `↑`/`↓` to recall previous inputs (persisted across sessions)
+- **Agent-agnostic** — works with any terminal program, not just AI agents
+- **Auto-cleanup** — companion exits when the agent exits
+
+## Installation
+
+### Requirements
+
+- Python 3.10+
+- tmux
+
+### Install via pip/uv
+
+```bash
+# Using uv (recommended)
+uv tool install tui-input
+
+# Using pip
+pip install tui-input
+```
+
+### One-liner (auto-detects agents + registers aliases)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/maked-dev/tui-input/main/install.sh | bash
+```
+
+This will:
+1. Install `tui-input`
+2. Detect installed agents (claude, codex, etc.)
+3. Register shell aliases so you can just type `claude` instead of `tui-input claude`
+
+To uninstall aliases:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/maked-dev/tui-input/main/install.sh | bash -s -- --uninstall
+```
+
+## Usage
+
+```bash
+# Basic usage
+tui-input claude
+
+# Any command works
+tui-input "vim file.py"
+tui-input htop
+
+# With aliases installed (via install.sh), just type the agent name
+claude
+codex
+```
+
+### Key Bindings
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Send text to top pane + clear input |
+| `Shift+Enter` | Insert newline (multi-line input) |
+| `↑` (on empty) | Previous history entry |
+| `↓` (on empty) | Next history entry |
+| `Esc` | Clear all input |
+
+### How It Works
+
+1. `tui-input` creates a tmux vertical split (or a new session if not in tmux)
+2. Your command runs in the top pane
+3. A Textual-based companion widget runs in the bottom pane
+4. Press `Enter` to send text to the top pane via `tmux paste-buffer`
+5. When the top pane command exits, the companion auto-exits
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/maked-dev/tui-input.git
+cd tui-input
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and format
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+## License
+
+[MIT](LICENSE)

tui_input-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tui_input/__init__.py,sha256=4feAoWGQdg5Ldfkg-mqAKQO1E1fjaqxlPOCbyxUmKn8,144
+tui_input/__main__.py,sha256=g66YcZUXfLq-BovEvSAd7P81gVKi5mGaI5ct_aax0ls,86
+tui_input/cli.py,sha256=6cjr85hC_USYnWQefMwLT6D9-6H5F9TYc-uKf6nRwkQ,3218
+tui_input/companion.py,sha256=xsroSBTh6a-wpM44vIJblqlZO0fXnwLtEAqX2a0zgcc,14682
+tui_input/companion.tcss,sha256=o5tTz9PmJJfD4k786XNg1-R-VaC2IYJhaWMCdBSwDiM,244
+tui_input/history.py,sha256=Xov1jNT3xpIwQQb0CMaUdFkU_P9HmTKmeho4E8sSvvc,3967
+tui_input/launcher.py,sha256=I6XrLK4dlOr-KZvPCqdYbCjP-mR2uUpmgZh-FIoRQXs,2785
+tui_input/tmux.py,sha256=4nvq7UYHN_D8GlSYtVtfn5nXdIjGY-SN_ep9O3gCdKs,9392
+tui_input-0.1.0.dist-info/METADATA,sha256=hXQEfx6pamO7S77MFk2tp1Oqw8WHERjv4pyaFNvGHps,5068
+tui_input-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tui_input-0.1.0.dist-info/entry_points.txt,sha256=NfsqbnOT4ao_OwS3tLvWlzlUyPSnpbcNIVpZ3QkwFK0,49
+tui_input-0.1.0.dist-info/licenses/LICENSE,sha256=rU0e79MlpR2z_i7EfnEx99doSDBVVaOsq41urbcT2gI,1066
+tui_input-0.1.0.dist-info/RECORD,,

tui_input-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tui_input-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tui-input = tui_input.cli:main

tui_input-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maked-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.