gdamms-tuimux 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Damien Guillotin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,53 @@
1
+ Metadata-Version: 2.4
2
+ Name: gdamms-tuimux
3
+ Version: 0.2.0
4
+ Summary: A lazydocker-like terminal UI to manage tmux sessions.
5
+ Author: gdamms
6
+ Author-email: gdamms <damguillotin@gmail.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Requires-Dist: gdamms-pytui>=0.2.0
10
+ Requires-Python: >=3.11
11
+ Description-Content-Type: text/markdown
12
+
13
+ # tuimux
14
+
15
+ A terminal UI to manage tmux sessions, in the spirit of lazydocker: your sessions on the
16
+ left, a live preview of the selected one on the right. Built with
17
+ [pytui](https://github.com/gdamms/pytui).
18
+
19
+ ## Features
20
+
21
+ - list sessions, with a live preview of each session's active pane
22
+ - create a session (named, or named after its id)
23
+ - rename a session
24
+ - delete a session (asks for confirmation)
25
+ - attach to a session (switches client when already inside tmux), back to tuimux on detach
26
+ - keyboard and mouse
27
+
28
+ ## Installation
29
+
30
+ ```sh
31
+ uv tool install gdamms-tuimux
32
+ ```
33
+
34
+ ## Usage
35
+
36
+ ```sh
37
+ tuimux
38
+ ```
39
+
40
+ Controls:
41
+ | Key | Action |
42
+ | --- | --- |
43
+ | `↑` / `↓` | select a session |
44
+ | `enter` / `a` | attach |
45
+ | `n` | new session |
46
+ | `r` | rename session |
47
+ | `d` | delete session |
48
+ | `q` / `esc` | quit (or close a dialog) |
49
+
50
+ ## TODO
51
+
52
+ - copy a session's environment
53
+ - session stats (cpu, mem, etc)
@@ -0,0 +1,41 @@
1
+ # tuimux
2
+
3
+ A terminal UI to manage tmux sessions, in the spirit of lazydocker: your sessions on the
4
+ left, a live preview of the selected one on the right. Built with
5
+ [pytui](https://github.com/gdamms/pytui).
6
+
7
+ ## Features
8
+
9
+ - list sessions, with a live preview of each session's active pane
10
+ - create a session (named, or named after its id)
11
+ - rename a session
12
+ - delete a session (asks for confirmation)
13
+ - attach to a session (switches client when already inside tmux), back to tuimux on detach
14
+ - keyboard and mouse
15
+
16
+ ## Installation
17
+
18
+ ```sh
19
+ uv tool install gdamms-tuimux
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ```sh
25
+ tuimux
26
+ ```
27
+
28
+ Controls:
29
+ | Key | Action |
30
+ | --- | --- |
31
+ | `↑` / `↓` | select a session |
32
+ | `enter` / `a` | attach |
33
+ | `n` | new session |
34
+ | `r` | rename session |
35
+ | `d` | delete session |
36
+ | `q` / `esc` | quit (or close a dialog) |
37
+
38
+ ## TODO
39
+
40
+ - copy a session's environment
41
+ - session stats (cpu, mem, etc)
@@ -0,0 +1,40 @@
1
+ [project]
2
+ name = "gdamms-tuimux"
3
+ version = "0.2.0"
4
+ description = "A lazydocker-like terminal UI to manage tmux sessions."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.11"
9
+ dependencies = ["gdamms-pytui>=0.2.0"]
10
+
11
+ [[project.authors]]
12
+ name = "gdamms"
13
+ email = "damguillotin@gmail.com"
14
+
15
+ [project.scripts]
16
+ tuimux = "tuimux.app:main"
17
+
18
+ [tool.uv.build-backend]
19
+ module-name = "tuimux"
20
+
21
+ [tool.ruff]
22
+ line-length = 100
23
+ target-version = "py311"
24
+
25
+ [tool.ruff.lint]
26
+ select = [
27
+ "E",
28
+ "F",
29
+ "W",
30
+ "I",
31
+ "B",
32
+ "UP",
33
+ ]
34
+
35
+ [build-system]
36
+ requires = ["uv_build>=0.13.3,<0.14.0"]
37
+ build-backend = "uv_build"
38
+
39
+ [dependency-groups]
40
+ dev = ["ruff>=0.6"]
@@ -0,0 +1,32 @@
1
+ [project]
2
+ name = "gdamms-tuimux"
3
+ version = "0.2.0"
4
+ description = "A lazydocker-like terminal UI to manage tmux sessions."
5
+ readme = "README.md"
6
+ authors = [{ name = "gdamms", email = "damguillotin@gmail.com" }]
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ requires-python = ">=3.11"
10
+ dependencies = [
11
+ "gdamms-pytui>=0.2.0",
12
+ ]
13
+
14
+ [project.scripts]
15
+ tuimux = "tuimux.app:main"
16
+
17
+ [tool.uv.build-backend]
18
+ module-name = "tuimux"
19
+
20
+ [build-system]
21
+ requires = ["uv_build>=0.13.3,<0.14.0"]
22
+ build-backend = "uv_build"
23
+
24
+ [dependency-groups]
25
+ dev = ["ruff>=0.6"]
26
+
27
+ [tool.ruff]
28
+ line-length = 100
29
+ target-version = "py311"
30
+
31
+ [tool.ruff.lint]
32
+ select = ["E", "F", "W", "I", "B", "UP"]
@@ -0,0 +1,5 @@
1
+ """tuimux: a lazydocker-like terminal UI to manage tmux sessions."""
2
+
3
+ from .app import TuiMux, main
4
+
5
+ __all__ = ["TuiMux", "main"]
@@ -0,0 +1,3 @@
1
+ from .app import main
2
+
3
+ main()
@@ -0,0 +1,148 @@
1
+ """The tuimux application: a session list next to a live preview of the selected session."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pytui import App, Box, ListView, Row, Style, Text, Widget
6
+ from pytui.text import truncate
7
+
8
+ from . import tmux
9
+ from .dialogs import Confirm, Modal, Prompt
10
+ from .tmux import Session
11
+
12
+ REFRESH_INTERVAL = 0.5
13
+ PANEL = Style(border="rounded", border_fg="bright_black", focus_within=Style(border_fg="cyan"))
14
+ HELP = "↑/↓ select · enter/a attach · n new · r rename · d delete · q quit"
15
+
16
+
17
+ class Preview(Widget):
18
+ """The bottom of a list of lines, like a terminal screen."""
19
+
20
+ DEFAULT_STYLE = Style(flex_grow=1)
21
+
22
+ def __init__(self, **kwargs) -> None:
23
+ super().__init__(**kwargs)
24
+ self.lines: list[str] = []
25
+
26
+ def render(self, canvas) -> None:
27
+ area = self.content_region
28
+ if area.empty:
29
+ return
30
+ for row, line in enumerate(self.lines[-area.height :]):
31
+ canvas.text(area.x, area.y + row, truncate(line, area.width), self.text_style)
32
+
33
+
34
+ class TuiMux:
35
+ def __init__(self) -> None:
36
+ self.sessions: list[Session] = []
37
+ self.list = ListView(on_highlight=lambda *_: self.refresh_preview(), flex_grow=1)
38
+ self.preview = Preview()
39
+ self.preview_panel = Box(self.preview, style=PANEL, flex_grow=1)
40
+ self.root = Box(
41
+ Row(
42
+ Box(self.list, style=PANEL, title="Sessions", width="30%", min_width=20),
43
+ self.preview_panel,
44
+ flex_grow=1,
45
+ ),
46
+ Text(HELP, dim=True, text_wrap=False, padding=(0, 1)),
47
+ )
48
+
49
+ self.app = App(self.root)
50
+ self.list.bind("enter", self.attach)
51
+ bindings = {"q escape": self.app.exit, "a": self.attach, "n": self.new}
52
+ bindings |= {"r": self.rename, "d": self.delete}
53
+ for keys, action in bindings.items():
54
+ self.app.bind(keys, action)
55
+ self.app.set_interval(REFRESH_INTERVAL, self.refresh)
56
+
57
+ @property
58
+ def selected(self) -> Session | None:
59
+ return None if self.list.index is None else self.sessions[self.list.index]
60
+
61
+ # --- refresh ------------------------------------------------------------
62
+
63
+ def refresh(self, select: str | None = None) -> None:
64
+ """Reload the sessions, keeping the selection (or selecting the ``select`` id)."""
65
+ current = select or (self.selected and self.selected.id)
66
+ self.sessions = tmux.sessions()
67
+ self.list.items = [s.label for s in self.sessions]
68
+ ids = [s.id for s in self.sessions]
69
+ if current in ids:
70
+ self.list.index = ids.index(current)
71
+ self.refresh_preview()
72
+
73
+ def refresh_preview(self) -> None:
74
+ session = self.selected
75
+ if session is None:
76
+ self.preview_panel.title = "Preview"
77
+ self.preview.lines = ["No sessions, press n to create one."]
78
+ else:
79
+ windows = f"{session.windows} window" + "s" * (session.windows > 1)
80
+ self.preview_panel.title = f"{session.name} ({windows})"
81
+ self.preview.lines = session.capture()
82
+
83
+ # --- actions ------------------------------------------------------------
84
+
85
+ def show(self, modal: Modal) -> None:
86
+ def close() -> None:
87
+ self.list.focus()
88
+ self.refresh()
89
+
90
+ modal.on_close = close
91
+ modal.open(self.root)
92
+
93
+ def name_error(self, name: str, renamed: Session | None = None) -> str | None:
94
+ if any(s.name == name and s != renamed for s in self.sessions):
95
+ return f"a session is already named {name!r}"
96
+ return None
97
+
98
+ def new(self) -> None:
99
+ self.show(
100
+ Prompt(
101
+ "New session",
102
+ lambda name: self.refresh(select=tmux.new_session(name)),
103
+ placeholder="leave empty to use the id",
104
+ validate=self.name_error,
105
+ )
106
+ )
107
+
108
+ def rename(self) -> None:
109
+ if (session := self.selected) is None:
110
+ return
111
+ self.show(
112
+ Prompt(
113
+ f"Rename {session.name}",
114
+ session.rename,
115
+ value=session.name,
116
+ validate=lambda name: (
117
+ self.name_error(name, session) or (None if name else "the name cannot be empty")
118
+ ),
119
+ )
120
+ )
121
+
122
+ def delete(self) -> None:
123
+ if (session := self.selected) is None:
124
+ return
125
+ self.show(
126
+ Confirm(
127
+ "Delete session",
128
+ f"Delete session {session.name!r} (id {session.id[1:]})?",
129
+ session.kill,
130
+ )
131
+ )
132
+
133
+ def attach(self) -> None:
134
+ if self.selected is not None:
135
+ self.app.exit(self.selected)
136
+
137
+ # --- running ------------------------------------------------------------
138
+
139
+ def run(self) -> None:
140
+ """Run until quit; attaching leaves the UI and comes back on detach."""
141
+ self.refresh()
142
+ while (session := self.app.run()) is not None:
143
+ session.attach()
144
+ self.refresh()
145
+
146
+
147
+ def main() -> None:
148
+ TuiMux().run()
@@ -0,0 +1,130 @@
1
+ """Modal dialogs drawn over the main screen."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable
6
+ from typing import Any
7
+
8
+ from pytui import Box, Button, Input, KeyEvent, Row, Style, Text, Widget
9
+
10
+ from .tmux import TmuxError
11
+
12
+ DIALOG = Style(
13
+ border="rounded",
14
+ border_fg="cyan",
15
+ bg="default",
16
+ padding=(0, 1),
17
+ gap=1,
18
+ width=50,
19
+ max_width="90%",
20
+ )
21
+ HINT = Style(dim=True, text_align="center")
22
+ INVALID = Style(fg="red", focus=Style(fg="red"))
23
+
24
+
25
+ class Modal(Box):
26
+ """A full-screen overlay holding a centered dialog.
27
+
28
+ Covering the screen keeps mouse clicks from reaching the widgets below, and
29
+ handling every key keeps them away from the app bindings.
30
+ """
31
+
32
+ DEFAULT_STYLE = Style(
33
+ position="absolute",
34
+ top=0,
35
+ right=0,
36
+ bottom=0,
37
+ left=0,
38
+ align_items="center",
39
+ justify_content="center",
40
+ )
41
+
42
+ def __init__(
43
+ self, *children: Widget, title: str, hint: str, focus: Widget | None = None
44
+ ) -> None:
45
+ self.error = Text("", fg="red", display="none")
46
+ super().__init__(
47
+ Box(*children, self.error, Text(hint, style=HINT), style=DIALOG, title=title)
48
+ )
49
+ self.initial_focus = focus
50
+ self.on_close: Callable[[], Any] = lambda: None
51
+ self.bind("escape", self.close)
52
+
53
+ def open(self, parent: Widget) -> None:
54
+ parent.mount(self)
55
+ (self.initial_focus or self._focusables()[0]).focus()
56
+
57
+ def close(self) -> None:
58
+ self.remove()
59
+ self.on_close()
60
+
61
+ def show_error(self, message: str | None) -> None:
62
+ self.error.text = message or ""
63
+ self.error.hidden = not message
64
+
65
+ def submit(self, action: Callable[[], Any]) -> None:
66
+ """Run ``action`` and close, or keep the dialog open to show a tmux error."""
67
+ try:
68
+ action()
69
+ except TmuxError as error:
70
+ self.show_error(str(error))
71
+ else:
72
+ self.close()
73
+
74
+ def _focusables(self) -> list[Widget]:
75
+ return [w for w in self.walk() if w.focusable]
76
+
77
+ def on_key(self, event: KeyEvent) -> bool:
78
+ steps = {"tab": 1, "right": 1, "shift+tab": -1, "left": -1}
79
+ if event.key in steps and self.app is not None:
80
+ widgets = self._focusables()
81
+ current = widgets.index(self.app.focused) if self.app.focused in widgets else 0
82
+ widgets[(current + steps[event.key]) % len(widgets)].focus()
83
+ return True
84
+
85
+
86
+ class Prompt(Modal):
87
+ """Ask for a line of text. ``validate(value)`` returns an error message or None."""
88
+
89
+ def __init__(
90
+ self,
91
+ title: str,
92
+ on_submit: Callable[[str], Any],
93
+ *,
94
+ value: str = "",
95
+ placeholder: str = "",
96
+ validate: Callable[[str], str | None] = lambda _: None,
97
+ ) -> None:
98
+ self.validate = validate
99
+ self.on_submit = on_submit
100
+ self.input = Input(
101
+ value, placeholder=placeholder, on_change=self._check, on_submit=self._submit
102
+ )
103
+ super().__init__(self.input, title=title, hint="enter: confirm · esc: cancel")
104
+
105
+ def _check(self, value: str) -> str | None:
106
+ error = self.validate(value)
107
+ self.show_error(error)
108
+ self.input.style = INVALID if error else Style()
109
+ return error
110
+
111
+ def _submit(self, value: str) -> None:
112
+ if self._check(value) is None:
113
+ self.submit(lambda: self.on_submit(value))
114
+
115
+
116
+ class Confirm(Modal):
117
+ """Ask a yes/no question; "No" is focused by default."""
118
+
119
+ def __init__(self, title: str, message: str, on_yes: Callable[[], Any]) -> None:
120
+ yes = Button("Yes", on_press=lambda: self.submit(on_yes))
121
+ no = Button("No", on_press=self.close)
122
+ super().__init__(
123
+ Text(message),
124
+ Row(yes, no, gap=2, justify_content="center", align_self="stretch"),
125
+ title=title,
126
+ hint="y: yes · n/esc: no",
127
+ focus=no,
128
+ )
129
+ self.bind("y", yes.press)
130
+ self.bind("n", self.close)
@@ -0,0 +1,69 @@
1
+ """A thin wrapper around the tmux command line."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import subprocess
7
+ from dataclasses import dataclass
8
+
9
+ _FIELDS = ("session_id", "session_name", "session_windows", "session_attached")
10
+ _SEP = "\x1f"
11
+
12
+
13
+ class TmuxError(RuntimeError):
14
+ pass
15
+
16
+
17
+ def tmux(*args: str, check: bool = True) -> str:
18
+ result = subprocess.run(["tmux", *args], capture_output=True, text=True)
19
+ if check and result.returncode != 0:
20
+ raise TmuxError(result.stderr.strip() or f"tmux {args[0]} failed")
21
+ return result.stdout
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Session:
26
+ id: str
27
+ name: str
28
+ windows: int
29
+ attached: bool
30
+
31
+ @property
32
+ def label(self) -> str:
33
+ return f"{self.id[1:]}: {self.name}" + (" *" if self.attached else "")
34
+
35
+ def capture(self) -> list[str]:
36
+ """Visible content of the session's active pane, without trailing blank lines."""
37
+ lines = tmux("capture-pane", "-p", "-t", self.id, check=False).splitlines()
38
+ while lines and not lines[-1].strip():
39
+ lines.pop()
40
+ return lines
41
+
42
+ def rename(self, name: str) -> None:
43
+ tmux("rename-session", "-t", self.id, name)
44
+
45
+ def kill(self) -> None:
46
+ tmux("kill-session", "-t", self.id)
47
+
48
+ def attach(self) -> None:
49
+ """Attach the terminal to the session, or switch to it when already inside tmux."""
50
+ command = "switch-client" if os.environ.get("TMUX") else "attach-session"
51
+ subprocess.run(["tmux", command, "-t", self.id])
52
+
53
+
54
+ def sessions() -> list[Session]:
55
+ # Fails when no server is running, which just means there are no sessions.
56
+ output = tmux("list-sessions", "-F", _SEP.join(f"#{{{f}}}" for f in _FIELDS), check=False)
57
+ found = []
58
+ for line in output.splitlines():
59
+ id, name, windows, attached = line.split(_SEP)
60
+ found.append(Session(id, name, int(windows), attached != "0"))
61
+ return sorted(found, key=lambda s: int(s.id[1:]))
62
+
63
+
64
+ def new_session(name: str = "") -> str:
65
+ """Create a detached session and return its id."""
66
+ args = ["new-session", "-d", "-P", "-F", "#{session_id}"]
67
+ if name:
68
+ args += ["-s", name]
69
+ return tmux(*args).strip()