tsugite-tmux 0.14.0__tar.gz

tsugite_tmux-0.14.0/.gitignore

@@ -0,0 +1,183 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.env
+.env
+benchmark_results/
+test_output/
+.claude/settings.local.json
+std*.txt
+secrets/*
+
+
+# TODO: temp - I need to clean up the docs
+docs-old/
+examples/*
+!examples/tsugite-example-plugin/
+agents/
+.claude/
+.tsugite/
+benchmarks/
+docker-compose.test.yml
+#### TODO ^^^

tsugite_tmux-0.14.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: tsugite-tmux
+Version: 0.14.0
+Summary: Tsugite plugin: tmux session management tools with automatic output logging
+Requires-Python: >=3.11
+Requires-Dist: tsugite-cli==0.14.0

tsugite_tmux-0.14.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "tsugite-tmux"
+version = "0.14.0"
+description = "Tsugite plugin: tmux session management tools with automatic output logging"
+requires-python = ">=3.11"
+dependencies = ["tsugite-cli==0.14.0"]
+
+[project.entry-points."tsugite.plugins"]
+tmux = "tsugite_tmux"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+tsugite-cli = { workspace = true }

tsugite_tmux-0.14.0/tests/test_tmux_tools.py

@@ -0,0 +1,376 @@
+"""Tests for tmux session management tools."""
+
+import json
+import subprocess
+from unittest.mock import MagicMock, call, patch
+
+import pytest
+
+from tsugite_tmux import (
+    _list_managed_sessions,
+    _strip_ansi,
+    _validate_name,
+    get_tmux_sessions,
+    tmux_create,
+    tmux_kill,
+    tmux_list,
+    tmux_read,
+    tmux_send,
+)
+
+
+@pytest.fixture
+def mock_metadata(tmp_path, monkeypatch):
+    """Redirect metadata and log paths to tmp_path."""
+    meta_dir = tmp_path / "tmux"
+    log_dir = tmp_path / "tmux-logs"
+    meta_dir.mkdir()
+    log_dir.mkdir()
+
+    monkeypatch.setattr("tsugite_tmux._get_metadata_path", lambda: meta_dir / "sessions.json")
+    monkeypatch.setattr("tsugite_tmux._get_log_dir", lambda: log_dir)
+    return tmp_path
+
+
+def _make_run_result(returncode=0, stdout="", stderr=""):
+    result = MagicMock(spec=subprocess.CompletedProcess)
+    result.returncode = returncode
+    result.stdout = stdout
+    result.stderr = stderr
+    return result
+
+
+class TestStripAnsi:
+    def test_strips_sgr_sequences(self):
+        assert _strip_ansi("\x1b[31mred\x1b[0m") == "red"
+
+    def test_strips_bold_and_color(self):
+        assert _strip_ansi("\x1b[1;32mgreen bold\x1b[0m") == "green bold"
+
+    def test_strips_osc_sequences(self):
+        assert _strip_ansi("\x1b]0;title\x07text") == "text"
+
+    def test_strips_charset_designator(self):
+        assert _strip_ansi("\x1b(Btext") == "text"
+
+    def test_passthrough_clean_text(self):
+        assert _strip_ansi("hello world") == "hello world"
+
+    def test_mixed_ansi(self):
+        text = "\x1b[1m\x1b[32mOK\x1b[0m: \x1b[34mtest\x1b[0m passed"
+        assert _strip_ansi(text) == "OK: test passed"
+
+
+class TestValidateName:
+    def test_valid_names(self):
+        for name in ["test", "my-session", "project_1", "A-b_C-3"]:
+            _validate_name(name)
+
+    def test_invalid_names(self):
+        for name in ["has space", "semi;colon", "pipe|char", "slash/path", ""]:
+            with pytest.raises(ValueError, match="Invalid session name"):
+                _validate_name(name)
+
+
+class TestTmuxCreate:
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_create_session(self, mock_run, mock_exists, mock_metadata):
+        mock_run.return_value = _make_run_result()
+
+        result = tmux_create("test")
+
+        assert result["name"] == "test"
+        assert result["tmux_session"] == "tsu-test"
+        assert result["status"] == "created"
+        assert "log_file" in result
+
+        calls = mock_run.call_args_list
+        assert calls[0] == call(
+            ["tmux", "new-session", "-d", "-s", "tsu-test", "-x", "200", "-y", "50"],
+            capture_output=True,
+            text=True,
+        )
+        assert calls[1].args[0][:4] == ["tmux", "pipe-pane", "-t", "tsu-test"]
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_create_with_command(self, mock_run, mock_exists, mock_metadata):
+        mock_run.return_value = _make_run_result()
+
+        tmux_create("test", command="htop")
+
+        new_session_call = mock_run.call_args_list[0]
+        assert "htop" in new_session_call.args[0]
+
+    @patch("tsugite_tmux._session_exists", return_value=True)
+    def test_create_already_exists(self, mock_exists):
+        with pytest.raises(RuntimeError, match="already exists"):
+            tmux_create("test")
+
+    def test_create_invalid_name(self):
+        with pytest.raises(ValueError, match="Invalid session name"):
+            tmux_create("bad name")
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_create_saves_metadata(self, mock_run, mock_exists, mock_metadata):
+        mock_run.return_value = _make_run_result()
+
+        tmux_create("myproject", command="python3")
+
+        meta_path = mock_metadata / "tmux" / "sessions.json"
+        assert meta_path.exists()
+        data = json.loads(meta_path.read_text())
+        assert "myproject" in data
+        assert data["myproject"]["command"] == "python3"
+        assert data["myproject"]["prefixed_name"] == "tsu-myproject"
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_create_cleans_up_on_pipe_failure(self, mock_run, mock_exists, mock_metadata):
+        mock_run.side_effect = [
+            _make_run_result(),  # new-session succeeds
+            _make_run_result(returncode=1, stderr="pipe error"),  # pipe-pane fails
+            _make_run_result(),  # kill-session cleanup
+        ]
+
+        with pytest.raises(RuntimeError, match="Failed to set up logging"):
+            tmux_create("test")
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_create_pipe_pane_uses_shlex_quote(self, mock_run, mock_exists, mock_metadata):
+        mock_run.return_value = _make_run_result()
+
+        tmux_create("test")
+
+        pipe_call = mock_run.call_args_list[1]
+        pipe_arg = pipe_call.args[0][5]  # The -o argument value
+        assert pipe_arg.startswith("cat >> ")
+
+
+class TestTmuxRead:
+    @patch("tsugite_tmux._session_exists", return_value=True)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_read_pane(self, mock_run, mock_exists):
+        mock_run.return_value = _make_run_result(stdout="\x1b[32mhello\x1b[0m world\n")
+
+        result = tmux_read("test", lines=10)
+
+        assert result == "hello world\n"
+        mock_run.assert_called_once_with(
+            ["tmux", "capture-pane", "-t", "tsu-test", "-p", "-S", "-10"],
+            capture_output=True,
+            text=True,
+        )
+
+    def test_read_log(self, mock_metadata):
+        log_dir = mock_metadata / "tmux-logs"
+        log_file = log_dir / "test.log"
+        log_file.write_text("line1\nline2\nline3\n\x1b[31mline4\x1b[0m\n")
+
+        result = tmux_read("test", lines=2, source="log")
+
+        assert result == "line3\nline4\n"
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    def test_read_nonexistent_pane(self, mock_exists):
+        with pytest.raises(RuntimeError, match="not found"):
+            tmux_read("nonexistent")
+
+    def test_read_nonexistent_log(self, mock_metadata):
+        with pytest.raises(RuntimeError, match="No log file"):
+            tmux_read("nonexistent", source="log")
+
+    def test_read_invalid_source(self):
+        with pytest.raises(ValueError, match="Invalid source"):
+            tmux_read("test", source="invalid")
+
+    @patch("tsugite_tmux._session_exists", return_value=True)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_read_clamps_lines(self, mock_run, mock_exists):
+        mock_run.return_value = _make_run_result(stdout="text\n")
+
+        tmux_read("test", lines=99999)
+
+        args = mock_run.call_args.args[0]
+        assert "-5000" in args
+
+
+class TestTmuxSend:
+    @patch("tsugite_tmux._session_exists", return_value=True)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_send_with_enter(self, mock_run, mock_exists):
+        mock_run.return_value = _make_run_result()
+
+        result = tmux_send("test", "ls -la")
+
+        mock_run.assert_called_once_with(
+            ["tmux", "send-keys", "-t", "tsu-test", "ls -la", "Enter"],
+            capture_output=True,
+            text=True,
+        )
+        assert "command" in result
+
+    @patch("tsugite_tmux._session_exists", return_value=True)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_send_without_enter(self, mock_run, mock_exists):
+        mock_run.return_value = _make_run_result()
+
+        result = tmux_send("test", "q", enter=False)
+
+        mock_run.assert_called_once_with(
+            ["tmux", "send-keys", "-t", "tsu-test", "q"],
+            capture_output=True,
+            text=True,
+        )
+        assert "keys" in result
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    def test_send_nonexistent(self, mock_exists):
+        with pytest.raises(RuntimeError, match="not found"):
+            tmux_send("nonexistent", "hello")
+
+
+class TestListManagedSessions:
+    """Tests for the shared _list_managed_sessions helper used by tmux_list and get_tmux_sessions."""
+
+    @patch("tsugite_tmux.subprocess.run")
+    def test_filters_by_prefix(self, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(
+            stdout="tsu-project1\tbash\nuser-session\tvim\ntsu-project2\tpython3\n"
+        )
+
+        meta_path = mock_metadata / "tmux" / "sessions.json"
+        meta_path.write_text(
+            json.dumps(
+                {
+                    "project1": {"command": "htop", "created_at": "2026-01-01T00:00:00", "log_file": "/tmp/p1.log"},
+                    "project2": {"command": None, "created_at": "2026-01-02T00:00:00", "log_file": "/tmp/p2.log"},
+                }
+            )
+        )
+
+        result = _list_managed_sessions()
+
+        assert len(result) == 2
+        names = [s["name"] for s in result]
+        assert "project1" in names
+        assert "project2" in names
+
+    @patch("tsugite_tmux.subprocess.run")
+    def test_idle_status_for_shell(self, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="tsu-test\tbash\n")
+
+        result = _list_managed_sessions()
+
+        assert result[0]["status"] == "idle"
+
+    @patch("tsugite_tmux.subprocess.run")
+    def test_active_status_for_process(self, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="tsu-test\tpython3\n")
+
+        result = _list_managed_sessions()
+
+        assert result[0]["status"] == "active: python3"
+
+    @patch("tsugite_tmux.subprocess.run")
+    def test_no_server(self, mock_run):
+        mock_run.return_value = _make_run_result(returncode=1, stderr="no server running")
+
+        assert _list_managed_sessions() == []
+
+    @patch("tsugite_tmux.subprocess.run")
+    def test_no_managed_sessions(self, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="user-session\tbash\n")
+
+        assert _list_managed_sessions() == []
+
+
+class TestTmuxList:
+    @patch("tsugite_tmux.subprocess.run")
+    def test_list_delegates_to_shared_helper(self, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="tsu-project1\tbash\ntsu-project2\thtop\n")
+
+        result = tmux_list()
+
+        assert len(result) == 2
+        assert result[0]["status"] == "idle"
+        assert result[1]["status"] == "active: htop"
+
+    @patch("tsugite_tmux.subprocess.run")
+    def test_list_no_server(self, mock_run):
+        mock_run.return_value = _make_run_result(returncode=1)
+
+        assert tmux_list() == []
+
+
+class TestTmuxKill:
+    @patch("tsugite_tmux._session_exists", return_value=True)
+    @patch("tsugite_tmux.subprocess.run")
+    def test_kill_session(self, mock_run, mock_exists, mock_metadata):
+        mock_run.return_value = _make_run_result()
+
+        meta_path = mock_metadata / "tmux" / "sessions.json"
+        meta_path.write_text(json.dumps({"test": {"command": "htop"}}))
+
+        result = tmux_kill("test")
+
+        mock_run.assert_called_once_with(
+            ["tmux", "kill-session", "-t", "tsu-test"],
+            capture_output=True,
+            text=True,
+        )
+        assert "terminated" in result
+
+        data = json.loads(meta_path.read_text())
+        assert "test" not in data
+
+    @patch("tsugite_tmux._session_exists", return_value=False)
+    def test_kill_nonexistent(self, mock_exists):
+        with pytest.raises(RuntimeError, match="not found"):
+            tmux_kill("nonexistent")
+
+
+class TestGetTmuxSessions:
+    @patch("tsugite_tmux.shutil.which", return_value=None)
+    def test_no_tmux_installed(self, mock_which):
+        assert get_tmux_sessions() == []
+
+    @patch("tsugite_tmux.subprocess.run")
+    @patch("tsugite_tmux.shutil.which", return_value="/usr/bin/tmux")
+    def test_filters_prefix(self, mock_which, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="tsu-myproject\tbash\nother-session\tvim\n")
+
+        result = get_tmux_sessions()
+
+        assert len(result) == 1
+        assert result[0]["name"] == "myproject"
+        assert "created_at" not in result[0]
+        assert "log_file" not in result[0]
+
+    @patch("tsugite_tmux.subprocess.run")
+    @patch("tsugite_tmux.shutil.which", return_value="/usr/bin/tmux")
+    def test_idle_status(self, mock_which, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="tsu-test\tzsh\n")
+
+        result = get_tmux_sessions()
+
+        assert result[0]["status"] == "idle"
+
+    @patch("tsugite_tmux.subprocess.run")
+    @patch("tsugite_tmux.shutil.which", return_value="/usr/bin/tmux")
+    def test_active_status(self, mock_which, mock_run, mock_metadata):
+        mock_run.return_value = _make_run_result(stdout="tsu-test\thtop\n")
+
+        result = get_tmux_sessions()
+
+        assert result[0]["status"] == "active: htop"
+
+    @patch("tsugite_tmux.subprocess.run")
+    @patch("tsugite_tmux.shutil.which", return_value="/usr/bin/tmux")
+    def test_no_server_running(self, mock_which, mock_run):
+        mock_run.return_value = _make_run_result(returncode=1)
+
+        assert get_tmux_sessions() == []

tsugite_tmux-0.14.0/tsugite_tmux/__init__.py

@@ -0,0 +1,292 @@
+"""Tsugite plugin: tmux session management tools with automatic output logging."""
+
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+from collections import deque
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from tsugite.cli.helpers import get_workspace_dir
+from tsugite.config import get_xdg_data_path
+from tsugite.tools import tool
+
+SESSION_PREFIX = "tsu-"
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]|\x1b\].*?\x07|\x1b\(B")
+SHELLS = {"bash", "zsh", "sh", "fish", "dash", "ksh", "csh", "tcsh"}
+VALID_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+
+def _prefixed(name: str) -> str:
+    return f"{SESSION_PREFIX}{name}"
+
+
+def _strip_ansi(text: str) -> str:
+    return ANSI_RE.sub("", text)
+
+
+def _validate_name(name: str) -> None:
+    if not VALID_NAME_RE.match(name):
+        raise ValueError(f"Invalid session name '{name}': only alphanumeric, hyphens, and underscores allowed")
+
+
+def _session_exists(prefixed_name: str) -> bool:
+    result = subprocess.run(
+        ["tmux", "has-session", "-t", prefixed_name],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+def _get_metadata_path() -> Path:
+    return get_xdg_data_path("tmux") / "sessions.json"
+
+
+def _load_metadata() -> dict:
+    path = _get_metadata_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_metadata(data: dict) -> None:
+    path = _get_metadata_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data, indent=2))
+    os.replace(str(tmp), str(path))
+
+
+def _get_log_dir() -> Path:
+    return get_xdg_data_path("tmux-logs")
+
+
+def _list_managed_sessions() -> list:
+    """Fetch all managed sessions with status in a single batched subprocess call."""
+    result = subprocess.run(
+        ["tmux", "list-panes", "-a", "-F", "#{session_name}\t#{pane_current_command}"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return []
+
+    pane_cmds = {}
+    for line in result.stdout.strip().split("\n"):
+        if not line.strip():
+            continue
+        parts = line.split("\t", 1)
+        session_name = parts[0]
+        if session_name.startswith(SESSION_PREFIX) and session_name not in pane_cmds:
+            pane_cmds[session_name] = parts[1] if len(parts) > 1 else ""
+
+    if not pane_cmds:
+        return []
+
+    metadata = _load_metadata()
+    sessions = []
+    for prefixed, cmd in pane_cmds.items():
+        name = prefixed[len(SESSION_PREFIX) :]
+        status = "idle" if (not cmd or cmd.lower() in SHELLS) else f"active: {cmd}"
+        meta = metadata.get(name, {})
+        sessions.append(
+            {
+                "name": name,
+                "status": status,
+                "created_at": meta.get("created_at", "unknown"),
+                "command": meta.get("command"),
+                "log_file": meta.get("log_file"),
+            }
+        )
+
+    return sessions
+
+
+@tool(category="tmux")
+def tmux_create(name: str, command: Optional[str] = None) -> dict:
+    """Create a named tmux session with automatic output logging.
+
+    Args:
+        name: Session name (alphanumeric, hyphens, underscores)
+        command: Initial command to run in the session (e.g., "htop", "python3")
+
+    Returns:
+        Dict with session name, tmux session name, log file path, and status
+    """
+    _validate_name(name)
+    prefixed = _prefixed(name)
+
+    if _session_exists(prefixed):
+        raise RuntimeError(
+            f"Session '{name}' already exists. Kill it first with tmux_kill('{name}') or use a different name."
+        )
+
+    log_dir = _get_log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / f"{name}.log"
+
+    workspace = get_workspace_dir()
+    cmd = ["tmux", "new-session", "-d", "-s", prefixed, "-x", "200", "-y", "50"]
+    if workspace is not None:
+        cmd.extend(["-c", str(workspace)])
+    if command:
+        cmd.append(command)
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"Failed to create tmux session: {result.stderr.strip()}")
+
+    pipe_result = subprocess.run(
+        ["tmux", "pipe-pane", "-t", prefixed, "-o", f"cat >> {shlex.quote(str(log_file))}"],
+        capture_output=True,
+        text=True,
+    )
+    if pipe_result.returncode != 0:
+        subprocess.run(["tmux", "kill-session", "-t", prefixed], capture_output=True)
+        raise RuntimeError(f"Failed to set up logging: {pipe_result.stderr.strip()}")
+
+    metadata = _load_metadata()
+    metadata[name] = {
+        "prefixed_name": prefixed,
+        "log_file": str(log_file),
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "command": command,
+    }
+    _save_metadata(metadata)
+
+    return {
+        "name": name,
+        "tmux_session": prefixed,
+        "log_file": str(log_file),
+        "status": "created",
+    }
+
+
+@tool(category="tmux")
+def tmux_read(name: str, lines: int = 50, source: str = "pane") -> str:
+    """Read output from a tmux session.
+
+    Args:
+        name: Session name (as given to tmux_create)
+        lines: Number of lines to capture (default: 50, max: 5000)
+        source: "pane" for current visible content, "log" for full pipe-pane log history
+
+    Returns:
+        Session output with ANSI escape codes stripped
+    """
+    _validate_name(name)
+    prefixed = _prefixed(name)
+    lines = max(1, min(lines, 5000))
+
+    if source == "pane":
+        if not _session_exists(prefixed):
+            raise RuntimeError(f"Session '{name}' not found. Use tmux_list() to see active sessions.")
+
+        result = subprocess.run(
+            ["tmux", "capture-pane", "-t", prefixed, "-p", "-S", f"-{lines}"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to capture pane: {result.stderr.strip()}")
+        return _strip_ansi(result.stdout)
+
+    elif source == "log":
+        log_file = _get_log_dir() / f"{name}.log"
+        if not log_file.exists():
+            raise RuntimeError(f"No log file found for session '{name}'.")
+        with open(log_file) as f:
+            tail = deque(f, maxlen=lines)
+        return _strip_ansi("".join(tail))
+
+    else:
+        raise ValueError(f"Invalid source '{source}': must be 'pane' or 'log'")
+
+
+@tool(category="tmux")
+def tmux_send(name: str, keys: str, enter: bool = True) -> str:
+    """Send keystrokes to a tmux session.
+
+    Args:
+        name: Session name (as given to tmux_create)
+        keys: Keys to send (text command or tmux key names like "C-c", "Enter", "q")
+        enter: Whether to send Enter after the keys (default: True). Set False for
+               single-key interactive inputs like "q" to quit, "y" to confirm, etc.
+
+    Returns:
+        Confirmation message
+    """
+    _validate_name(name)
+    prefixed = _prefixed(name)
+
+    if not _session_exists(prefixed):
+        raise RuntimeError(f"Session '{name}' not found. Use tmux_list() to see active sessions.")
+
+    cmd = ["tmux", "send-keys", "-t", prefixed, keys]
+    if enter:
+        cmd.append("Enter")
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"Failed to send keys: {result.stderr.strip()}")
+
+    return f"Sent {'keys' if not enter else 'command'} to session '{name}'"
+
+
+@tool(category="tmux")
+def tmux_list() -> list:
+    """List all tsugite-managed tmux sessions with their current status.
+
+    Returns:
+        List of dicts with name, status, created_at, command, and log_file for each session
+    """
+    return _list_managed_sessions()
+
+
+@tool(category="tmux")
+def tmux_kill(name: str) -> str:
+    """Terminate a tmux session and clean up its metadata.
+
+    Args:
+        name: Session name (as given to tmux_create)
+
+    Returns:
+        Confirmation message
+    """
+    _validate_name(name)
+    prefixed = _prefixed(name)
+
+    if not _session_exists(prefixed):
+        raise RuntimeError(f"Session '{name}' not found. Use tmux_list() to see active sessions.")
+
+    result = subprocess.run(
+        ["tmux", "kill-session", "-t", prefixed],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Failed to kill session: {result.stderr.strip()}")
+
+    metadata = _load_metadata()
+    metadata.pop(name, None)
+    _save_metadata(metadata)
+
+    return f"Session '{name}' terminated. Log file preserved at {_get_log_dir() / f'{name}.log'}"
+
+
+def get_tmux_sessions() -> list:
+    """Active tsugite-managed tmux sessions, for use as a Jinja2 template global.
+
+    Returns a list of dicts with name, status, and command for each session.
+    Returns empty list if tmux is not installed or no managed sessions exist.
+    """
+    if not shutil.which("tmux"):
+        return []
+    return [{"name": s["name"], "status": s["status"], "command": s["command"]} for s in _list_managed_sessions()]