tmuxctl 0.1.1__tar.gz

tmuxctl-0.1.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: tmuxctl
+Version: 0.1.1
+Summary: Small tmux session controller with recurring sends
+Author: Alexey Grigorev
+Project-URL: Homepage, https://github.com/alexeygrigorev/tmuxctl
+Project-URL: Issues, https://github.com/alexeygrigorev/tmuxctl/issues
+Keywords: tmux,cli,scheduler,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1,>=0.12
+
+# tmuxctl
+
+Small tmux session controller with recurring sends.
+
+`tmuxctl` lets you:
+
+- list tmux sessions by name
+- show the most recent sessions by creation time or activity
+- attach to a named session or jump to the most recent ones quickly
+- send a message to a session's active pane
+- store recurring jobs in SQLite
+- run a lightweight daemon loop that executes due jobs
+
+## Install
+
+Install from PyPI with `uv`:
+
+```bash
+uv tool install tmuxctl
+tmuxctl --help
+```
+
+Or with `pip`:
+
+```bash
+pip install tmuxctl
+tmuxctl --help
+```
+
+Install from GitHub with `uv`:
+
+```bash
+uv tool install git+https://github.com/alexeygrigorev/tmuxctl.git
+tmuxctl --help
+```
+
+Install from a local checkout in editable mode:
+
+```bash
+git clone https://github.com/alexeygrigorev/tmuxctl.git
+cd tmuxctl
+uv tool install -e .
+tmuxctl --help
+```
+
+If you update the local checkout later, reinstall with:
+
+```bash
+uv tool install -e . --force
+```
+
+For development, tests, and builds:
+
+```bash
+uv sync --dev
+uv run pytest
+uv build
+```
+
+## Usage
+
+List sessions:
+
+```bash
+tmuxctl list
+tmuxctl recent --limit 10
+tmuxctl recent --limit 10 --by activity
+```
+
+Attach to a session directly or jump to the newest one:
+
+```bash
+tmuxctl attach codex
+tmuxctl create-or-attach codex
+tmuxctl :codex
+tmuxctl attach-last
+tmuxctl attach-last --by activity
+tmuxctl attach-recent 2
+tmuxctl attach-recent 3 --by activity
+```
+
+`tmuxctl :codex` is shorthand for `tmuxctl create-or-attach codex`.
+
+There are also short hidden aliases for the most recent sessions:
+
+```bash
+tmuxctl a1
+tmuxctl a2
+tmuxctl a3
+```
+
+Send one message now:
+
+```bash
+tmuxctl send codex "check status and fix if something is broken or stuck"
+```
+
+Send one message from a file:
+
+```bash
+tmuxctl send rk-codex --message-file prompts/rk-codex-progress.txt
+```
+
+By default, `tmuxctl send` waits `200ms` before pressing Return. Override that with `--enter-delay-ms` or disable Return with `--no-enter`.
+
+Create a recurring job:
+
+```bash
+tmuxctl add codex --every 15m --message "check status and fix if something is broken or stuck"
+```
+
+Recurring jobs also store an Enter delay. By default that is `200ms`, and you can override it with `--enter-delay-ms`.
+
+Example: send an automated follow-up to `rk-codex` every 30 minutes:
+
+```bash
+tmuxctl add rk-codex --every 30m --message-file prompts/rk-codex-progress.txt
+```
+
+You can load message text from a file with `--message-file` for `tmuxctl send`, `tmuxctl add`, and `tmuxctl edit`.
+
+For `tmuxctl add` and `tmuxctl edit`, the file path is stored with the job. Scheduled runs read the file at send time, so updating the prompt file changes future runs without recreating the job.
+
+To switch an existing job to the shared prompt file:
+
+```bash
+tmuxctl jobs
+tmuxctl edit <job_id> --message-file prompts/rk-codex-progress.txt
+```
+
+Example: check a worker session every 30 minutes and unblock stalled progress:
+
+```bash
+tmuxctl add lnewly-57 --every 30m --message "Status check for litehive: report current progress, current task, and the last meaningful change. Check whether progress is stalled, not whether you personally feel stuck. Identify blockers, lack of movement, repeated retries, failing commands, broken states, or missing dependencies. If progress is stalled, choose the best next concrete action to unblock litehive and execute it. Fix any problems you can fix now, then continue the work and summarize what changed."
+```
+
+Edit an existing job:
+
+```bash
+tmuxctl edit 2 --every 45m
+tmuxctl edit 2 --message "check status and continue"
+tmuxctl edit 3 --message-file prompts/rk-codex-progress.txt
+```
+
+Remove a job:
+
+```bash
+tmuxctl remove 3
+```
+
+List jobs and logs:
+
+```bash
+tmuxctl jobs
+tmuxctl logs --limit 20
+```
+
+`tmuxctl jobs` shows whether a job uses inline text or a linked file prompt.
+
+Logs include the target session, whether the send was manual or scheduled, whether Return was sent, the Enter delay used, and any recorded error text.
+
+If a scheduled job fails 3 runs in a row, `tmuxctl daemon` removes it automatically.
+
+Run the scheduler:
+
+```bash
+tmuxctl daemon
+```
+
+## Shortcuts
+
+Useful shortcuts for hopping between recent sessions:
+
+- `tmuxctl attach-last`
+- `tmuxctl attach-recent 2`
+- `tmuxctl attach-recent 3`
+- `tmuxctl a1`
+- `tmuxctl a2`
+- `tmuxctl a3`
+
+## How Scheduling Works
+
+`tmuxctl` does not create cron entries and it does not require editing `crontab`.
+
+Recurring jobs are stored in SQLite at:
+
+```text
+~/.config/tmuxctl/tmuxctl.db
+```
+
+The commands work like this:
+
+- `tmuxctl add ...` inserts a recurring job into the database
+- `tmuxctl edit`, `pause`, `resume`, and `remove` update that stored job
+- `tmuxctl daemon` polls the database for due jobs and runs them
+
+That means recurring sends only happen while the daemon is running.
+
+If you want jobs to keep running after logout or reboot, use an external process manager to keep the daemon alive, for example:
+
+- `systemd --user` on Linux
+- `launchd` on macOS
+- `cron @reboot` as a fallback
+
+Even in those setups, cron or systemd only starts `tmuxctl daemon`. The recurring schedule itself still lives in the `tmuxctl` database.
+
+## Bash Completion
+
+`tmuxctl` includes shell completion through Typer.
+
+Install completion for your current Bash setup:
+
+```bash
+tmuxctl --install-completion
+```
+
+Preview or manually wire the Bash completion script:
+
+```bash
+tmuxctl --show-completion bash
+```
+
+Session-taking commands also complete existing tmux session names in Bash.

