In agent development, there is often a disconnect between the browser Harness and the terminal console. Developers frequently switch context, manually check tmux session status, or forget which working sessions have been frozen. The dsh-wo-tmux plugin integrates the tmux workflow directly into DeepSeek Harness’s Workspace Overview, addressing status visibility and quick access.

Plugin Introduction

dsh-wo-tmux is a DeepSeek Harness (DSH) client plugin maintained by joao-paulo-santos. It provides a tmux workspace overview, supports displaying session status (live, frozen, cold storage), and provides one-click terminal attach, helping developers manage terminal sessions without leaving the browser.

Core Features

  1. Session State Capsule
    Displays a state capsule in the session header of Workspace Overview, intuitively showing the current session status. Click the capsule to open or attach to the terminal, automatically performing unfreezing or restoration depending on the status.

  2. Workspace Overview Subtab
    Provides a Tmux subtab in Workspace Overview, divided into two views:

    • Session: Displays detailed status for the current workspace session (name, status chip, resolution method, client count, window count).
    • All sessions: Lists all sessions on the machine, grouped by status, and supports managing sessions from the global view.

  3. Session Operations
    Provides different operation options based on session status:

    • Live session: open console, freeze, snapshot to cold storage.
    • Frozen session: unfreeze, restore, clean up snapshot.
    • Cold storage session: restore, clean up snapshot.
    • All operations require confirmation to prevent accidental actions.

  4. Linking and Grouping
    Supports pinning a workspace to a custom session name for grouped display. This is useful for projects with the same name (for example, two projects both named api); explicit links can be used to avoid conflicts.

  5. Persistent Links
    The link relationship between workspaces and sessions is persistently stored in ~/.dsh/settings/wo-tmux.json and remains valid after restart.

  6. Session Resolution Priority
    The plugin resolves a workspace to a session using the following priority:

    1. Explicit link (Link Store)
    2. Basename match (Workspace Basename)
    3. No match (manual creation or linking required)

Installation and Activation

Before installing, ensure DeepSeek Harness (DSH) is installed and you have a profile (the examples use the web profile). The system’s PATH must include tmux and tmux-fridge.

  1. Create the plugin directory and clone dependencies:
    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
  1. Run plugin installation from the Harness checkout directory:
    pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-workspace-overview
    pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-wo-tmux
  1. Verify configuration:
    pnpm dsh --profile web --dump-config

After restarting Harness, you can see the Tmux subtab in Workspace Overview, and a state capsule appears in the header of the associated session.

Typical Use Cases

  • Freezing workflow: Use tmux-fridge to freeze a long-running work session currently in progress, keeping system resource usage minimal.
  • Quick access: Click the state capsule in Workspace Overview to directly open a real terminal window and attach to the session, without manually typing tmux attach.
  • Resolving conflicts: Link workspaces for two projects with the same name to different custom session names, and clearly distinguish them in Workspace Overview.

Applicable Scenarios and Notes

Applicable Scenarios

  • Developers who use tmux-fridge to manage session freezing and restoration.
  • Agent developers who frequently switch between the browser Harness and terminal.
  • Users who need to uniformly manage tmux session status across multiple machines.

Notes

  • Dependencies: The dsh-workspace-overview plugin must be installed; otherwise, client features will not take effect.
  • Terminal emulator: The plugin relies on a terminal emulator. Specify it via the $TERMINAL environment variable when creating a session; if not specified, common emulators such as kitty, alacritty, and wezterm are probed.
  • Environment variables: Use the TMUX_FRIDGE_BIN environment variable to specify the path to the tmux-fridge binary.
  • Real terminal: The plugin does not embed a browser terminal; it creates a real terminal window. Each click opens only one terminal window.
  • Scenario limitations: Name detection currently covers only one-to-one scenarios (one workspace to one session); many-to-many scenarios are not covered.

Summary

dsh-wo-tmux introduces tmux session state management into DSH’s Workspace Overview, achieving seamless connection between browser operations and terminal control. It provides a clear visual interface through state capsules and subtabs, and simplifies session freezing, restoration, and management through standardized operation flows.