dsh-wo-tmux

Readme

# dsh-wo-tmux

A [DeepSeek Harness](https://github.com/deepseek-ai/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:

1. an explicit link from the link store;
2. a tmux session named like the workspace's basename, looked up in the
   live server, the frozen list, then cold storage;
3. 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:

```sh
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](https://github.com/joao-paulo-santos/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.