workstreams-cli 0.6.1__tar.gz → 0.6.4__tar.gz

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstreams-cli
-Version: 0.6.1
+Version: 0.6.4
 Summary: Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more).
 Author: Dream-Pixels-Forge
 License: MIT
@@ -114,7 +114,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.1
+workstreams --version   # -> workstreams 0.6.4
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.
@@ -139,10 +139,36 @@ The terminal tool that hosts the visible windows. `workstreams` currently suppor
 
 | Multiplexer | Layouts | Notes |
 |-------------|---------|-------|
-| `tmux` (default) | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
+| `default` (auto-detect) | per backend | **Picks the best multiplexer installed for your OS**: `tmux` on macOS, `lmux` on Linux, `wmux` on Windows — falling back to `zellij` when the platform primary is missing. This is now the out-of-the-box behaviour. |
+| `tmux` | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
 | `zellij` | tabs | One **tab per workstream**. Simpler scripting surface; `dispatch` targets the current tab only. |
+| `nami` / `lmux` / `wmux` / `herdr` | tmux-compatible | tmux-compatible CLIs wrapped by `TmuxCompatibleMultiplexer`. |
 
-The tmux/zellij session is auto-named `workstreams-<project>`.
+**Auto-detect** — you normally don't pick one. `load_config` resolves the
+platform default at startup:
+
+```
+macOS   → tmux first, then zellij, nami, lmux, wmux
+Linux   → lmux first, then zellij, then tmux
+Windows → wmux first, then lmux, zellij, tmux
+```
+
+The first *installed* binary in that list wins — **and** for the
+tmux-compatible wrapper family (`nami` / `lmux` / `wmux` / `herdr`)
+workstreams validates that the binary actually exposes tmux-style verbs
+(`new-session` / `send-keys` / …) before committing. For example `lmux`
+v1 has a completely different CLI shape (`workspace.create`,
+`surface.send-key`) so the validator rejects it and auto-detect falls
+through to `zellij` or `tmux`. If you *know* your `lmux` build exposes
+the tmux dialect, pin it explicitly with `multiplexer: lmux` — the
+validator is only consulted on the `default` auto-pick path. If you want a specific one:
+
+- Set it in your `.workstreams.yaml` / `.json`: `multiplexer: zellij`
+- Or pass `--multiplexer zellij` on `init` / `start` / `dispatch` / `work`
+- Or run `workstreams init --choose` to interactively pick, which persists the
+  choice into your config file so later commands use it.
+
+The tmux/zellij/lmux/wmux session is auto-named `workstreams-<project>`.
 
 ### 3. Subagent
 The coding agent doing the work inside a workstream. This is deliberately **free-form**: `claude-code`, `codex`, `opencode`, `qwen-code`, `mimocode`, `hermes`, `kilo-code`, `cline`, or any label you want. There is no vendor lock-in — a subagent is just an identifier used in the event log. The agent that actually runs is whatever command you send into the pane (see `dispatch`/`work`).

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/README.md

@@ -84,7 +84,7 @@ pip install -e ".[yaml,dev]"   # dev extras add pytest
 Verify:
 
 ```bash
-workstreams --version   # -> workstreams 0.6.1
+workstreams --version   # -> workstreams 0.6.4
 ```
 
 > **Note:** every command also accepts `--json` to emit machine-readable output (where supported), which coding agents can parse. All read-side commands work without a multiplexer installed; only `start`/`dispatch`/`work`/`attach` need one.
@@ -109,10 +109,36 @@ The terminal tool that hosts the visible windows. `workstreams` currently suppor
 
 | Multiplexer | Layouts | Notes |
 |-------------|---------|-------|
-| `tmux` (default) | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
+| `default` (auto-detect) | per backend | **Picks the best multiplexer installed for your OS**: `tmux` on macOS, `lmux` on Linux, `wmux` on Windows — falling back to `zellij` when the platform primary is missing. This is now the out-of-the-box behaviour. |
+| `tmux` | `even-horizontal`, `even-vertical`, `main-horizontal`, `tiled` | One **window per workstream** (cleanest for agents), or all in one tiled window. Detached sessions survive your logout. |
 | `zellij` | tabs | One **tab per workstream**. Simpler scripting surface; `dispatch` targets the current tab only. |
