@jx0/jmux 0.2.0 → 0.3.0

package/README.md

@@ -14,7 +14,7 @@ You lose context constantly. You forget what's running where. You can't see at a
 
 ## The Solution
 
-jmux wraps tmux with a persistent sidebar that shows all your sessions, all the time. It doesn't replace tmux — it sits alongside it. Your keybindings, your panes, your workflow. Everything works exactly like before, plus a sidebar.
+jmux wraps tmux with a persistent sidebar that shows all your sessions, all the time. It works with your existing `~/.tmux.conf` — your plugins, your colors, your keybindings — and layers a sidebar on top.
 
 **What you get:**
 - Every session visible at all times with git branch and window count
@@ -23,7 +23,7 @@ jmux wraps tmux with a persistent sidebar that shows all your sessions, all the
 - Activity indicators (green dot) and attention flags (orange `!`) for agentic workflows
 - Mouse click to switch sessions
 - New session modal with fuzzy directory picker
-- A self-contained tmux distribution — ships its own config, doesn't touch `~/.tmux.conf`
+- Bring your own `~/.tmux.conf` — your plugins and keybindings just work
 
 ![jmux sidebar alongside vim with split panes and a dev server](docs/screenshots/blog.png)
 
@@ -31,7 +31,7 @@ jmux wraps tmux with a persistent sidebar that shows all your sessions, all the
 
 jmux owns the terminal. It spawns tmux in a PTY, feeds the output through a headless terminal emulator ([xterm.js](https://xtermjs.org/)), and composites a 24-column sidebar alongside the tmux rendering. A separate tmux control mode connection provides real-time session metadata via push notifications.
 
-Your tmux is unmodified. Sessions, windows, panes, keybindings — all unchanged. jmux just adds a persistent view of what's happening across your projects.
+jmux sources your `~/.tmux.conf` first, then layers its own defaults and the few settings the sidebar requires. Your existing setup carries over — jmux just adds the sidebar.
 
 ```
 ┌─ jmux sidebar ──┬─ your normal tmux ──────────────────────┐
@@ -144,7 +144,7 @@ The session is created in the selected directory and the sidebar updates immedia
 |-----|--------|
 | `Ctrl-a \|` | Split horizontal |
 | `Ctrl-a -` | Split vertical |
-| `Shift-arrows` | Navigate panes (vim-aware via smart-splits) |
+| `Shift-arrows` | Navigate panes |
 | `Ctrl-a arrows` | Resize panes |
 | `Ctrl-a P` | Toggle pane border titles |
 
@@ -185,17 +185,25 @@ jmux shows an orange `!` indicator. When you switch to that session, the flag cl
 4. Work in one session while others run in the background
 5. Orange `!` flags appear when Claude finishes — switch instantly with `Ctrl-Shift-Down`
 
-## Self-Contained Config
+## Configuration
 
-jmux ships its own `config/tmux.conf`. It never reads `~/.tmux.conf`. This means:
+jmux loads config in three layers:
 
-- Your existing tmux setup is untouched
-- Every jmux user gets the same keybindings and behavior
-- No plugin manager needed — everything is built in
-- The status bar shows only window tabs (session info is in the sidebar)
-- Windows auto-rename to the running command (`vim`, `zsh`, `bun`, etc.)
+```
+config/defaults.conf      ← jmux defaults (baseline)
+~/.tmux.conf              ← your config (overrides defaults)
+config/core.conf          ← jmux requirements (always wins)
+```
+
+jmux defaults are applied first as a baseline. Your `~/.tmux.conf` is sourced next — anything you set overrides the defaults. Finally, the core settings the sidebar depends on are applied last and cannot be overridden.
+
+**Core settings** (cannot be overridden):
+- `detach-on-destroy off` — switch to next session on kill, don't exit jmux
+- `mouse on` — required for sidebar clicks
+- `prefix + n` — new session modal
+- Empty `status-left` — session info is in the sidebar
 
-The config is fully customizable — see [docs/configuration.md](docs/configuration.md) for details.
+Everything else is yours to customize. See [docs/configuration.md](docs/configuration.md) for details.
 
 ## Architecture
 

package/config/core.conf

@@ -0,0 +1,17 @@
+# jmux core — required settings that jmux depends on.
+# These are sourced LAST and override any user config.
+# Do not edit unless you know what you're doing.
+
+# Session lifecycle — jmux expects to switch sessions, not detach
+set -g detach-on-destroy off
+
+# Mouse — required for sidebar click handling
+set -g mouse on
+
+# New session modal — bound to prefix+n
+unbind n
+bind-key n display-popup -E -w 60% -h 70% -b heavy -S 'fg=#4f565d' "$JMUX_DIR/config/new-session.sh"
+
+# Status bar — session info is in the sidebar, keep status bar for windows only
+set -g status-left ""
+set -g status-left-length 0

package/config/defaults.conf

@@ -0,0 +1,106 @@
+# jmux default configuration
+# Opinionated defaults — override anything here via ~/.tmux.conf
+
+# --- Prefix ---
+set -g prefix C-a
+unbind C-b
+bind-key C-a send-prefix
+
+unbind p  # free up for future use
+
+# --- Windows ---
+set -g base-index 1
+set -g pane-base-index 1
+set -g renumber-windows on
+set -g automatic-rename on
+set -g automatic-rename-format "#{pane_current_command}"
+bind c new-window -c ~
+bind -n C-Right next-window
+bind -n C-Left previous-window
+
+# Reorder windows with Ctrl-Shift-Left/Right
+bind-key -n C-S-Left run-shell 'W=#{window_index}; T=$((W-1)); [ $T -ge 1 ] && tmux swap-window -s ":$W" -t ":$T" && tmux select-window -t ":$T"'
+bind-key -n C-S-Right run-shell 'W=#{window_index}; T=$((W+1)); MAX=$(tmux list-windows | wc -l | tr -d " "); [ $T -le $MAX ] && tmux swap-window -s ":$W" -t ":$T" && tmux select-window -t ":$T"'
+
+# --- Panes ---
+bind | split-window -h -c "#{pane_current_path}"
+bind - split-window -v -c "#{pane_current_path}"
+unbind '"'
+unbind %
+bind -r Left resize-pane -L 5
+bind -r Down resize-pane -D 5
+bind -r Up resize-pane -U 5
+bind -r Right resize-pane -R 5
+
+# Smart-splits.nvim integration
+is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|l?n?vim?x?|fzf)(diff)?$'"
+bind -n S-Left if-shell "$is_vim" "send-keys S-Left" "select-pane -L"
+bind -n S-Right if-shell "$is_vim" "send-keys S-Right" "select-pane -R"
+bind -n S-Up if-shell "$is_vim" "send-keys S-Up" "select-pane -U"
+bind -n S-Down if-shell "$is_vim" "send-keys S-Down" "select-pane -D"
+
+# --- Pane borders ---
+set -g pane-border-lines heavy
+set -g pane-border-status off
+set -g pane-border-style 'fg=#3a4450'
+set -g pane-active-border-style 'fg=#4f565d'
+set -g pane-border-format "#{?pane_active, #[fg=#9fe8c3 bold]#{pane_title} #[fg=#b5bcc9 nobold]#{b:pane_current_path} #[fg=#4f565d]| #{pane_current_command} , #[fg=#4f565d]#{pane_title} #[fg=#3a4450]#{b:pane_current_path} | #{pane_current_command} }"
+
+# Auto-show pane borders only when window has multiple panes
+set-hook -g window-layout-changed 'if -F "#{==:#{window_panes},1}" "set -w pane-border-status off" "set -w pane-border-status top"'
+set-hook -g after-select-window 'if -F "#{==:#{window_panes},1}" "set -w pane-border-status off" "set -w pane-border-status top"'
+bind-key P set -w pane-border-status
+
+# --- Window styles ---
+set -g window-style 'fg=#6b7280'
+set -g window-active-style 'fg=#b5bcc9'
+
+# --- Utilities ---
+bind k send-keys -R \; clear-history \; display-message "Pane cleared"
+bind y run-shell "tmux capture-pane -pS - -E - | grep . | pbcopy" \; display-message "Copied pane to clipboard"
+
+# Window switcher popup (C-a j) — jmux overrides this for sidebar mode,
+# but it's still available if sidebar mode changes
+bind-key j display-popup -E -x 0 -y 0 -w 30% -h 100% -b heavy -S 'fg=#4f565d' \
+  "tmux list-windows -F '#I: #W#{?window_active, *, }' | \
+   fzf --reverse --no-info --prompt=' Window> ' --pointer='▸' \
+       --color='bg:#0c1117,fg:#6b7280,hl:#fbd4b8,fg+:#b5bcc9,hl+:#fbd4b8,pointer:#9fe8c3,prompt:#9fe8c3' | \
+   cut -d: -f1 | \
+   xargs -I{} tmux select-window -t :{}"
+
+# --- Terminal ---
+set -g default-terminal "tmux-256color"
+set -g set-clipboard on
+set -g focus-events on
+set -g mouse on
+set -gq status-utf8 on
+set-window-option -gq utf8 on
+set-option -ga terminal-overrides ",xterm-256color:Tc"
+set-option -ga terminal-overrides ',*:Smulx=\E[4::%p1%dm'
+set-option -ga terminal-overrides ',*:Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m'
+
+# --- Bell / Activity ---
+set-window-option -g visual-bell off
+set-window-option -g bell-action other
+set-window-option -g monitor-activity off
+set-window-option -g visual-activity off
+set-hook -g pane-focus-in 'setw monitor-bell off; setw monitor-bell on'
+unbind -T root DoubleClick1Pane
+unbind -T root TripleClick1Pane
+
+# --- Status bar ---
+# Minimal — session indicator handled by jmux sidebar, no system metrics
+set -g status-position bottom
+set -g status-interval 1
+set -g status-justify left
+set -g status-bg "#181f26"
+set -g status-left ""
+set -g status-right ""
+set -g status-left-length 0
+set -g status-right-length 0
+
+# Window tabs
+setw -g window-status-current-format "#[bg=#181f26 fg=#fbd4b8]◢#[bg=#fbd4b8 fg=#131a21] #W #{?window_zoomed_flag,󰊓 ,}#[bg=#181f26 fg=#fbd4b8]◣"
+setw -g window-status-format "#{?window_bell_flag,#[bg=#181f26 fg=#ced4df] #W #{?window_zoomed_flag,󰊓 ,},#[bg=#181f26 fg=#4f565d] #W #{?window_zoomed_flag,󰊓 ,}}"
+set -g window-status-bell-style 'fg=#ced4df,bg=#0c1117'
+set -g window-status-activity-style 'fg=#b5bcc9,bg=#4e555c,bold'

package/config/tmux.conf

@@ -1,113 +1,18 @@
-# jmux tmux configuration
-# Self-contained — does not read ~/.tmux.conf
-
-# --- Prefix ---
-set -g prefix C-a
-unbind C-b
-bind-key C-a send-prefix
-
-# jmux-managed bindings
-bind-key n display-popup -E -w 60% -h 70% -b heavy -S 'fg=#4f565d' "$JMUX_DIR/config/new-session.sh"
-unbind p  # free up for future use
-
-# --- Windows ---
-set -g base-index 1
-set -g pane-base-index 1
-set -g renumber-windows on
-set -g automatic-rename on
-set -g automatic-rename-format "#{pane_current_command}"
-bind c new-window -c ~
-bind -n C-Right next-window
-bind -n C-Left previous-window
-
-# Reorder windows with Ctrl-Shift-Left/Right
-bind-key -n C-S-Left run-shell 'W=#{window_index}; T=$((W-1)); [ $T -ge 1 ] && tmux swap-window -s ":$W" -t ":$T" && tmux select-window -t ":$T"'
-bind-key -n C-S-Right run-shell 'W=#{window_index}; T=$((W+1)); MAX=$(tmux list-windows | wc -l | tr -d " "); [ $T -le $MAX ] && tmux swap-window -s ":$W" -t ":$T" && tmux select-window -t ":$T"'
-
-# --- Panes ---
-bind | split-window -h -c "#{pane_current_path}"
-bind - split-window -v -c "#{pane_current_path}"
-unbind '"'
-unbind %
-bind -r Left resize-pane -L 5
-bind -r Down resize-pane -D 5
-bind -r Up resize-pane -U 5
-bind -r Right resize-pane -R 5
-
-# Smart-splits.nvim integration
-is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|l?n?vim?x?|fzf)(diff)?$'"
-bind -n S-Left if-shell "$is_vim" "send-keys S-Left" "select-pane -L"
-bind -n S-Right if-shell "$is_vim" "send-keys S-Right" "select-pane -R"
-bind -n S-Up if-shell "$is_vim" "send-keys S-Up" "select-pane -U"
-bind -n S-Down if-shell "$is_vim" "send-keys S-Down" "select-pane -D"
-
-# --- Pane borders ---
-set -g pane-border-lines heavy
-set -g pane-border-status off
-set -g pane-border-style 'fg=#3a4450'
-set -g pane-active-border-style 'fg=#4f565d'
-set -g pane-border-format "#{?pane_active, #[fg=#9fe8c3 bold]#{pane_title} #[fg=#b5bcc9 nobold]#{b:pane_current_path} #[fg=#4f565d]| #{pane_current_command} , #[fg=#4f565d]#{pane_title} #[fg=#3a4450]#{b:pane_current_path} | #{pane_current_command} }"
-
-# Auto-show pane borders only when window has multiple panes
-set-hook -g window-layout-changed 'if -F "#{==:#{window_panes},1}" "set -w pane-border-status off" "set -w pane-border-status top"'
-set-hook -g after-select-window 'if -F "#{==:#{window_panes},1}" "set -w pane-border-status off" "set -w pane-border-status top"'
-bind-key P set -w pane-border-status
-
-# --- Window styles ---
-set -g window-style 'fg=#6b7280'
-set -g window-active-style 'fg=#b5bcc9'
-
-# --- Utilities ---
-bind k send-keys -R \; clear-history \; display-message "Pane cleared"
-bind y run-shell "tmux capture-pane -pS - -E - | grep . | pbcopy" \; display-message "Copied pane to clipboard"
-
-# Window switcher popup (C-a j) — jmux overrides this for sidebar mode,
-# but it's still available if sidebar mode changes
-bind-key j display-popup -E -x 0 -y 0 -w 30% -h 100% -b heavy -S 'fg=#4f565d' \
-  "tmux list-windows -F '#I: #W#{?window_active, *, }' | \
-   fzf --reverse --no-info --prompt=' Window> ' --pointer='▸' \
-       --color='bg:#0c1117,fg:#6b7280,hl:#fbd4b8,fg+:#b5bcc9,hl+:#fbd4b8,pointer:#9fe8c3,prompt:#9fe8c3' | \
-   cut -d: -f1 | \
-   xargs -I{} tmux select-window -t :{}"
-
-# --- Session lifecycle ---
-# When a session is killed, switch to the next one instead of detaching.
-# jmux only exits when the last session is destroyed.
-set -g detach-on-destroy off
-
-# --- Terminal ---
-set -g default-terminal "tmux-256color"
-set -g set-clipboard on
-set -g focus-events on
-set -g mouse on
-set -gq status-utf8 on
-set-window-option -gq utf8 on
-set-option -ga terminal-overrides ",xterm-256color:Tc"
-set-option -ga terminal-overrides ',*:Smulx=\E[4::%p1%dm'
-set-option -ga terminal-overrides ',*:Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m'
-
-# --- Bell / Activity ---
-set-window-option -g visual-bell off
-set-window-option -g bell-action other
-set-window-option -g monitor-activity off
-set-window-option -g visual-activity off
-set-hook -g pane-focus-in 'setw monitor-bell off; setw monitor-bell on'
-unbind -T root DoubleClick1Pane
-unbind -T root TripleClick1Pane
-
-# --- Status bar ---
-# Minimal — session indicator handled by jmux sidebar, no system metrics
-set -g status-position bottom
-set -g status-interval 1
-set -g status-justify left
-set -g status-bg "#181f26"
-set -g status-left ""
-set -g status-right ""
-set -g status-left-length 0
-set -g status-right-length 0
-
-# Window tabs
-setw -g window-status-current-format "#[bg=#181f26 fg=#fbd4b8]◢#[bg=#fbd4b8 fg=#131a21] #W #{?window_zoomed_flag,󰊓 ,}#[bg=#181f26 fg=#fbd4b8]◣"
-setw -g window-status-format "#{?window_bell_flag,#[bg=#181f26 fg=#ced4df] #W #{?window_zoomed_flag,󰊓 ,},#[bg=#181f26 fg=#4f565d] #W #{?window_zoomed_flag,󰊓 ,}}"
-set -g window-status-bell-style 'fg=#ced4df,bg=#0c1117'
-set -g window-status-activity-style 'fg=#b5bcc9,bg=#4e555c,bold'
+# jmux tmux configuration loader
+#
+# Source order:
+#   1. jmux defaults — opinionated keybindings, colors, status bar
+#   2. User's ~/.tmux.conf (if it exists) — overrides defaults
+#   3. jmux core — required settings that jmux depends on (sourced last, wins)
+#
+# Users can override any default in ~/.tmux.conf. Only core settings
+# (mouse, detach-on-destroy, prefix+n) cannot be overridden.
+
+# Step 1: jmux defaults (baseline)
+source-file "$JMUX_DIR/config/defaults.conf"
+
+# Step 2: User config (overrides defaults)
+if-shell "test -f ~/.tmux.conf" "source-file ~/.tmux.conf"
+
+# Step 3: jmux core (non-negotiable — must be last)
+source-file "$JMUX_DIR/config/core.conf"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jx0/jmux",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A persistent session sidebar for tmux",
   "type": "module",
   "bin": {

package/src/main.ts

@@ -12,7 +12,7 @@ import { homedir } from "os";
 
 // --- CLI commands (run and exit before TUI) ---
 
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 
 const HELP = `jmux — a persistent session sidebar for tmux