sebside-tmux 0.1.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.
Files changed (35) hide show
  1. sebside_tmux-0.1.0/.gitignore +11 -0
  2. sebside_tmux-0.1.0/CHANGELOG.md +22 -0
  3. sebside_tmux-0.1.0/LICENSE +21 -0
  4. sebside_tmux-0.1.0/PKG-INFO +262 -0
  5. sebside_tmux-0.1.0/README.md +237 -0
  6. sebside_tmux-0.1.0/pyproject.toml +73 -0
  7. sebside_tmux-0.1.0/scripts/demo.sh +48 -0
  8. sebside_tmux-0.1.0/scripts/screenshot.py +133 -0
  9. sebside_tmux-0.1.0/scripts/toggle.sh +41 -0
  10. sebside_tmux-0.1.0/sebside.tmux +76 -0
  11. sebside_tmux-0.1.0/src/sebside/__init__.py +8 -0
  12. sebside_tmux-0.1.0/src/sebside/__main__.py +3 -0
  13. sebside_tmux-0.1.0/src/sebside/cards.py +257 -0
  14. sebside_tmux-0.1.0/src/sebside/cli.py +361 -0
  15. sebside_tmux-0.1.0/src/sebside/config.py +214 -0
  16. sebside_tmux-0.1.0/src/sebside/errors.py +39 -0
  17. sebside_tmux-0.1.0/src/sebside/log.py +35 -0
  18. sebside_tmux-0.1.0/src/sebside/model.py +132 -0
  19. sebside_tmux-0.1.0/src/sebside/py.typed +0 -0
  20. sebside_tmux-0.1.0/src/sebside/render.py +390 -0
  21. sebside_tmux-0.1.0/src/sebside/store.py +343 -0
  22. sebside_tmux-0.1.0/src/sebside/tmux.py +312 -0
  23. sebside_tmux-0.1.0/src/sebside/tui.py +346 -0
  24. sebside_tmux-0.1.0/tests/conftest.py +24 -0
  25. sebside_tmux-0.1.0/tests/fakes.py +127 -0
  26. sebside_tmux-0.1.0/tests/integration/test_real_tmux.py +231 -0
  27. sebside_tmux-0.1.0/tests/unit/test_cards.py +163 -0
  28. sebside_tmux-0.1.0/tests/unit/test_cli.py +184 -0
  29. sebside_tmux-0.1.0/tests/unit/test_config.py +97 -0
  30. sebside_tmux-0.1.0/tests/unit/test_plugin_script.py +36 -0
  31. sebside_tmux-0.1.0/tests/unit/test_render.py +143 -0
  32. sebside_tmux-0.1.0/tests/unit/test_review_fixes.py +268 -0
  33. sebside_tmux-0.1.0/tests/unit/test_store.py +136 -0
  34. sebside_tmux-0.1.0/tests/unit/test_tmux.py +190 -0
  35. sebside_tmux-0.1.0/tests/unit/test_tui.py +166 -0