tmuxctl-0.1.1/README.md

@@ -0,0 +1,223 @@
+# tmuxctl
+
+Small tmux session controller with recurring sends.
+
+`tmuxctl` lets you:
+
+- list tmux sessions by name
+- show the most recent sessions by creation time or activity
+- attach to a named session or jump to the most recent ones quickly
+- send a message to a session's active pane
+- store recurring jobs in SQLite
+- run a lightweight daemon loop that executes due jobs
+
+## Install
+
+Install from PyPI with `uv`:
+
+```bash
+uv tool install tmuxctl
+tmuxctl --help
+```
+
+Or with `pip`:
+
+```bash
+pip install tmuxctl
+tmuxctl --help
+```
+
+Install from GitHub with `uv`:
+
+```bash
+uv tool install git+https://github.com/alexeygrigorev/tmuxctl.git
+tmuxctl --help
+```
+
+Install from a local checkout in editable mode:
+
+```bash
+git clone https://github.com/alexeygrigorev/tmuxctl.git
+cd tmuxctl
+uv tool install -e .
+tmuxctl --help
+```
+
+If you update the local checkout later, reinstall with:
+
+```bash
+uv tool install -e . --force
+```
+
+For development, tests, and builds:
+
+```bash
+uv sync --dev
+uv run pytest
+uv build
+```
+
+## Usage
+
+List sessions:
+
+```bash
+tmuxctl list
+tmuxctl recent --limit 10
+tmuxctl recent --limit 10 --by activity
+```
+
+Attach to a session directly or jump to the newest one:
+
+```bash
+tmuxctl attach codex
+tmuxctl create-or-attach codex
+tmuxctl :codex
+tmuxctl attach-last
+tmuxctl attach-last --by activity
+tmuxctl attach-recent 2
+tmuxctl attach-recent 3 --by activity
+```
+
+`tmuxctl :codex` is shorthand for `tmuxctl create-or-attach codex`.
+
+There are also short hidden aliases for the most recent sessions:
+
+```bash
+tmuxctl a1
+tmuxctl a2
+tmuxctl a3
+```
+
+Send one message now:
+
+```bash
+tmuxctl send codex "check status and fix if something is broken or stuck"
+```
+
+Send one message from a file:
+
+```bash
+tmuxctl send rk-codex --message-file prompts/rk-codex-progress.txt
+```
+
+By default, `tmuxctl send` waits `200ms` before pressing Return. Override that with `--enter-delay-ms` or disable Return with `--no-enter`.
+
+Create a recurring job:
+
+```bash
+tmuxctl add codex --every 15m --message "check status and fix if something is broken or stuck"
+```
+
+Recurring jobs also store an Enter delay. By default that is `200ms`, and you can override it with `--enter-delay-ms`.
+
+Example: send an automated follow-up to `rk-codex` every 30 minutes:
+
+```bash
+tmuxctl add rk-codex --every 30m --message-file prompts/rk-codex-progress.txt
+```
+
+You can load message text from a file with `--message-file` for `tmuxctl send`, `tmuxctl add`, and `tmuxctl edit`.
+
+For `tmuxctl add` and `tmuxctl edit`, the file path is stored with the job. Scheduled runs read the file at send time, so updating the prompt file changes future runs without recreating the job.
+
+To switch an existing job to the shared prompt file:
+
+```bash
+tmuxctl jobs
+tmuxctl edit <job_id> --message-file prompts/rk-codex-progress.txt
+```
+
+Example: check a worker session every 30 minutes and unblock stalled progress:
+
+```bash
+tmuxctl add lnewly-57 --every 30m --message "Status check for litehive: report current progress, current task, and the last meaningful change. Check whether progress is stalled, not whether you personally feel stuck. Identify blockers, lack of movement, repeated retries, failing commands, broken states, or missing dependencies. If progress is stalled, choose the best next concrete action to unblock litehive and execute it. Fix any problems you can fix now, then continue the work and summarize what changed."
+```
+
+Edit an existing job:
+
+```bash
+tmuxctl edit 2 --every 45m
+tmuxctl edit 2 --message "check status and continue"
+tmuxctl edit 3 --message-file prompts/rk-codex-progress.txt
+```
+
+Remove a job:
+
+```bash
+tmuxctl remove 3
+```
+
+List jobs and logs:
+
+```bash
+tmuxctl jobs
+tmuxctl logs --limit 20
+```
+
+`tmuxctl jobs` shows whether a job uses inline text or a linked file prompt.
+
+Logs include the target session, whether the send was manual or scheduled, whether Return was sent, the Enter delay used, and any recorded error text.
+
+If a scheduled job fails 3 runs in a row, `tmuxctl daemon` removes it automatically.
+
+Run the scheduler:
+
+```bash
+tmuxctl daemon
+```
+
+## Shortcuts
+
+Useful shortcuts for hopping between recent sessions:
+
+- `tmuxctl attach-last`
+- `tmuxctl attach-recent 2`
+- `tmuxctl attach-recent 3`
+- `tmuxctl a1`
+- `tmuxctl a2`
+- `tmuxctl a3`
+
+## How Scheduling Works
+
+`tmuxctl` does not create cron entries and it does not require editing `crontab`.
+
+Recurring jobs are stored in SQLite at:
+
+```text
+~/.config/tmuxctl/tmuxctl.db
+```
+
+The commands work like this:
+
+- `tmuxctl add ...` inserts a recurring job into the database
+- `tmuxctl edit`, `pause`, `resume`, and `remove` update that stored job
+- `tmuxctl daemon` polls the database for due jobs and runs them
+
+That means recurring sends only happen while the daemon is running.
+
+If you want jobs to keep running after logout or reboot, use an external process manager to keep the daemon alive, for example:
+
+- `systemd --user` on Linux
+- `launchd` on macOS
+- `cron @reboot` as a fallback
+
+Even in those setups, cron or systemd only starts `tmuxctl daemon`. The recurring schedule itself still lives in the `tmuxctl` database.
+
+## Bash Completion
+
+`tmuxctl` includes shell completion through Typer.
+
+Install completion for your current Bash setup:
+
+```bash
+tmuxctl --install-completion
+```
+
+Preview or manually wire the Bash completion script:
+
+```bash
+tmuxctl --show-completion bash
+```
+
+Session-taking commands also complete existing tmux session names in Bash.