+| `nami` / `lmux` / `wmux` / `herdr` | tmux-compatible | tmux-compatible CLIs wrapped by `TmuxCompatibleMultiplexer`. |
 
-The tmux/zellij session is auto-named `workstreams-<project>`.
+**Auto-detect** — you normally don't pick one. `load_config` resolves the
+platform default at startup:
+
+```
+macOS   → tmux first, then zellij, nami, lmux, wmux
+Linux   → lmux first, then zellij, then tmux
+Windows → wmux first, then lmux, zellij, tmux
+```
+
+The first *installed* binary in that list wins — **and** for the
+tmux-compatible wrapper family (`nami` / `lmux` / `wmux` / `herdr`)
+workstreams validates that the binary actually exposes tmux-style verbs
+(`new-session` / `send-keys` / …) before committing. For example `lmux`
+v1 has a completely different CLI shape (`workspace.create`,
+`surface.send-key`) so the validator rejects it and auto-detect falls
+through to `zellij` or `tmux`. If you *know* your `lmux` build exposes
+the tmux dialect, pin it explicitly with `multiplexer: lmux` — the
+validator is only consulted on the `default` auto-pick path. If you want a specific one:
+
+- Set it in your `.workstreams.yaml` / `.json`: `multiplexer: zellij`
+- Or pass `--multiplexer zellij` on `init` / `start` / `dispatch` / `work`
+- Or run `workstreams init --choose` to interactively pick, which persists the
+  choice into your config file so later commands use it.
+
+The tmux/zellij/lmux/wmux session is auto-named `workstreams-<project>`.
 
 ### 3. Subagent
 The coding agent doing the work inside a workstream. This is deliberately **free-form**: `claude-code`, `codex`, `opencode`, `qwen-code`, `mimocode`, `hermes`, `kilo-code`, `cline`, or any label you want. There is no vendor lock-in — a subagent is just an identifier used in the event log. The agent that actually runs is whatever command you send into the pane (see `dispatch`/`work`).

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workstreams-cli"
-version = "0.6.1"
+version = "0.6.4"
 description = "Visually dispatch coding-agent work to subagents in real terminal windows and monitor it in one dashboard - for any coding agent (Claude Code, Codex, OpenCode, Qwen Code, Hermes, Cline, and more)."
 readme = "README.md"
 requires-python = ">=3.9"

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/src/workstreams/__init__.py

@@ -42,7 +42,7 @@ from .confidence import (
     extract_score,
 )
 
-__version__ = "0.6.1"
+__version__ = "0.6.4"
 
 __all__ = [
     # models

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/src/workstreams/cli.py

@@ -98,7 +98,8 @@ def build_parser() -> argparse.ArgumentParser:
     # init
     init = common_parent("init")
     init.add_argument("--workstreams", type=int, default=4, help="Number of workstreams to create (default: 4)")
-    init.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None, help="Multiplexer type")
+    init.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None, help="Multiplexer type ('default' = auto-detect: tmux/mac, lmux/linux, wmux/win)")
+    init.add_argument("--choose", action="store_true", help="Interactively pick the multiplexer (writes choice to .workstreams.yaml)")
     init.add_argument("--layout", choices=["even-horizontal", "even-vertical", "main-horizontal", "tiled"], default=None)
     init.add_argument("--base-branch", default=None, help="Base branch (default: main)")
     init.add_argument("--mode", choices=["worktree", "branch"], default=None, help="worktree (isolated) or branch (shared dir)")
@@ -110,12 +111,12 @@ def build_parser() -> argparse.ArgumentParser:
     start = common_parent("start")
     start.add_argument("--workstream", type=int, help="Start a single workstream by ID")
     start.add_argument("--cmd", help="Override the command sent to each pane")
-    start.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    start.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
     start.add_argument("--layout", choices=["even-horizontal", "even-vertical", "main-horizontal", "tiled"], default=None)
 
     # attach
     attach = common_parent("attach")
-    attach.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    attach.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
     attach.add_argument("--session", help="Override session name")
 
     # status
