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.
- sebside_tmux-0.1.0/.gitignore +11 -0
- sebside_tmux-0.1.0/CHANGELOG.md +22 -0
- sebside_tmux-0.1.0/LICENSE +21 -0
- sebside_tmux-0.1.0/PKG-INFO +262 -0
- sebside_tmux-0.1.0/README.md +237 -0
- sebside_tmux-0.1.0/pyproject.toml +73 -0
- sebside_tmux-0.1.0/scripts/demo.sh +48 -0
- sebside_tmux-0.1.0/scripts/screenshot.py +133 -0
- sebside_tmux-0.1.0/scripts/toggle.sh +41 -0
- sebside_tmux-0.1.0/sebside.tmux +76 -0
- sebside_tmux-0.1.0/src/sebside/__init__.py +8 -0
- sebside_tmux-0.1.0/src/sebside/__main__.py +3 -0
- sebside_tmux-0.1.0/src/sebside/cards.py +257 -0
- sebside_tmux-0.1.0/src/sebside/cli.py +361 -0
- sebside_tmux-0.1.0/src/sebside/config.py +214 -0
- sebside_tmux-0.1.0/src/sebside/errors.py +39 -0
- sebside_tmux-0.1.0/src/sebside/log.py +35 -0
- sebside_tmux-0.1.0/src/sebside/model.py +132 -0
- sebside_tmux-0.1.0/src/sebside/py.typed +0 -0
- sebside_tmux-0.1.0/src/sebside/render.py +390 -0
- sebside_tmux-0.1.0/src/sebside/store.py +343 -0
- sebside_tmux-0.1.0/src/sebside/tmux.py +312 -0
- sebside_tmux-0.1.0/src/sebside/tui.py +346 -0
- sebside_tmux-0.1.0/tests/conftest.py +24 -0
- sebside_tmux-0.1.0/tests/fakes.py +127 -0
- sebside_tmux-0.1.0/tests/integration/test_real_tmux.py +231 -0
- sebside_tmux-0.1.0/tests/unit/test_cards.py +163 -0
- sebside_tmux-0.1.0/tests/unit/test_cli.py +184 -0
- sebside_tmux-0.1.0/tests/unit/test_config.py +97 -0
- sebside_tmux-0.1.0/tests/unit/test_plugin_script.py +36 -0
- sebside_tmux-0.1.0/tests/unit/test_render.py +143 -0
- sebside_tmux-0.1.0/tests/unit/test_review_fixes.py +268 -0
- sebside_tmux-0.1.0/tests/unit/test_store.py +136 -0
- sebside_tmux-0.1.0/tests/unit/test_tmux.py +190 -0
- sebside_tmux-0.1.0/tests/unit/test_tui.py +166 -0
|
@@ -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
|
+

|
|
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
|
+

|
|
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"]
|