dsh-wo-tmux
A DeepSeek Harness (DSH)
plugin: your tmux workflow, wired into the Workspace Overview tab. The
plugin knows whether the current workspace's tmux session is live, frozen
with tmux-fridge, or resting in cold storage, and one click opens a fresh
terminal attached to it: unfreezing or recovering first when needed.
For people who live in named tmux sessions per project and suspend work
mid-thought, this closes the gap between the browser harness and the
console: no more tmux ls, no more remembering which projects are frozen.
What you get
- Pill in the session header: shows the workspace's tmux session and
its state; clicking opens a terminal attached to it (attach, unfreeze,
or recover, per state). Hidden for workspaces without a session, or
via a toggle in Granular Settings.
- Tmux subtab in Workspace Overview, in two panes:
- Session (default):
- a status card: session name, state chip, how it was resolved
(explicit link or name convention), attached clients and windows;
- actions per state: open console, snapshot to cold storage, freeze
(with a confirmation; freezing kills the live session), recover,
clean snapshot (also confirmed);
- linking: pin the workspace to any session name (grouped by live,
frozen, cold storage), unlink, or create a new session (pre-filled
with the workspace basename, auto-linked, opened in a terminal).
- All sessions: every session the machine knows about, grouped by
store: live sessions (open console, freeze, snapshot), frozen
sessions (unfreeze), and cold-storage snapshots (recover, clean).
Freezing any live session from this pane is how a project gets
parked without leaving the harness.
- The tab polls while it is open: after an action (unfreeze hands off
to a terminal and returns before tmux settles) the state chips catch
up on their own, no page switching needed.
- Workspace-to-session links survive reboots in
~/.dsh/settings/wo-tmux.json, so colliding basenames (two projects
named api) stay unambiguous.
How it resolves a workspace to a session
First match wins:
- an explicit link from the link store;
- a tmux session named like the workspace's basename, looked up in the
live server, the frozen list, then cold storage;
- nothing (the tab invites you to create or link).
How it talks to tmux
The host half shells out to the tmux and tmux-fridge CLIs with
argument arrays only (no shell interpolation). Open runs the fridge
command bare: tmux-fridge detects and launches the terminal for the attach
itself and exits, so wrapping it would only flash a window that dies the
moment the handoff happens. Only create needs a terminal from us (plain
tmux new-session cannot spawn one): $TERMINAL picks the emulator;
without it the plugin probes kitty, alacritty, wezterm, gnome-terminal,
x-terminal-emulator, and xterm, and detaches the session when none is
found. The TMUX_FRIDGE_BIN environment variable overrides the fridge
binary location. Storage formats are never read directly: the CLIs are the
contract, so tmux-fridge can change its layout freely.
How to install
Requires a DeepSeek Harness checkout and a profile, here web. tmux
and tmux-fridge must be on PATH. Clone the dependencies and this plugin
into a plugins folder:
mkdir -p ~/dsh-plugins && cd ~/dsh-plugins
git clone https://github.com/joao-paulo-santos/dsh-workspace-overview.git
git clone https://github.com/joao-paulo-santos/dsh-wo-tmux.git
# from the harness checkout
pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-workspace-overview
pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-wo-tmux
# verify the profile still composes
pnpm dsh --profile web --dump-config
Restart the harness; the Tmux tab appears in Workspace Overview and the
pill appears on sessions whose workspace has a session.
Dependencies
- dsh-workspace-overview hosts the subtab and the pill (required; without it the client half stays inactive)
- the
tmux binary on PATH (session listing and creation)
- the
tmux-fridge binary on PATH (frozen/cold storage and the attach actions); without it the tab still shows live state and a clear "not on PATH" note
- a terminal emulator:
$TERMINAL or one of the probed ones; without any, open and create fall back to detached sessions where possible
Plugins dependent on this
(none)
Limitations
- The plugin never embeds a terminal in the browser; it spawns a real
terminal window. That is the point.
- One terminal window per click. Attaching twice to the same session is
normal tmux and stays your business.
- Name detection covers one session per workspace; many-to-many setups
(several sessions for one project) are out of scope, though linking
picks the one you care about.