@@ -162,7 +163,7 @@ def build_parser() -> argparse.ArgumentParser:
     dispatch.add_argument("--prompt", help="Prompt / task description sent to the pane")
     dispatch.add_argument("--agent", help="Agent binary to invoke (e.g. 'claude', 'codex', 'opencode run'). If omitted, sends --prompt verbatim to the pane.")
     dispatch.add_argument("--wait", action="store_true", help="Block until subagent reports done/failed")
-    dispatch.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    dispatch.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
 
     # work (run agent command directly)
     work = common_parent("work")
@@ -172,7 +173,7 @@ def build_parser() -> argparse.ArgumentParser:
     work.add_argument("--subagent", default="agent", help="Identifier used in event log")
     work.add_argument("--issue", type=int, default=0)
     work.add_argument("--wait", action="store_true", help="Block until terminal event")
-    work.add_argument("--multiplexer", choices=["tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
+    work.add_argument("--multiplexer", choices=["default", "tmux", "zellij", "nami", "lmux", "wmux", "herdr"], default=None)
 
     # run
     run = common_parent("run")
@@ -266,6 +267,13 @@ def _cmd_init(args) -> int:
         manager.config.mode = args.mode
     if args.agent:
         manager.config.agent = args.agent
+    # Interactive picker: ask the user which multiplexer to persist,
+    # then write it to the config file.
+    if getattr(args, "choose", False):
+        from .multiplexer import resolve_default_multiplexer
+        chosen = resolve_default_multiplexer(interactive=True)
+        manager.config.multiplexer = chosen
+        print(f"Multiplexer: {chosen} (persisted to config)")
     if args.no_worktrees:
         # Skip git worktree creation; just write config
         from .models import WorkstreamConfig

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/src/workstreams/config.py

@@ -80,9 +80,17 @@ def load_config(
     if not project:
         project = base_path.name or "myproject"
 
+    # Resolve the multiplexer: explicit config/env value wins; the literal
+    # string "default" (or absence) auto-detects the best installed
+    # multiplexer for this platform (tmux/mac, lmux/linux, wmux/win).
+    multiplexer = data.get("multiplexer") or os.environ.get("WORKSTREAMS_MULTIPLEXER") or "default"
+    if multiplexer == "default":
+        from .multiplexer import resolve_default_multiplexer
+        multiplexer = resolve_default_multiplexer(interactive=False)
+
     return WorkstreamsConfig(
         project=project,
-        multiplexer=data.get("multiplexer") or os.environ.get("WORKSTREAMS_MULTIPLEXER") or "tmux",
+        multiplexer=multiplexer,
         layout=data.get("layout") or os.environ.get("WORKSTREAMS_LAYOUT") or "even-horizontal",
         base_branch=data.get("base_branch") or os.environ.get("WORKSTREAMS_BASE_BRANCH") or "main",
         mode=data.get("mode") or os.environ.get("WORKSTREAMS_WORKTREE_MODE") or "worktree",

{workstreams_cli-0.6.1 → workstreams_cli-0.6.4}/src/workstreams/models.py

@@ -39,7 +39,7 @@ class WorkstreamsConfig:
     """Project-level configuration."""
 
     project: str
-    multiplexer: str = "tmux"
+    multiplexer: str = "default"  # "default" = auto-detect platform best
     layout: str = "even-horizontal"
     base_branch: str = "main"
     mode: str = "worktree"  # worktree|branch

workstreams_cli-0.6.4/src/workstreams/multiplexer/__init__.py

@@ -0,0 +1,223 @@
+"""Terminal multiplexer implementations + platform-aware default detection."""
+
+import shutil
+import subprocess
+import sys
+from typing import Dict
+
+from .base import MultiplexerBase
+from .tmux import TmuxMultiplexer
+from .zellij import ZellijMultiplexer
+from .tmux_compatible import TmuxCompatibleMultiplexer
+from .lmux import LmuxMultiplexer
+from .wmux import WmuxMultiplexer
+
+__all__ = [
+    "MultiplexerBase",
+    "TmuxMultiplexer",
+    "ZellijMultiplexer",
+    "LmuxMultiplexer",
+    "WmuxMultiplexer",
+    "get_multiplexer",
+    "resolve_default_multiplexer",
+]
+
+# Name -> binary that must be on PATH. The TmuxCompatibleMultiplexer wraps
+# any binary whose CLI is compatible with tmux (send-keys, new-window, ...).
+# NOTE: "lmux" and "wmux" are NOT tmux-compatible; they have native dialects
+# (LmuxMultiplexer JSON verbs / WmuxMultiplexer JSON-RPC) and are handled by
+# their own classes. The tmux-compat shim HANGS FOREVER on wmux (every wmux
+# invocation launches the Electron GUI and blocks), so wmux must never be
+# routed through it.
+_TMUX_COMPATIBLE = {
+    "nami": "nami",
+    "herdr": "herdr",
+}
+
+# Ordered preference list per platform. We pick the FIRST that is installed.
+# lmux is the top Linux choice because it is purpose-built for AI coding
+# agents and workstreams now drives it natively.
+_PLATFORM_PREFERENCE = {
+    "win": ["wmux", "lmux", "zellij", "tmux"],
+    "mac": ["tmux", "zellij", "nami", "lmux", "wmux"],
+    "linux": ["lmux", "zellij", "tmux"],
+}
+
+
+def _installed(name: str) -> bool:
+    """Return True if the CLI binary for `name` is on PATH.
+
+    For the tmux-compatible wrappers (nami, wmux, herdr) we additionally
+    require that the binary actually exposes a tmux-style command.
+
+    `lmux` and `wmux` are special-cased: each speaks its OWN native dialect
+    and is driven by its dedicated class (LmuxMultiplexer / WmuxMultiplexer)
+    — never the tmux wrapper. wmux additionally requires a live RPC socket
+    for auto-detect, because probing it with a subprocess would launch the
+    Electron GUI and block.
+    """
+    if name == "lmux":
+        if shutil.which("lmux") is None:
+            return False
+        return _supports_lmux_dialect("lmux")
+    if name == "wmux":
+        if shutil.which("wmux") is None:
+            return False
+        from .wmux import default_socket_path
+        import os
+        return os.path.exists(default_socket_path())
+    if name in ("tmux", "zellij"):
+        binary = name
+    elif name in _TMUX_COMPATIBLE:
+        binary = _TMUX_COMPATIBLE[name]
+    else:
+        return False
+    if shutil.which(binary) is None:
+        return False
+    if name in _TMUX_COMPATIBLE:
+        return _supports_tmux_dialect(binary)
+    return True
+
+
+_tmux_dialect_cache: Dict[str, bool] = {}
+_lmux_dialect_cache: Dict[str, bool] = {}
+
+
+def _supports_lmux_dialect(binary: str) -> bool:
+    """Heuristic: does `binary` expose lmux's native verb-dialect?
+
+    Probes ``<binary> help`` for the canonical native verbs:
+    ``workspace.create`` AND ``surface.send_text``. A binary that has these
+    is driven natively by :class:`LmuxMultiplexer` (JSON socket protocol).
+    """
+    key = binary
+    if key in _lmux_dialect_cache:
+        return _lmux_dialect_cache[key]
+    result = False
+    try:
+        proc = subprocess.run([binary, "help"], capture_output=True, text=True, timeout=5)
+        help_text = (proc.stdout or "") + (proc.stderr or "")
+        has_workspace = "workspace.create" in help_text
+        has_send_text = "surface.send_text" in help_text or "surface.send-text" in help_text
+        result = has_workspace and has_send_text
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        result = False
+    _lmux_dialect_cache[key] = result
+    return result
+
+
+def _supports_tmux_dialect(binary: str) -> bool:
+    """Heuristic: does `binary` accept tmux-style subcommands?
+
+    Probing method:
+      1. Run `<binary> help` — look for canonical tmux verbs
+         (new-session / has-session / send-keys / capture-pane).
+      2. If that's inconclusive (tmux has no `help` subcommand and dumps
+         to stderr instead), run `<binary> new-session -P` and treat
+         "command not found" / "unknown command" in stderr as a negative.
+
+    For `lmux` the help text exposes `workspace.create` / `surface.send-key`
+    instead of the tmux verbs, so this probe correctly returns False and
+    auto-detect skips it — only an explicit user-configured `lmux` will
+    attempt the wrapper.
+    """
+    import subprocess as _sp
+    key = binary
+    if key in _tmux_dialect_cache:
+        return _tmux_dialect_cache[key]
+    result = False
+    try:
+        proc = _sp.run([binary, "help"], capture_output=True, text=True, timeout=5)
+        help_text = (proc.stdout or "") + (proc.stderr or "")
+        # Require BOTH a session verb and a key verb. `lmux` happens to
+        # mention "capture-pane" in one subcommand's description but is
+        # missing session.send-keys / new-session entirely, so a single
+        # hit is not enough to call it tmux-compatible.
+        has_session = any(m in help_text for m in ("new-session", "has-session"))
+        has_keys = any(m in help_text for m in ("send-keys", "send-text"))
+        result = has_session and has_keys
+    except (_sp.TimeoutExpired, FileNotFoundError, OSError):
+        result = False
+    if not result:
+        # Secondary probe: tmux has no `help`; `new-session -P` on a bad
+        # socket prints an error but the command exists. Only count as
+        # "no dialect" when we see an explicit unknown-command message.
+        try:
+            proc = _sp.run([binary, "new-session", "-P"],
+                           capture_output=True, text=True, timeout=5)
+            err = (proc.stderr or "").lower()
+            if proc.returncode != 0 and ("unknown command" in err or "invalid command" in err):
+                result = False
+        except (_sp.TimeoutExpired, FileNotFoundError, OSError):
+            pass
+    _tmux_dialect_cache[key] = result
+    return result
+
+
+def resolve_default_multiplexer(interactive: bool = False, quiet: bool = False) -> str:
+    """Pick the best available multiplexer for the current platform.
+
+    Returns a string name (tmux, zellij, lmux, wmux, ...). When
+    `interactive` and no preference is installed, asks the user. When
+    `quiet`, never prompts — falls back to the first available, or "tmux".
+    """
+    platform = sys.platform
+    if platform.startswith("win"):
+        key = "win"
+    elif platform == "darwin":
+        key = "mac"
+    else:
+        key = "linux"
+
+    preference = _PLATFORM_PREFERENCE[key]
+    available = [m for m in preference if _installed(m)]
+
+    primary = preference[0]
+    if _installed(primary):
+        return primary
+    if available:
+        return available[0]
+
+    # Nothing on the preference list is installed.
+    if interactive and sys.stdin.isatty():
+        options = [m for m in preference if _installed(m)] or _PLATFORM_PREFERENCE[key]
+        print("No preferred multiplexer found on this system. Available options:")
+        for i, opt in enumerate(options, start=1):
+            print(f"  {i}. {opt}")
+        print("Which one? [1]: ", end="", flush=True)
+        try:
+            choice = int(input().strip() or "1")
+        except (ValueError, EOFError):
+            choice = 1
+        return options[choice - 1] if 1 <= choice <= len(options) else options[0]
+
+    # Quiet / non-interactive: fall back to tmux (the most universal one).
+    if _installed("tmux"):
+        return "tmux"
+    return "tmux"  # the caller will surface the "install tmux" hint
+
+
+def get_multiplexer(name: str, config) -> MultiplexerBase:
+    """Get a multiplexer instance by name."""
+    if name == "default" or not name:
+        # Resolve the platform-aware default; the user can override this in
+        # .workstreams.yaml by setting `multiplexer: tmux` (or any other).
+        name = resolve_default_multiplexer(interactive=False)
+    multiplexers = {
+        "tmux": TmuxMultiplexer,
+        "zellij": ZellijMultiplexer,
+        "lmux": LmuxMultiplexer,
+        "wmux": WmuxMultiplexer,
+    }
+    cls = multiplexers.get(name)
+    if not cls:
+        # Fallback: a tmux-compatible wrapper binary (nami/herdr).
+        if name in _TMUX_COMPATIBLE:
+            binary = _TMUX_COMPATIBLE[name]
+            return TmuxCompatibleMultiplexer(config, binary)
+        raise ValueError(
+            f"Unknown multiplexer: {name}. "
+            f"Supported: {', '.join(multiplexers)} plus tmux-compatible: "
+            f"{', '.join(_TMUX_COMPATIBLE)} or 'default' (auto-detect)."
+        )
+    return cls(config)