@@ -0,0 +1,11 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ build/
8
+ *.egg-info/
9
+ .coverage
10
+ .DS_Store
11
+ .mypy_cache/
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-11-18
10
+
11
+ ### Added
12
+
13
+ - Sidebar TUI (`sebside`): three-line cards with a colored bar, state icons and an animated spinner, cards that
14
+ need you on top, a counter and key hints at the bottom, recently closed cards greyed at the bottom.
15
+ - Keyboard navigation: `↑`/`↓`/`j`/`k`, `Enter` to switch to a session, `?` to explain a card's state, `q` to quit.
16
+ - Card contract: one JSON file per card in `$XDG_STATE_HOME/sebside/cards/`, plus `@sebside_id` and
17
+ `@sebside_state` pane options; `sebside card set|clear|list`.
18
+ - Reconciliation of closed cards by tmux identity (socket, server pid, pane) on every refresh; `sebside reconcile`.
19
+ - Resume of closed cards as an argv list in a new detached session, limited to `resume_programs`, after confirmation.
20
+ - Config file `~/.config/sebside/config.toml` with environment overrides.
21
+ - TPM plugin `sebside.tmux`: `prefix + S` toggles the sidebar, `session-closed[97]` nudge hook; `sebside uninstall`.
22
+ - Allowlist of tmux commands, enforced and tested.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sebastian Wojtyna
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,262 @@
1
+ Metadata-Version: 2.5
2
+ Name: sebside-tmux
3
+ Version: 0.1.0
4
+ Summary: A tmux sidebar that shows every session as a card: who is working, who is waiting for you, what just finished.
5
+ Project-URL: Homepage, https://github.com/swojtyna/sebside-tmux
6
+ Project-URL: Repository, https://github.com/swojtyna/sebside-tmux
7
+ Project-URL: Issues, https://github.com/swojtyna/sebside-tmux/issues
8
+ Project-URL: Changelog, https://github.com/swojtyna/sebside-tmux/blob/main/CHANGELOG.md
9
+ Author: Sebastian Wojtyna
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agents,sessions,sidebar,terminal,tmux,tui
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console :: Curses
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: POSIX :: Linux
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Terminals
22
+ Classifier: Topic :: Utilities
23
+ Requires-Python: >=3.12
24
+ Description-Content-Type: text/markdown
25
+
26
+ # sebside-tmux
27
+
28
+ A tmux sidebar that shows every session as a card, so you can see at a glance who is working, who is waiting for
29
+ you, and what just finished.
30
+
31
+ ![sebside sidebar next to a tmux session](https://raw.githubusercontent.com/swojtyna/sebside-tmux/main/docs/screenshot.png)
32
+
33
+ ## Why
34
+
35
+ When you run many long jobs in tmux (AI agents, builds, test runs, dev servers), the hard part is not starting them.
36
+ It is noticing which one needs you *right now*. tmux's own session list shows names, not state.
37
+
38
+ sebside keeps a narrow pane on the left with one card per session or task:
39
+
40
+ - **waiting** (yellow ●) and **error** (red ✖) cards float to the top: they need you.
41
+ - **working** (cyan spinner) means busy, nothing to do.
42
+ - **done** (green ✔) means finished; it turns quiet once you have looked at it.
43
+ - **quiet** (grey ○) and **unknown** (grey ?) are dimmed.
44
+ - Recently closed cards stay at the bottom, greyed, and can be resumed with Enter.
45
+
46
+ It works with plain tmux out of the box (session name, directory, current command, last activity). Any program can
47
+ make its card richer with one command: `sebside card set --id build --state working --desc "compiling"`.
48
+ It knows nothing about any particular tool. Colors come from your terminal theme: only the 16 ANSI colors, bold and
49
+ dim are used.
50
+
51
+ ## Install
52
+
53
+ You need tmux 3.0 or newer and Python 3.12 or newer.
54
+
55
+ ```sh
56
+ uv tool install sebside-tmux # or: pipx install sebside-tmux
57
+ uvx --from sebside-tmux sebside --help # try it without installing
58
+ ```
59
+
60
+ Then add the tmux plugin with [TPM](https://github.com/tmux-plugins/tpm) in `~/.tmux.conf`:
61
+
62
+ ```tmux
63
+ set -g @plugin 'swojtyna/sebside-tmux'
64
+ ```
65
+
66
+ and press `prefix + I` to install it. Without TPM, clone the repo
67
+ (`git clone https://github.com/swojtyna/sebside-tmux ~/.tmux/sebside-tmux`) and add
68
+ `run-shell ~/.tmux/sebside-tmux/sebside.tmux` to your `tmux.conf`. The `sebside` command must be on tmux's `PATH`;
69
+ if `uv` says its tool directory is not on your `PATH`, run `uv tool update-shell` and restart tmux. If `sebside` is
70
+ missing, the plugin shows a message with the install command.
71
+
72
+ ## Quick start
73
+
74
+ 1. Press `prefix + S` (by default `Ctrl-b S`). The sidebar opens on the left of the current window.
75
+ 2. `↑`/`↓` (or `j`/`k`) select a card, `Enter` switches to that session.
76
+ 3. `Ctrl-b →` moves to your session, `Ctrl-b ←` back to the sidebar. `q` closes it, so does `prefix + S` again.
77
+ 4. `?` explains where the selected card's state came from (tmux basics or a card file, and how old it is).
78
+
79
+ In any pane, give it a real card:
80
+
81
+ ```sh
82
+ sebside card set --id build --state working --title "build" --desc "compiling 120 files"
83
+ make && sebside card set --id build --state done --desc "build ok" \
84
+ || sebside card set --id build --state error --desc "build failed"
85
+ ```
86
+
87
+ ## Cards: the contract
88
+
89
+ A card is one JSON file in `$XDG_STATE_HOME/sebside/cards/<id>.json` (default `~/.local/state/sebside/cards/`).
90
+ The file is the single source of truth. `sebside card set` writes it atomically (temporary file and rename, mode
91
+ 0600, directory 0700). Inside tmux it also sets two pane options, `@sebside_id` and `@sebside_state`, so the
92
+ sidebar knows which pane the card belongs to and your status line can show the state.
93
+
94
+ | `card set` flag | File field | Shown as | Default when empty |
95
+ |---|---|---|---|
96
+ | `--id` (required) | `id` | (identity) | none |
97
+ | `--state` (required) | `state` | icon, color, order | none |
98
+ | `--title` | `title` | line 1, bold | session name |
99
+ | `--subtitle` | `subtitle` | line 2, dimmed | pane directory |
100
+ | `--desc` | `desc` | line 3, dimmed, cut with … (max 300 characters) | current command |
101
+ | `--extra` | `extra` | right side of line 2 | nothing |
102
+ | `--resume` | `resume` (argv list) | Enter on a closed card | not resumable |
103
+ | `--cwd` | `cwd` | directory for resume | current directory |
104
+ | (automatic) | `tmux`: socket, server pid, pane | which pane is live | `null` outside tmux |
105
+ | (automatic) | `schema`, `rev`, `created_at`, `updated_at`, `closed_at` | age on the right | |
106
+
107
+ States: `waiting`, `error`, `working`, `done`, `quiet`, `unknown`. Text is cleaned of control characters.
108
+
109
+ **Live or closed.** A card is live when its tmux server (socket and server pid) is running and its pane still
110
+ exists. On every refresh the sidebar closes cards whose pane is gone ("reconciliation"); the plugin's
111
+ `session-closed` hook only nudges that. Pane ids reused after a tmux restart cannot claim an old card, because the
112
+ server pid differs. A card set outside tmux has no pane, is shown without one, and stays open until you clear it.
113
+
114
+ **Stale.** A card whose last update and last pane output are both older than `stale_hours` is shown as unknown.
115
+
116
+ **Resume.** `--resume "agent --resume 1234"` is split into words and stored as a list. Enter on a closed card shows
117
+ the exact command first and runs it after a second Enter, in a new detached tmux session, without a shell. Only
118
+ programs listed in `resume_programs` in the config can be resumed, and only from card files owned by you with no
119
+ group or other permissions. If a live card with the same id exists, Enter switches to it instead.
120
+ The allowlist covers the program, not its arguments: anything that can write a card file decides the arguments, so
121
+ never list a shell or interpreter (`bash`, `sh`, `python`, `ssh`, `npx`, `env`) in `resume_programs`.
122
+
123
+ Other commands:
124
+
125
+ ```sh
126
+ sebside card clear [--id ID] [--forget] # close the card (keep it in history unless --forget)
127
+ sebside card list # live and recently closed cards as JSON
128
+ sebside reconcile # close cards whose pane is gone (the hook runs this)
129
+ sebside config path | show | get KEY
130
+ sebside uninstall # remove hook, key binding, sidebar panes and @sebside_* pane options
131
+ ```
132
+
133
+ Exit codes: 0 ok, 1 runtime error, 2 usage error, 3 tmux missing or not running, 4 state not readable or writable.
134
+
135
+ ## Configuration
136
+
137
+ Everything is optional. `~/.config/sebside/config.toml` (or `$XDG_CONFIG_HOME/sebside/config.toml`, or the path in
138
+ `$SEBSIDE_CONFIG`):
139
+
140
+ ```toml
141
+ width = 36 # sidebar width used by the plugin (columns)
142
+ history = 5 # closed cards shown at the bottom
143
+ stale_hours = 12 # no update and no output this long -> unknown
144
+ quiet_minutes = 10 # a session without a card is quiet after this long without output
145
+ refresh_seconds = 1.5 # tmux poll interval; card file changes show up at once
146
+ sort = "attention" # attention | recent | name
147
+ resume_programs = [] # programs a closed card may be resumed with, e.g. ["vim", "my-agent"]
148
+
149
+ [icons] # several characters = animation frames
150
+ waiting = "●"
151
+ working = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
152
+ done = "✔"
153
+
154
+ [colors] # ANSI names (red, bright-cyan, grey, default) or #rrggbb
155
+ waiting = "bright-yellow"
156
+ selected-bg = "grey"
157
+
158
+ [filter] # glob patterns on session names
159
+ include = ["*"]
160
+ exclude = ["scratch-*"]
161
+ ```
162
+
163
+ Environment variables beat the file; the `sebside sidebar` flags `--sort` and `--history` beat both: `SEBSIDE_WIDTH`, `SEBSIDE_HISTORY`, `SEBSIDE_STALE_HOURS`,
164
+ `SEBSIDE_QUIET_MINUTES`, `SEBSIDE_REFRESH_SECONDS`, `SEBSIDE_SORT`; also `SEBSIDE_STATE_DIR`,
165
+ `SEBSIDE_TMUX_SOCKET` and `SEBSIDE_DEBUG=1` (debug log in the state directory).
166
+
167
+ tmux options, set them **before** the plugin line in `tmux.conf`:
168
+
169
+ | Option | Default | Meaning |
170
+ |---|---|---|
171
+ | `@sebside-key` | `S` | key after the prefix that toggles the sidebar (`S` is bound only if it is free) |
172
+ | `@sebside-width` | config `width` | sidebar width in columns or percent (`25%`, tmux 3.1+), always under half the window |
173
+ | `@sebside-hook` | `on` | `off` skips the `session-closed[97]` hook |
174
+
175
+ ## Integrations
176
+
177
+ Anything that can run a command can drive a card. A few examples:
178
+
179
+ **A shell script**
180
+
181
+ ```sh
182
+ #!/bin/sh
183
+ sebside card set --id backup --state working --title "backup" --desc "rsync to nas"
184
+ if rsync -a ~/photos nas:/backup/; then
185
+ sebside card set --id backup --state done --desc "backup finished"
186
+ else
187
+ sebside card set --id backup --state error --desc "rsync failed"
188
+ fi
189
+ ```
190
+
191
+ **A long-running test watcher**
192
+
193
+ ```sh
194
+ while inotifywait -qq -r -e modify src; do
195
+ sebside card set --id tests --state working --desc "running tests"
196
+ if out=$(pytest -q 2>&1 | tail -1); then state=done; else state=error; fi
197
+ sebside card set --id tests --state "$state" --desc "$out"
198
+ done
199
+ ```
200
+
201
+ **An AI coding agent (example: a Claude Code hook)**
202
+
203
+ Agents that support hooks can report "waiting for you" and "done" directly. A Claude Code hook script receives JSON
204
+ on stdin with a `session_id` and the event name:
205
+
206
+ ```sh
207
+ #!/bin/sh
208
+ # registered for the Notification, Stop and UserPromptSubmit hook events
209
+ input=$(cat)
210
+ id=$(printf '%s' "$input" | jq -r .session_id)
211
+ case $(printf '%s' "$input" | jq -r .hook_event_name) in
212
+ Notification) state=waiting ;;
213
+ Stop) state=done ;;
214
+ UserPromptSubmit) state=working ;;
215
+ *) exit 0 ;;
216
+ esac
217
+ sebside card set --id "$id" --state "$state" --resume "claude --resume $id" >/dev/null
218
+ ```
219
+
220
+ Add `claude` to `resume_programs` to resume closed agent sessions from the sidebar. Other agents and tools work
221
+ the same way: pick a stable id and map your events to states.
222
+
223
+ ## FAQ
224
+
225
+ **Does it work without any integration?** Yes. Every session gets a card from tmux basics. Cards just get better
226
+ when something calls `sebside card set`.
227
+
228
+ **Can it type into my sessions or kill them?** No. The sidebar only reads tmux and switches your client to the card
229
+ you pick, through an explicit, tested allowlist of tmux commands. It never sends keys, never runs a shell through
230
+ tmux and never kills anything. The explicit exceptions: Enter on a closed card starts a new session for its resume
231
+ command (after you confirm), the plugin's toggle key closes the sidebar pane, and `sebside uninstall` removes
232
+ sebside's own hook, key and sidebar panes.
233
+
234
+ **The colors look wrong.** sebside uses your terminal's 16 ANSI colors. Change them in your terminal theme, or
235
+ override them per state in `[colors]`.
236
+
237
+ **Does it support the mouse?** Not in 0.1. Keyboard only.
238
+
239
+ **Where is my data?** Only in `~/.local/state/sebside/cards/` and in your tmux pane options. Nothing leaves your
240
+ machine.
241
+
242
+ **How do I remove it?** Run `sebside uninstall`, remove the plugin line from `tmux.conf`, then
243
+ `uv tool uninstall sebside-tmux`. Card files stay in the state directory until you delete them.
244
+
245
+ ## Development
246
+
247
+ ```sh
248
+ uv sync
249
+ uv run pytest # integration tests need tmux and run on a private tmux server
250
+ uv run pytest -m "not tmux" # unit tests only
251
+ uv run ruff check && uv run ruff format --check
252
+ uv run mypy
253
+ scripts/demo.sh # try the sidebar on a private tmux server with demo cards
254
+ uv run --with pillow python scripts/screenshot.py docs/screenshot.png
255
+ ```
256
+
257
+ The integration tests start their own tmux server on a temporary socket and never touch your default server.
258
+ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design rules and [CONTRIBUTING.md](CONTRIBUTING.md).
259
+
260
+ ## License
261
+
262
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,237 @@
1
+ # sebside-tmux
2
+
3
+ A tmux sidebar that shows every session as a card, so you can see at a glance who is working, who is waiting for
4
+ you, and what just finished.
5
+
6
+ ![sebside sidebar next to a tmux session](https://raw.githubusercontent.com/swojtyna/sebside-tmux/main/docs/screenshot.png)
7
+
8
+ ## Why
9
+
10
+ When you run many long jobs in tmux (AI agents, builds, test runs, dev servers), the hard part is not starting them.
11
+ It is noticing which one needs you *right now*. tmux's own session list shows names, not state.
12
+
13
+ sebside keeps a narrow pane on the left with one card per session or task:
14
+
15
+ - **waiting** (yellow ●) and **error** (red ✖) cards float to the top: they need you.
16
+ - **working** (cyan spinner) means busy, nothing to do.
17
+ - **done** (green ✔) means finished; it turns quiet once you have looked at it.
18
+ - **quiet** (grey ○) and **unknown** (grey ?) are dimmed.
19
+ - Recently closed cards stay at the bottom, greyed, and can be resumed with Enter.
20
+
21
+ It works with plain tmux out of the box (session name, directory, current command, last activity). Any program can
22
+ make its card richer with one command: `sebside card set --id build --state working --desc "compiling"`.
23
+ It knows nothing about any particular tool. Colors come from your terminal theme: only the 16 ANSI colors, bold and
24
+ dim are used.
25
+
26
+ ## Install
27
+
28
+ You need tmux 3.0 or newer and Python 3.12 or newer.
29
+
30
+ ```sh
31
+ uv tool install sebside-tmux # or: pipx install sebside-tmux
32
+ uvx --from sebside-tmux sebside --help # try it without installing
33
+ ```
34
+
35
+ Then add the tmux plugin with [TPM](https://github.com/tmux-plugins/tpm) in `~/.tmux.conf`:
36
+
37
+ ```tmux
38
+ set -g @plugin 'swojtyna/sebside-tmux'
39
+ ```
40
+
41
+ and press `prefix + I` to install it. Without TPM, clone the repo
42
+ (`git clone https://github.com/swojtyna/sebside-tmux ~/.tmux/sebside-tmux`) and add
43
+ `run-shell ~/.tmux/sebside-tmux/sebside.tmux` to your `tmux.conf`. The `sebside` command must be on tmux's `PATH`;
44
+ if `uv` says its tool directory is not on your `PATH`, run `uv tool update-shell` and restart tmux. If `sebside` is
45
+ missing, the plugin shows a message with the install command.
46
+
47
+ ## Quick start
48
+
49
+ 1. Press `prefix + S` (by default `Ctrl-b S`). The sidebar opens on the left of the current window.
50
+ 2. `↑`/`↓` (or `j`/`k`) select a card, `Enter` switches to that session.
51
+ 3. `Ctrl-b →` moves to your session, `Ctrl-b ←` back to the sidebar. `q` closes it, so does `prefix + S` again.
52
+ 4. `?` explains where the selected card's state came from (tmux basics or a card file, and how old it is).
53
+
54
+ In any pane, give it a real card:
55
+
56
+ ```sh
57
+ sebside card set --id build --state working --title "build" --desc "compiling 120 files"
58
+ make && sebside card set --id build --state done --desc "build ok" \
59
+ || sebside card set --id build --state error --desc "build failed"
60
+ ```
61
+
62
+ ## Cards: the contract
63
+
64
+ A card is one JSON file in `$XDG_STATE_HOME/sebside/cards/<id>.json` (default `~/.local/state/sebside/cards/`).
65
+ The file is the single source of truth. `sebside card set` writes it atomically (temporary file and rename, mode
66
+ 0600, directory 0700). Inside tmux it also sets two pane options, `@sebside_id` and `@sebside_state`, so the
67
+ sidebar knows which pane the card belongs to and your status line can show the state.
68
+
69
+ | `card set` flag | File field | Shown as | Default when empty |
70
+ |---|---|---|---|
71
+ | `--id` (required) | `id` | (identity) | none |
72
+ | `--state` (required) | `state` | icon, color, order | none |
73
+ | `--title` | `title` | line 1, bold | session name |
74
+ | `--subtitle` | `subtitle` | line 2, dimmed | pane directory |
75
+ | `--desc` | `desc` | line 3, dimmed, cut with … (max 300 characters) | current command |
76
+ | `--extra` | `extra` | right side of line 2 | nothing |
77
+ | `--resume` | `resume` (argv list) | Enter on a closed card | not resumable |
78
+ | `--cwd` | `cwd` | directory for resume | current directory |
79
+ | (automatic) | `tmux`: socket, server pid, pane | which pane is live | `null` outside tmux |
80
+ | (automatic) | `schema`, `rev`, `created_at`, `updated_at`, `closed_at` | age on the right | |
81
+
82
+ States: `waiting`, `error`, `working`, `done`, `quiet`, `unknown`. Text is cleaned of control characters.
83
+
84
+ **Live or closed.** A card is live when its tmux server (socket and server pid) is running and its pane still
85
+ exists. On every refresh the sidebar closes cards whose pane is gone ("reconciliation"); the plugin's
86
+ `session-closed` hook only nudges that. Pane ids reused after a tmux restart cannot claim an old card, because the
87
+ server pid differs. A card set outside tmux has no pane, is shown without one, and stays open until you clear it.
88
+
89
+ **Stale.** A card whose last update and last pane output are both older than `stale_hours` is shown as unknown.
90
+
91
+ **Resume.** `--resume "agent --resume 1234"` is split into words and stored as a list. Enter on a closed card shows
92
+ the exact command first and runs it after a second Enter, in a new detached tmux session, without a shell. Only
93
+ programs listed in `resume_programs` in the config can be resumed, and only from card files owned by you with no
94
+ group or other permissions. If a live card with the same id exists, Enter switches to it instead.
95
+ The allowlist covers the program, not its arguments: anything that can write a card file decides the arguments, so
96
+ never list a shell or interpreter (`bash`, `sh`, `python`, `ssh`, `npx`, `env`) in `resume_programs`.
97
+
98
+ Other commands:
99
+
100
+ ```sh
101
+ sebside card clear [--id ID] [--forget] # close the card (keep it in history unless --forget)
102
+ sebside card list # live and recently closed cards as JSON
103
+ sebside reconcile # close cards whose pane is gone (the hook runs this)
104
+ sebside config path | show | get KEY
105
+ sebside uninstall # remove hook, key binding, sidebar panes and @sebside_* pane options
106
+ ```
107
+
108
+ Exit codes: 0 ok, 1 runtime error, 2 usage error, 3 tmux missing or not running, 4 state not readable or writable.
109
+
110
+ ## Configuration
111
+
112
+ Everything is optional. `~/.config/sebside/config.toml` (or `$XDG_CONFIG_HOME/sebside/config.toml`, or the path in
113
+ `$SEBSIDE_CONFIG`):
114
+
115
+ ```toml
116
+ width = 36 # sidebar width used by the plugin (columns)
117
+ history = 5 # closed cards shown at the bottom
118
+ stale_hours = 12 # no update and no output this long -> unknown
119
+ quiet_minutes = 10 # a session without a card is quiet after this long without output
120
+ refresh_seconds = 1.5 # tmux poll interval; card file changes show up at once
121
+ sort = "attention" # attention | recent | name
122
+ resume_programs = [] # programs a closed card may be resumed with, e.g. ["vim", "my-agent"]
123
+
124
+ [icons] # several characters = animation frames
125
+ waiting = "●"
126
+ working = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
127
+ done = "✔"
128
+
129
+ [colors] # ANSI names (red, bright-cyan, grey, default) or #rrggbb
130
+ waiting = "bright-yellow"
131
+ selected-bg = "grey"
132
+
133
+ [filter] # glob patterns on session names
134
+ include = ["*"]
135
+ exclude = ["scratch-*"]
136
+ ```
137
+
138
+ Environment variables beat the file; the `sebside sidebar` flags `--sort` and `--history` beat both: `SEBSIDE_WIDTH`, `SEBSIDE_HISTORY`, `SEBSIDE_STALE_HOURS`,
139
+ `SEBSIDE_QUIET_MINUTES`, `SEBSIDE_REFRESH_SECONDS`, `SEBSIDE_SORT`; also `SEBSIDE_STATE_DIR`,
140
+ `SEBSIDE_TMUX_SOCKET` and `SEBSIDE_DEBUG=1` (debug log in the state directory).
141
+
142
+ tmux options, set them **before** the plugin line in `tmux.conf`:
143
+
144
+ | Option | Default | Meaning |
145
+ |---|---|---|
146
+ | `@sebside-key` | `S` | key after the prefix that toggles the sidebar (`S` is bound only if it is free) |
147
+ | `@sebside-width` | config `width` | sidebar width in columns or percent (`25%`, tmux 3.1+), always under half the window |
148
+ | `@sebside-hook` | `on` | `off` skips the `session-closed[97]` hook |
149
+
150
+ ## Integrations
151
+
152
+ Anything that can run a command can drive a card. A few examples:
153
+
154
+ **A shell script**
155
+
156
+ ```sh
157
+ #!/bin/sh
158
+ sebside card set --id backup --state working --title "backup" --desc "rsync to nas"
159
+ if rsync -a ~/photos nas:/backup/; then
160
+ sebside card set --id backup --state done --desc "backup finished"
161
+ else
162
+ sebside card set --id backup --state error --desc "rsync failed"
163
+ fi
164
+ ```
165
+
166
+ **A long-running test watcher**
167
+
168
+ ```sh
169
+ while inotifywait -qq -r -e modify src; do
170
+ sebside card set --id tests --state working --desc "running tests"
171
+ if out=$(pytest -q 2>&1 | tail -1); then state=done; else state=error; fi
172
+ sebside card set --id tests --state "$state" --desc "$out"
173
+ done
174
+ ```
175
+
176
+ **An AI coding agent (example: a Claude Code hook)**
177
+
178
+ Agents that support hooks can report "waiting for you" and "done" directly. A Claude Code hook script receives JSON
179
+ on stdin with a `session_id` and the event name:
180
+
181
+ ```sh
182
+ #!/bin/sh
183
+ # registered for the Notification, Stop and UserPromptSubmit hook events
184
+ input=$(cat)
185
+ id=$(printf '%s' "$input" | jq -r .session_id)
186
+ case $(printf '%s' "$input" | jq -r .hook_event_name) in
187
+ Notification) state=waiting ;;
188
+ Stop) state=done ;;
189
+ UserPromptSubmit) state=working ;;
190
+ *) exit 0 ;;
191
+ esac
192
+ sebside card set --id "$id" --state "$state" --resume "claude --resume $id" >/dev/null
193
+ ```
194
+
195
+ Add `claude` to `resume_programs` to resume closed agent sessions from the sidebar. Other agents and tools work
196
+ the same way: pick a stable id and map your events to states.
197
+
198
+ ## FAQ
199
+
200
+ **Does it work without any integration?** Yes. Every session gets a card from tmux basics. Cards just get better
201
+ when something calls `sebside card set`.
202
+
203
+ **Can it type into my sessions or kill them?** No. The sidebar only reads tmux and switches your client to the card
204
+ you pick, through an explicit, tested allowlist of tmux commands. It never sends keys, never runs a shell through
205
+ tmux and never kills anything. The explicit exceptions: Enter on a closed card starts a new session for its resume
206
+ command (after you confirm), the plugin's toggle key closes the sidebar pane, and `sebside uninstall` removes
207
+ sebside's own hook, key and sidebar panes.
208
+
209
+ **The colors look wrong.** sebside uses your terminal's 16 ANSI colors. Change them in your terminal theme, or
210
+ override them per state in `[colors]`.
211
+
212
+ **Does it support the mouse?** Not in 0.1. Keyboard only.
213
+
214
+ **Where is my data?** Only in `~/.local/state/sebside/cards/` and in your tmux pane options. Nothing leaves your
215
+ machine.
216
+
217
+ **How do I remove it?** Run `sebside uninstall`, remove the plugin line from `tmux.conf`, then
218
+ `uv tool uninstall sebside-tmux`. Card files stay in the state directory until you delete them.
219
+
220
+ ## Development
221
+
222
+ ```sh
223
+ uv sync
224
+ uv run pytest # integration tests need tmux and run on a private tmux server
225
+ uv run pytest -m "not tmux" # unit tests only
226
+ uv run ruff check && uv run ruff format --check
227
+ uv run mypy
228
+ scripts/demo.sh # try the sidebar on a private tmux server with demo cards
229
+ uv run --with pillow python scripts/screenshot.py docs/screenshot.png
230
+ ```
231
+
232
+ The integration tests start their own tmux server on a temporary socket and never touch your default server.
233
+ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design rules and [CONTRIBUTING.md](CONTRIBUTING.md).
234
+
235
+ ## License
236
+
237
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,73 @@
1
+ [project]
2
+ name = "sebside-tmux"
3
+ version = "0.1.0"
4
+ description = "A tmux sidebar that shows every session as a card: who is working, who is waiting for you, what just finished."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Sebastian Wojtyna" }]
9
+ requires-python = ">=3.12"
10
+ dependencies = []
11
+ keywords = ["tmux", "sidebar", "tui", "terminal", "sessions", "agents"]
12
+ classifiers = [
13
+ "Development Status :: 3 - Alpha",
14
+ "Environment :: Console :: Curses",
15
+ "Intended Audience :: Developers",
16
+ "Operating System :: MacOS",
17
+ "Operating System :: POSIX :: Linux",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Topic :: Terminals",
22
+ "Topic :: Utilities",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/swojtyna/sebside-tmux"
27
+ Repository = "https://github.com/swojtyna/sebside-tmux"
28
+ Issues = "https://github.com/swojtyna/sebside-tmux/issues"
29
+ Changelog = "https://github.com/swojtyna/sebside-tmux/blob/main/CHANGELOG.md"
30
+
31
+ [project.scripts]
32
+ sebside = "sebside.cli:main"
33
+
34
+ [dependency-groups]
35
+ dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
36
+
37
+ [build-system]
38
+ requires = ["hatchling>=1.26"]
39
+ build-backend = "hatchling.build"
40
+
41
+ [tool.hatch.build.targets.wheel]
42
+ packages = ["src/sebside"]
43
+
44
+ [tool.hatch.build.targets.sdist]
45
+ include = ["src/sebside", "tests", "scripts", "sebside.tmux", "README.md", "LICENSE", "CHANGELOG.md"]
46
+
47
+ [tool.pytest.ini_options]
48
+ testpaths = ["tests"]
49
+ addopts = ["--strict-markers"]
50
+ markers = ["tmux: needs a real tmux binary; runs on a private tmux server, never the default one"]
51
+ pythonpath = ["tests"]
52
+
53
+ [tool.mypy]
54
+ strict = true
55
+ python_version = "3.12"
56
+ files = ["src/sebside"]
57
+
58
+ [tool.ruff]
59
+ line-length = 120
60
+ target-version = "py312"
61
+ src = ["src", "tests"]
62
+
63
+ [tool.ruff.lint]
64
+ select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "PT", "C4", "PTH", "TC", "T20", "S", "ANN"]
65
+ ignore = ["RUF001", "RUF002", "RUF003"] # box-drawing and icon characters are intentional
66
+
67
+ [tool.ruff.lint.per-file-ignores]
68
+ "src/sebside/tmux.py" = ["S603", "S607"] # the only module that runs a subprocess
69
+ "src/sebside/cli.py" = ["T20"] # print is allowed only in cli, render and tui
70
+ "src/sebside/render.py" = ["T20"]
71
+ "src/sebside/tui.py" = ["T20"]
72
+ "tests/**" = ["S101", "S108", "S603", "S607", "ANN", "T20", "PTH", "PT018", "TC"]
73
+ "scripts/**" = ["T20", "S603", "S607"]