tmuxctl-0.1.1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "tmuxctl"
+version = "0.1.1"
+description = "Small tmux session controller with recurring sends"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Alexey Grigorev" },
+]
+keywords = ["tmux", "cli", "scheduler", "automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Shells",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "typer>=0.12,<1",
+]
+
+[project.scripts]
+tmuxctl = "tmuxctl.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/alexeygrigorev/tmuxctl"
+Issues = "https://github.com/alexeygrigorev/tmuxctl/issues"
+
+[dependency-groups]
+dev = [
+  "hatch>=1,<2",
+  "pytest>=8,<9",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+include = ["tmuxctl*"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

tmuxctl-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tmuxctl-0.1.1/tests/test_cli.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from tmuxctl import cli
+from tmuxctl.cli import app
+from tmuxctl.models import Job
+
+
+runner = CliRunner()
+
+
+def test_send_reads_message_from_file(monkeypatch, tmp_path: Path) -> None:
+    message_file = tmp_path / "message.txt"
+    message_file.write_text("line 1\nline 2\n", encoding="utf-8")
+    captured: dict[str, object] = {}
+
+    monkeypatch.setattr("tmuxctl.cli._conn", lambda: object())
+    monkeypatch.setattr("tmuxctl.cli.tmux_api.session_exists", lambda session_name: True)
+
+    def fake_send_keys(session_name: str, message: str, press_enter: bool, enter_delay_ms: int) -> None:
+        captured["session_name"] = session_name
+        captured["message"] = message
+        captured["press_enter"] = press_enter
+        captured["enter_delay_ms"] = enter_delay_ms
+
+    monkeypatch.setattr("tmuxctl.cli.tmux_api.send_keys", fake_send_keys)
+    monkeypatch.setattr("tmuxctl.cli.storage.insert_log", lambda *args, **kwargs: None)
+
+    result = runner.invoke(app, ["send", "rk-codex", "--message-file", str(message_file)])
+
+    assert result.exit_code == 0
+    assert captured["session_name"] == "rk-codex"
+    assert captured["message"] == "line 1\nline 2"
+    assert captured["press_enter"] is True
+    assert captured["enter_delay_ms"] == 200
+
+
+def test_add_rejects_both_message_and_message_file(monkeypatch, tmp_path: Path) -> None:
+    message_file = tmp_path / "message.txt"
+    message_file.write_text("hello", encoding="utf-8")
+
+    monkeypatch.setattr("tmuxctl.cli.tmux_api.session_exists", lambda session_name: True)
+
+    result = runner.invoke(
+        app,
+        [
+            "add",
+            "rk-codex",
+            "--every",
+            "30m",
+            "--message",
+            "hello",
+            "--message-file",
+            str(message_file),
+        ],
+    )
+
+    assert result.exit_code == 1
+    assert "choose either --message or --message-file, not both" in result.output
+
+
+def test_add_stores_message_file_path(monkeypatch, tmp_path: Path) -> None:
+    message_file = tmp_path / "message.txt"
+    message_file.write_text("hello from file\n", encoding="utf-8")
+    captured: dict[str, object] = {}
+
+    monkeypatch.setattr("tmuxctl.cli.tmux_api.session_exists", lambda session_name: True)
+    monkeypatch.setattr("tmuxctl.cli._conn", lambda: object())
+    monkeypatch.setattr("tmuxctl.cli.parse_interval", lambda value: 1800)
+
+    class DummyJob:
+        id = 7
+        session_name = "rk-codex"
+        interval_seconds = 1800
+
+    def fake_create_job(conn, **kwargs):
+        captured.update(kwargs)
+        return DummyJob()
+
+    monkeypatch.setattr("tmuxctl.cli.storage.create_job", fake_create_job)
+
+    result = runner.invoke(
+        app,
+        ["add", "rk-codex", "--every", "30m", "--message-file", str(message_file)],
+    )
+
+    assert result.exit_code == 0
+    assert captured["message"] == "hello from file"
+    assert captured["message_file_path"] == str(message_file)
+
+
+def test_jobs_shows_inline_and_file_sources(monkeypatch) -> None:
+    monkeypatch.setattr("tmuxctl.cli._conn", lambda: object())
+    monkeypatch.setattr(
+        "tmuxctl.cli.storage.list_jobs",
+        lambda conn: [
+            Job(
+                id=1,
+                session_name="inline",
+                message="short inline prompt",
+                message_file_path=None,
+                interval_seconds=900,
+                enabled=True,
+                send_enter=True,
+                enter_delay_ms=200,
+                created_at="2026-04-03T00:00:00+00:00",
+                updated_at="2026-04-03T00:00:00+00:00",
+                last_run_at=None,
+                next_run_at="2026-04-03T00:15:00+00:00",
+            ),
+            Job(
+                id=2,
+                session_name="linked",
+                message="stored snapshot",
+                message_file_path="prompts/rk-codex-progress.txt",
+                interval_seconds=1800,
+                enabled=True,
+                send_enter=True,
+                enter_delay_ms=200,
+                created_at="2026-04-03T00:00:00+00:00",
+                updated_at="2026-04-03T00:00:00+00:00",
+                last_run_at=None,
+                next_run_at="2026-04-03T00:30:00+00:00",
+            ),
+        ],
+    )
+
+    result = runner.invoke(app, ["jobs"])
+
+    assert result.exit_code == 0
+    assert "SOURCE" in result.output
+    assert "inline" in result.output
+    assert "file" in result.output
+    assert "short inline prompt" in result.output
+    assert "prompts/rk-codex-progress.txt" in result.output
+
+
+def test_complete_session_names_filters_matches(monkeypatch) -> None:
+    monkeypatch.setattr("tmuxctl.cli.tmux_api.list_sessions", lambda: ["rk-codex", "rk-worker", "other"])
+
+    assert cli._complete_session_names("rk-") == ["rk-codex", "rk-worker"]
+
+
+def test_main_rewrites_colon_shortcut(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_app(*, args):
+        captured["args"] = args
+
+    monkeypatch.setattr(cli, "app", fake_app)
+    monkeypatch.setattr(sys, "argv", ["tmuxctl", ":rk-codex"])
+
+    cli.main()
+
+    assert captured["args"] == ["create-or-attach", "rk-codex"]