optmux 0.1.0__tar.gz

optmux-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: optmux
+Version: 0.1.0
+Summary: Optimal, opinionated, batteries-included TMUX that's neat and easy for any project
+Author: Jaeho Shin
+Author-email: Jaeho Shin <netj@sparcs.org>
+License-Expression: MIT
+Requires-Dist: tmuxp
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# optmux
+
+<p align="center">
+  <img src="optmux.svg" width="192" alt="optmux logo">
+</p>
+
+Optimal, opinionated, batteries-included TMUX that's neat and easy for any project.
+
+A [tmuxp](https://tmuxp.git-pull.com) wrapper that creates per-project tmux config directories with [TPM](https://github.com/tmux-plugins/tpm) and plugins pre-configured.
+
+## Quick Start
+
+```bash
+# run optmux anywhere (installs on first use via uv)
+uvx optmux
+
+# strongly recommended: install wtcode + lazygit for the full experience
+brew install netj/tap/optmux
+```
+
+Try the included example:
+
+```bash
+git clone https://github.com/netj/optmux.git && cd optmux
+./example.optmux.yaml
+```
+
+On first run, optmux will:
+
+1. Create `.example.optmux.d/tmux/` next to the YAML file
+2. Seed a default `tmux.conf` with TPM and plugins
+3. Install TPM and all plugins (visible in window 0)
+4. Launch tmuxp with an isolated tmux server
+
+## Usage
+
+### With a tmuxp YAML file
+
+Supports `.optmux.yaml`, `.tmuxp.yaml`, and `.optmuxp.yaml` extensions:
+
+```bash
+optmux myproject.optmux.yaml
+optmux myproject.tmuxp.yaml
+```
+
+### Without arguments
+
+```bash
+optmux
+```
+
+Opens plain `tmux` using `.optmux.d/` in the current directory — useful for a quick, isolated tmux session with the bundled config.
+
+### As a shebang
+
+Write a [tmuxp YAML config](https://tmuxp.git-pull.com/configuration/) with the optmux shebang line and make it executable:
+
+```yaml
+#!/usr/bin/env -S uvx optmux
+session_name: myproject
+windows:
+  - window_name: editor
+    panes:
+      - vim .
+  - window_name: shell
+    panes:
+      - ""
+```
+
+```bash
+chmod +x myproject.optmux.yaml
+./myproject.optmux.yaml
+```
+
+## Example tmuxp YAML
+
+Here's the included [`example.optmux.yaml`](example.optmux.yaml) showing shortcuts, tmux config, and window layout:
+
+```yaml
+#!/usr/bin/env -S uvx optmux
+session_name: example
+start_directory: .
+
+optmux:
+  shortcuts:
+    C-M-b: gh browse .
+    C-M-e:
+      command: ${VISUAL:-${EDITOR:-vim}} README.md  # exec directly (default for str, no latency)
+      window: true                                  # in a new-window
+    E:
+      send-keys: ${VISUAL:-${EDITOR:-vim}} .        # send-keys (given command is run in a new shell)
+      zoom: false                                   # do not zoom (defaults to zoom when split-window)
+  tmux_config:
+    project-settings: |
+      set -g status-style bg=blue
+
+windows:
+  - window_name: editor
+    panes:
+      - vim .
+  - window_name: shell
+    panes:
+      - ""
+  - window_name: logs
+    panes:
+      - tail -f /var/log/system.log
+```
+
+## Config directory
+
+Each project gets its own `.$NAME.optmux.d/` directory:
+
+| Path | Purpose |
+|---|---|
+| `tmux/tmux.conf` | Main tmux config (editable after creation) |
+| `tmux/tmux.*.conf` | Additional config files you can add |
+| `tmux/tmux.sock` | Tmux server socket (isolates this project) |
+| `tmux/plugins/` | TPM plugin directory |
+| `tmux/plugins-update.sh` | Run manually to update all plugins |
+
+## optmux YAML config
+
+Add an `optmux:` section to your tmuxp YAML to configure shortcuts and tmux settings:
+
+```yaml
+optmux:
+  shortcuts:
+    C-M-b: gh browse .                              # Ctrl-Alt-b: run command directly
+    C-M-e:
+      command: ${VISUAL:-${EDITOR:-vim}} README.md  # exec directly (no shell)
+      window: true                                  # open in a new-window
+    E:
+      send-keys: ${VISUAL:-${EDITOR:-vim}} .        # send-keys (runs in a new shell)
+      zoom: false                                   # do not zoom (default: true for splits)
+  tmux_config:
+    project-settings: |
+      set -g status-style bg=blue
+```
+
+### Shortcuts
+
+Shortcuts bind tmux keys to commands:
+
+- **`C-M-*` keys** are bound globally (no prefix needed)
+- **Other keys** require the tmux prefix (`C-t`)
+- **`command:`** executes directly (default for string values)
+- **`send-keys:`** sends the command to a new shell (supports shell expansion)
+- **`window: true`** opens in a new window instead of a split
+- **`zoom: false`** disables auto-zoom on splits (default: true)
+
+### tmux_config
+
+Entries under `tmux_config:` are written as `tmux.optmux-extras.{name}.conf` files and auto-sourced by tmux.
+
+### Personal config (`~/.optmux.yaml`)
+
+Create `~/.optmux.yaml` to define personal defaults that apply to all optmux sessions:
+
+```yaml
+optmux:
+  shortcuts:
+    C-M-g: lazygit
+  tmux_config:
+    my-defaults: |
+      set -g status-style bg=green
+```
+
+Personal config is merged with per-project config. When both define the same key, **personal settings take precedence**.
+
+### Customization
+
+- Edit `tmux/tmux.conf` to change tmux settings
+- Drop `tmux/tmux.mysetup.conf` files for additional config (auto-sourced)
+- Run `tmux/plugins-update.sh` from inside tmux to update plugins
+- Press `prefix + R` to reload the config
+
+### Environment variables
+
+optmux sets these before launching tmux/tmuxp:
+
+| Variable | Value |
+|---|---|
+| `OPTMUX_DIR` | Absolute path to the `.$NAME.optmux.d/` directory |
+| `OPTMUX_NAME` | Name derived from YAML filename or cwd (e.g., `myproject`) |
+| `TMUX_PLUGIN_MANAGER_PATH` | `$OPTMUX_DIR/tmux/plugins` |
+
+## Development
+
+```bash
+# install the latest main branch
+uvx git+https://github.com/netj/optmux.git
+
+# local editable install for development
+uv tool install -e .
+
+# test any local changes directly (best for testing branches)
+uv run optmux ./example.optmux.yaml
+```
+
+## License
+
+[MIT](LICENSE)

optmux-0.1.0/README.md

@@ -0,0 +1,202 @@
+# optmux
+
+<p align="center">
+  <img src="optmux.svg" width="192" alt="optmux logo">
+</p>
+
+Optimal, opinionated, batteries-included TMUX that's neat and easy for any project.
+
+A [tmuxp](https://tmuxp.git-pull.com) wrapper that creates per-project tmux config directories with [TPM](https://github.com/tmux-plugins/tpm) and plugins pre-configured.
+
+## Quick Start
+
+```bash
+# run optmux anywhere (installs on first use via uv)
+uvx optmux
+
+# strongly recommended: install wtcode + lazygit for the full experience
+brew install netj/tap/optmux
+```
+
+Try the included example:
+
+```bash
+git clone https://github.com/netj/optmux.git && cd optmux
+./example.optmux.yaml
+```
+
+On first run, optmux will:
+
+1. Create `.example.optmux.d/tmux/` next to the YAML file
+2. Seed a default `tmux.conf` with TPM and plugins
+3. Install TPM and all plugins (visible in window 0)
+4. Launch tmuxp with an isolated tmux server
+
+## Usage
+
+### With a tmuxp YAML file
+
+Supports `.optmux.yaml`, `.tmuxp.yaml`, and `.optmuxp.yaml` extensions:
+
+```bash
+optmux myproject.optmux.yaml
+optmux myproject.tmuxp.yaml
+```
+
+### Without arguments
+
+```bash
+optmux
+```
+
+Opens plain `tmux` using `.optmux.d/` in the current directory — useful for a quick, isolated tmux session with the bundled config.
+
+### As a shebang
+
+Write a [tmuxp YAML config](https://tmuxp.git-pull.com/configuration/) with the optmux shebang line and make it executable:
+
+```yaml
+#!/usr/bin/env -S uvx optmux
+session_name: myproject
+windows:
+  - window_name: editor
+    panes:
+      - vim .
+  - window_name: shell
+    panes:
+      - ""
+```
+
+```bash
+chmod +x myproject.optmux.yaml
+./myproject.optmux.yaml
+```
+
+## Example tmuxp YAML
+
+Here's the included [`example.optmux.yaml`](example.optmux.yaml) showing shortcuts, tmux config, and window layout:
+
+```yaml
+#!/usr/bin/env -S uvx optmux
+session_name: example
+start_directory: .
+
+optmux:
+  shortcuts:
+    C-M-b: gh browse .
+    C-M-e:
+      command: ${VISUAL:-${EDITOR:-vim}} README.md  # exec directly (default for str, no latency)
+      window: true                                  # in a new-window
+    E:
+      send-keys: ${VISUAL:-${EDITOR:-vim}} .        # send-keys (given command is run in a new shell)
+      zoom: false                                   # do not zoom (defaults to zoom when split-window)
+  tmux_config:
+    project-settings: |
+      set -g status-style bg=blue
+
+windows:
+  - window_name: editor
+    panes:
+      - vim .
+  - window_name: shell
+    panes:
+      - ""
+  - window_name: logs
+    panes:
+      - tail -f /var/log/system.log
+```
+
+## Config directory
+
+Each project gets its own `.$NAME.optmux.d/` directory:
+
+| Path | Purpose |
+|---|---|
+| `tmux/tmux.conf` | Main tmux config (editable after creation) |
+| `tmux/tmux.*.conf` | Additional config files you can add |
+| `tmux/tmux.sock` | Tmux server socket (isolates this project) |
+| `tmux/plugins/` | TPM plugin directory |
+| `tmux/plugins-update.sh` | Run manually to update all plugins |
+
+## optmux YAML config
+
+Add an `optmux:` section to your tmuxp YAML to configure shortcuts and tmux settings:
+
+```yaml
+optmux:
+  shortcuts:
+    C-M-b: gh browse .                              # Ctrl-Alt-b: run command directly
+    C-M-e:
+      command: ${VISUAL:-${EDITOR:-vim}} README.md  # exec directly (no shell)
+      window: true                                  # open in a new-window
+    E:
+      send-keys: ${VISUAL:-${EDITOR:-vim}} .        # send-keys (runs in a new shell)
+      zoom: false                                   # do not zoom (default: true for splits)
+  tmux_config:
+    project-settings: |
+      set -g status-style bg=blue
+```
+
+### Shortcuts
+
+Shortcuts bind tmux keys to commands:
+
+- **`C-M-*` keys** are bound globally (no prefix needed)
+- **Other keys** require the tmux prefix (`C-t`)
+- **`command:`** executes directly (default for string values)
+- **`send-keys:`** sends the command to a new shell (supports shell expansion)
+- **`window: true`** opens in a new window instead of a split
+- **`zoom: false`** disables auto-zoom on splits (default: true)
+
+### tmux_config
+
+Entries under `tmux_config:` are written as `tmux.optmux-extras.{name}.conf` files and auto-sourced by tmux.
+
+### Personal config (`~/.optmux.yaml`)
+
+Create `~/.optmux.yaml` to define personal defaults that apply to all optmux sessions:
+
+```yaml
+optmux:
+  shortcuts:
+    C-M-g: lazygit
+  tmux_config:
+    my-defaults: |
+      set -g status-style bg=green
+```
+
+Personal config is merged with per-project config. When both define the same key, **personal settings take precedence**.
+
+### Customization
+
+- Edit `tmux/tmux.conf` to change tmux settings
+- Drop `tmux/tmux.mysetup.conf` files for additional config (auto-sourced)
+- Run `tmux/plugins-update.sh` from inside tmux to update plugins
+- Press `prefix + R` to reload the config
+
+### Environment variables
+
+optmux sets these before launching tmux/tmuxp:
+
+| Variable | Value |
+|---|---|
+| `OPTMUX_DIR` | Absolute path to the `.$NAME.optmux.d/` directory |
+| `OPTMUX_NAME` | Name derived from YAML filename or cwd (e.g., `myproject`) |
+| `TMUX_PLUGIN_MANAGER_PATH` | `$OPTMUX_DIR/tmux/plugins` |
+
+## Development
+
+```bash
+# install the latest main branch
+uvx git+https://github.com/netj/optmux.git
+
+# local editable install for development
+uv tool install -e .
+
+# test any local changes directly (best for testing branches)
+uv run optmux ./example.optmux.yaml
+```
+
+## License
+
+[MIT](LICENSE)

optmux-0.1.0/optmux/__init__.py

@@ -0,0 +1 @@
+"""optmux — tmuxp wrapper with per-workflow tmux config directories."""

optmux-0.1.0/optmux/cli.py

@@ -0,0 +1,149 @@
+import os
+import shutil
+import subprocess
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+
+def load_optmux_conf():
+    """Load personal optmux config from ~/.optmux.yaml if it exists."""
+    conf_path = Path.home() / ".optmux.yaml"
+    if conf_path.exists():
+        with open(conf_path) as f:
+            data = yaml.safe_load(f) or {}
+        return data.get("optmux") or {}
+    return {}
+
+
+def merge_optmux(project, personal):
+    """Merge project and personal optmux configs (personal wins)."""
+    merged = {}
+    for key in ("shortcuts", "tmux_config"):
+        proj = project.get(key) or {}
+        pers = personal.get(key) or {}
+        if proj or pers:
+            merged[key] = {**proj, **pers}
+    return merged
+
+
+def generate_tmux_conf_files(tmux_dir, optmux):
+    """Generate tmux conf files from merged optmux config."""
+    # clear all managed files first to avoid stale configs
+    for conf_file in tmux_dir.glob("tmux.optmux-*.conf"):
+        conf_file.unlink()
+
+    # optmux.shortcuts → tmux.optmux-shortcuts.conf
+    shortcuts = optmux.get("shortcuts") or {}
+    if shortcuts:
+        lines = []
+        for key, value in shortcuts.items():
+            bind = "bind -n" if key.startswith("C-M-") else "bind"
+            # normalize str to dict
+            if isinstance(value, str):
+                opts = {"command": value}
+            elif isinstance(value, dict):
+                opts = value
+            else:
+                continue
+            use_window = opts.get("new-window", False)
+            use_zoom = opts.get("zoom", True)
+            open_cmd = "new-window" if use_window else "split-window -v"
+            # build the tmux action
+            if "send-keys" in opts:
+                escaped = opts["send-keys"].replace("'", "'\\''")
+                action = f"{open_cmd} -c '#{{pane_current_path}}' \\; send-keys '{escaped}' Enter"
+            elif "command" in opts:
+                escaped = opts["command"].replace("'", "'\\''")
+                action = f"{open_cmd} -c '#{{pane_current_path}}' '{escaped}'"
+            else:
+                continue
+            if use_zoom and not use_window:
+                action += " \\; resize-pane -Z"
+            lines.append(f"{bind} {key} {action}\n")
+        (tmux_dir / "tmux.optmux-shortcuts.conf").write_text("".join(lines))
+
+    # optmux.tmux_config → tmux.optmux-extras.{name}.conf for each entry
+    tmux_config = optmux.get("tmux_config") or {}
+    for conf_name, content in tmux_config.items():
+        (tmux_dir / f"tmux.optmux-extras.{conf_name}.conf").write_text(content)
+
+
+def main():
+    if len(sys.argv) > 1:
+        # optmux NAME.optmux.yaml [TMUXP_ARGS...]
+        tmuxp_yaml = sys.argv[1]
+        remaining_args = sys.argv[2:]
+
+        yaml_path = Path(tmuxp_yaml).resolve()
+        yaml_dir = yaml_path.parent
+
+        # strip .yaml, then .tmuxp, then .optmux suffixes
+        name = yaml_path.stem
+        for suffix in (".tmuxp", ".optmux", ".optmuxp"):
+            if name.endswith(suffix):
+                name = name[: -len(suffix)]
+
+        optmux_dir = yaml_dir / f".{name}.optmux.d"
+    else:
+        # optmux (no args) — just open tmux in cwd
+        name = Path.cwd().name
+        optmux_dir = Path.cwd() / ".optmux.d"
+
+    tmux_dir = optmux_dir / "tmux"
+    tmux_dir.mkdir(parents=True, exist_ok=True)
+
+    # seed bundled files if not present
+    bundled = files("optmux").joinpath("data")
+    tmux_conf = tmux_dir / "tmux.conf"
+    shutil.copy2(bundled / "tmux.conf", tmux_conf)  # always regenerated; use tmux.*.conf for customizations
+    setup_script = tmux_dir / "plugins-update.sh"
+    if not setup_script.exists():
+        shutil.copy2(bundled / "plugins-update.sh", setup_script)
+        setup_script.chmod(0o755)
+    tips_script = tmux_dir / "tips.sh"
+    if not tips_script.exists():
+        shutil.copy2(bundled / "tips.sh", tips_script)
+        tips_script.chmod(0o755)
+
+    # generate tmux conf files from optmux YAML merged with personal config
+    personal = load_optmux_conf()
+    if len(sys.argv) > 1:
+        with open(yaml_path) as f:
+            data = yaml.safe_load(f) or {}
+        project = data.get("optmux") or {}
+        optmux = merge_optmux(project, personal)
+    else:
+        optmux = personal
+    generate_tmux_conf_files(tmux_dir, optmux)
+
+    # ensure scripts from optmux's own venv (e.g., tmuxp) are on PATH
+    venv_bin = str(Path(sys.executable).parent)
+    os.environ["PATH"] = venv_bin + os.pathsep + os.environ.get("PATH", "")
+
+    os.environ["OPTMUX_DIR"] = str(optmux_dir)
+    os.environ["OPTMUX_NAME"] = name
+    os.environ["TMUX_PLUGIN_MANAGER_PATH"] = str(tmux_dir / "plugins")
+
+    # bootstrap TPM (clone only); plugin install happens inside tmux via tmux.conf
+    subprocess.run([str(setup_script)], check=True)
+
+    sock = str(tmux_dir / "tmux.sock")
+    conf = str(tmux_conf)
+
+    if len(sys.argv) > 1:
+        os.execvp(
+            "tmuxp",
+            ["tmuxp", "load", "--yes", "-S", sock, "-f", conf, tmuxp_yaml, *remaining_args],
+        )
+    else:
+        # attach to existing session on this socket, or create a new one
+        has_session = subprocess.run(
+            ["tmux", "-S", sock, "has-session"],
+            capture_output=True,
+        ).returncode == 0
+        if has_session:
+            os.execvp("tmux", ["tmux", "-S", sock, "attach-session"])
+        else:
+            os.execvp("tmux", ["tmux", "-S", sock, "-f", conf, "new-session", "-s", f"optmux {name}"])

optmux-0.1.0/optmux/data/plugins-update.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# optmux tmux plugin setup/update script
+# Bootstraps TPM, installs missing plugins, and updates all plugins.
+# Run manually to update: ./path/to/workflow.optmux.d/tmux/plugins-update.sh
+set -euo pipefail
+
+: ${OPTMUX_DIR:="$(cd "$(dirname "$0")/.."; pwd)"}
+: ${TMUX_PLUGIN_MANAGER_PATH:="$OPTMUX_DIR/tmux/plugins"}
+export TMUX_PLUGIN_MANAGER_PATH
+export XDG_CONFIG_HOME="$OPTMUX_DIR"
+
+tpm=netj/tpm  # XXX using netj/tpm fork; TODO switch back to tmux-plugins/tpm
+
+if [[ ! -x "$TMUX_PLUGIN_MANAGER_PATH"/$tpm/tpm ]]; then
+    echo "optmux: installing TPM ($tpm)..."
+    git clone https://github.com/$tpm "$TMUX_PLUGIN_MANAGER_PATH"/$tpm
+fi
+
+if [[ -n "${TMUX:-}" ]]; then
+    echo "optmux: installing/updating tmux plugins..."
+    "$TMUX_PLUGIN_MANAGER_PATH"/$tpm/bin/install_plugins
+    "$TMUX_PLUGIN_MANAGER_PATH"/$tpm/bin/update_plugins all
+    # reload config to activate newly installed/updated plugins
+    tmux source-file "$OPTMUX_DIR/tmux/tmux.conf"
+fi

optmux-0.1.0/optmux/data/tips.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# optmux tips — shows key binding cheatsheet and hints
+set -euo pipefail
+
+: ${OPTMUX_DIR:="$(cd "$(dirname "$0")/.."; pwd)"}
+dismissed="$OPTMUX_DIR/tmux/.tips-dismissed"
+
+# check suppression
+if [[ -e "$dismissed" ]]; then
+    if grep -q '^forever$' "$dismissed" 2>/dev/null; then
+        exit 0
+    fi
+    # skip if dismissed less than 7 days ago
+    if find "$dismissed" -mtime -7 -print -quit 2>/dev/null | grep -q .; then
+        exit 0
+    fi
+fi
+
+# nerd font hint
+nerd_font_tip=""
+if ! fc-list : family 2>/dev/null | grep -qi 'Nerd Font'; then
+    nerd_font_tip="
+  [!] Install a Nerd Font for best experience
+      https://www.nerdfonts.com"
+fi
+
+clear
+cat <<EOF
+
+
+                            optmux tips
+
+  Prefix: Ctrl+T  (C-t)
+
+  Workflow:  C-M-c  wtcode   or   C-M-f  find file to open editor
+          -> C-M-g  lazygit  to check diff/commits
+          -> C-M-o  cycle between panes   or   q  to return
+          -> C-M-s  shell in same dir (run tests, one-off commands)
+
+  Install:  brew install netj/tap/wtcode   https://github.com/netj/wtcode
+            brew install lazygit          https://github.com/jesseduffield/lazygit
+
+  C-t C-t   last window        C-M-h/j/k/l  navigate panes
+  C-t C-c   new window         C-M-z         quick toggle zoom
+  C-t C-n/p next/prev window   C-M-\\         last pane
+  C-t n/p   next/prev w/ bell  C-M-o         prev pane + zoom
+  C-t z     toggle zoom
+  C-t o     cycle panes
+  C-t R     reload config
+
+  C-t t     send prefix to nested tmux
+  C-t T     swap prefix (for nested tmux)
+  copy-mode yank auto-copies to system clipboard (OSC 52)
+${nerd_font_tip}
+
+  q/Enter: dismiss    d: dismiss for a week    D: dismiss forever
+
+EOF
+
+# wait for user input
+while true; do
+    read -rsn1 key
+    case "$key" in
+        q|"")
+            break
+            ;;
+        d)
+            touch "$dismissed"
+            break
+            ;;
+        D)
+            echo "forever" > "$dismissed"
+            break
+            ;;
+    esac
+done

optmux-0.1.0/optmux/data/tmux.conf

@@ -0,0 +1,141 @@
+# optmux provided "optimal" TMUX configuration for most workflows
+# Origin: https://github.com/netj/dotfiles/blob/main/.tmux.conf
+
+###############################################################################
+# Essential config
+###############################################################################
+# C-t as prefix not C-b b/c it's TMUX not BMUX; moreover, C-b/C-f is essential for EMACS-mode readline in BASH/etc.
+set -g prefix C-t; unbind C-b
+set -g default-command '$SHELL -l'  # ensure starting a login shell
+
+set -g base-index 1
+set -g pane-base-index 1
+
+set -g display-time 2500
+setw -g clock-mode-style 24
+setw -g wrap-search off
+setw -g mouse on
+set -g set-clipboard on        # emit OSC 52 on yank so terminal sets system clipboard
+set -g allow-passthrough on    # let nested/inner programs' OSC 52 reach outer terminal (tmux 3.3+)
+setw -g monitor-activity on
+set -g set-titles on
+
+set -g set-titles-string "#T - #I:#W#F#S^#h"
+set -g status-left "#T"
+set -g status-left-length 48
+set -g status-right "#[fg=white,bright]#S#[default]^#[fg=white]#h#[default]"
+set -g status-right-length 16
+set -g  status-style bg=black
+set -ga status-style fg=brightblack
+set -g  status-left-style fg=green,bright
+setw -g window-status-style fg=brightblack
+setw -g window-status-current-style fg=green,bright
+setw -g window-status-activity-style fg=yellow,bright
+setw -g window-status-bell-style fg=red,bright
+setw -g window-status-bell-style fg=red,bright,blink
+setw -g window-status-format " #I:#{b:pane_current_path}#F "
+setw -g window-status-current-format " #I:#{b:pane_current_path}#F "
+
+set -g pane-border-status top
+set -g pane-border-format " #P: #{pane_current_command} | #T "
+
+###############################################################################
+# TPM Plugins
+###############################################################################
+set -g @plugin 'tmux-plugins/tmux-sensible'      # hx limit, mouse, C-n/C-p over awkward n/p
+
+# vim-tmux-navigator with C-M-h/j/k/l (preserving custom bindings)
+set -g @plugin 'tmux-plugins/tmux-pain-control'  # move around panes with j and k, a bit like vim; resize panes like vim
+set -g @plugin 'christoomey/vim-tmux-navigator'
+set -g @vim_navigator_mapping_left "C-M-h"
+set -g @vim_navigator_mapping_down "C-M-j"
+set -g @vim_navigator_mapping_up "C-M-k"
+set -g @vim_navigator_mapping_right "C-M-l"
+set -g @vim_navigator_mapping_prev ""
+set -g @vim_navigator_prefix_mapping_clear_screen ""
+
+set -g @plugin 'tmux-plugins/tmux-copycat'
+set -g @plugin 'tmux-plugins/tmux-yank'
+set -g @plugin 'nhdaly/tmux-better-mouse-mode'
+
+# resurrect
+set -g @plugin 'tmux-plugins/tmux-resurrect'
+set -g @resurrect-strategy-vim 'session'
+set -g @resurrect-capture-pane-contents 'on'
+
+# continuum
+#set -g @plugin 'tmux-plugins/tmux-continuum'
+#set -g @continuum-restore 'on'
+
+set -g @plugin 'netj/claritmux'
+set -g @claritmux_status_workdir   0
+set -g @claritmux_status_date      0
+set -g @claritmux_status_time      0
+set -g @claritmux_status_hostname  1
+
+## Initialize TPM (bootstrap is handled by tmux/plugins-update.sh before tmux starts)
+set -g @tpm 'netj/tpm'  # XXX using my fork netj/tpm for now; TODO switch back to tmux-plugins/tpm once merging outstanding improvements
+set -gF @plugin '#{@tpm}'
+set-environment -g OPTMUX_DIR "$OPTMUX_DIR"
+set-environment -g TMUX_PLUGIN_MANAGER_PATH "$OPTMUX_DIR/tmux/plugins"
+run 'export XDG_CONFIG_HOME="$OPTMUX_DIR"; tpm=$(tmux show -gv @tpm); "$TMUX_PLUGIN_MANAGER_PATH"/$tpm/tpm'
+# Window 0: plugins update + tips pane
+set-hook -g session-created 'new-window -t 0 -n "optmux" "$OPTMUX_DIR/tmux/tips.sh" ; split-window -t 0 -v "$OPTMUX_DIR/tmux/plugins-update.sh"'
+
+###############################################################################
+# Essential config, continued; also compensating plugin
+###############################################################################
+
+## reload optmux config (overrides tmux-sensible's R which reloads ~/.tmux.conf)
+bind R source-file "$OPTMUX_DIR/tmux/tmux.conf" \; display-message "optmux: reloaded $OPTMUX_DIR/tmux/tmux.conf"
+
+## easier session/window actions
+unbind ^D; bind ^D detach           # easier detach w/ Ctrl
+unbind ^C; bind ^C new-window -c "#{pane_current_path}"  # easier new window
+unbind  C; bind  C new-session      # easier new session
+bind Tab attach-session -d          # easier to detach all other clients to make this client the only one
+bind ` confirm-before kill-session  # easier kill-session
+
+## settings for TMUX in TMUX windows/panes
+# C-t t to send prefix is a more sensible escaping scheme than TMUX or tmux-plugins/tmux-sensible's default
+# b/c when using TMUX in TMUX (double-decker or more), you really don't want to press C-t 2^k times but just press C-t once followed by the t key only k times for sending the prefix key to the k-th inner/nested TMUX sessions
+unbind C-t; bind C-t last-window
+unbind   t; bind   t send-prefix
+# swap outer TMUX prefix to a different one to let the usual prefix directly reach the inner TMUX
+bind T \
+    if-shell "[ \"`tmux show-options prefix`\" = 'prefix C-t' ]" \
+        "set prefix C-s; unbind -n M-Up;           unbind -n M-PageUp" \
+        "set prefix C-t;   bind -n M-Up copy-mode;   bind -n M-PageUp copy-mode" \
+        #
+
+## easier window selection with an alert ("bell") via lifting Ctrl (NOTE prefix C-n/C-p in tmux-sensible selects all windows)
+bind n run-shell 'wc=#{window_index} ws=$(tmux list-windows -F "##{?window_bell_flag, ,@}##{window_index}"); wb=$({ echo "$ws"; echo "$ws"; } | grep -A9999 ".$wc\$" | tail -n +2 | grep "^ " | head -1); if [[ -n $wb ]]; then tmux select-window -t $wb; else tmux next-window; fi'
+bind p run-shell 'wc=#{window_index} ws=$(tmux list-windows -F "##{?window_bell_flag, ,@}##{window_index}"); wb=$({ echo "$ws"; echo "$ws"; } | grep -B9999 ".$wc\$" | head -n -1 | grep "^ " | tail -1); if [[ -n $wb ]]; then tmux select-window -t $wb; else tmux previous-window; fi'
+
+## easier pane selection/rotation (default is not symmetric and a bit awkward)
+bind C-o select-pane -t :.+
+bind   o select-pane -t :.-
+bind   O rotate-window
+bind M-o rotate-window -D
+
+## Ctrl+Opt/Alt: quicker access to frequently used prefix combos
+bind -n C-M-z  resize-pane -Z  # quick toggle zoom pane          (normally prefix z)
+bind -n C-M-\\ select-pane -l \; resize-pane -Z  # quick switching btwn last panes (normally prefix ;) cf. vim_navigator_mapping_prev
+bind -n C-M-o  select-pane -t :.-\; resize-pane -Z  # switch to prev pane and also zoom
+# quicker split
+bind -n C-M-s split-window -v -c "#{pane_current_path}"            \; resize-pane -Z
+
+# quick commands in new pane with Ctrl+Opt
+bind -n C-M-c split-window -v -c "#{pane_current_path}" wtcode     \; resize-pane -Z
+bind -n C-M-f split-window -v -c "#{pane_current_path}" '${VISUAL:-${EDITOR:-vim}} $(fzf || echo .)' \; resize-pane -Z
+bind -n C-M-g split-window -v -c "#{pane_current_path}" lazygit    \; resize-pane -Z
+
+
+###############################################################################
+# Local config
+###############################################################################
+# Source all tmux.*.conf files from the optmux dir
+if-shell "ls \"$OPTMUX_DIR\"/tmux/tmux.*.conf >/dev/null 2>&1" \
+    "source-file $OPTMUX_DIR/tmux/tmux.*.conf"
+
+# vim:ft=tmux

optmux-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "optmux"
+version = "0.1.0"
+description = "Optimal, opinionated, batteries-included TMUX that's neat and easy for any project"
+readme = "README.md"
+authors = [
+    { name = "Jaeho Shin", email = "netj@sparcs.org" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "tmuxp",
+]
+
+[project.scripts]
+optmux = "optmux.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""