@jx0/jmux 0.3.9 → 0.5.0

package/README.md

@@ -4,12 +4,12 @@
 
 **The terminal workspace for agentic development.**
 
-A tmux environment built for running coding agents in parallel — with a persistent sidebar that shows every session, what's running, and what needs your attention.
+Run coding agents in parallel from your terminal. A persistent sidebar shows every session, what's running, and what needs your attention — without leaving the tools you already use.
 
 [![npm](https://img.shields.io/npm/v/@jx0/jmux)](https://www.npmjs.com/package/@jx0/jmux)
 [![license](https://img.shields.io/github/license/jarredkenny/jmux)](LICENSE)
 
-![jmux sidebar with grouped sessions alongside vim and server logs](docs/screenshots/hero.png)
+![jmux sidebar with grouped sessions alongside vim and Claude Code](docs/screenshots/hero.png)
 
 </div>
 
@@ -26,47 +26,64 @@ Requires [Bun](https://bun.sh) 1.2+, [tmux](https://github.com/tmux/tmux) 3.2+,
 
 ## Why
 
-tmux sessions are invisible. You have 30 of them, but the status bar shows one name. To switch, you `prefix-s`, scan a wall of text, and hope you remember what's where.
+GUI agent orchestrators are 100MB+ Electron apps that lock you into their editor, their diff viewer, their Git workflow. They work on one platform. They'll charge you eventually.
 
-jmux fixes this with a persistent sidebar that shows every session, all the time.
+jmux takes the opposite approach: it's a thin orchestration layer over tmux — the tool you already know. Your editor, your Git workflow, your shell, your tools. jmux just makes them visible and navigable when you're running 10+ agents in parallel.
+
+| | jmux | GUI orchestrators |
+|---|---|---|
+| **Size** | ~0.3 MB | ~100+ MB |
+| **Platform** | Anywhere tmux runs (macOS, Linux, SSH, containers) | macOS only |
+| **Editor** | Yours (vim, emacs, VS Code, whatever) | Built-in (take it or leave it) |
+| **Git** | `git`, `gh`, lazygit, [wtm](https://github.com/jarredkenny/worktree-manager), your workflow | Built-in GUI (their workflow) |
+| **Agents** | Any (Claude Code, Codex, aider, custom) | Bundled subset |
+| **Lock-in** | None — it's tmux underneath | Proprietary workspace format |
+| **Cost** | Free, open source | Free today, VC-funded |
 
 ## Features
 
 ### Session Sidebar
 
-Every session visible at a glance — name, window count, git branch. Sessions sharing a parent directory are automatically grouped under a header.
+Every session visible at a glance — name, window count, git branch. Sessions sharing a parent directory are automatically grouped under a header. Mouse wheel scrolling when sessions overflow.
 
-- Green `▎` left marker on the active session
+- Green `▎` marker + highlighted background on the active session
 - Green `●` dot for sessions with new output
-- Orange `!` flag for attention (set programmatically)
+- Orange `!` flag for attention (e.g., an agent finished and needs review)
+
+### Smart Window & Pane Titles
+
+Window tabs auto-name to the working directory. Pane borders show the running command with automatic detection for tools like Claude Code. No more tabs full of `zsh` or garbled version strings.
 
 ### Instant Switching
 
-`Ctrl-Shift-Up/Down` moves between sessions with zero delay. No prefix key, no menu, no mode to enter. Or just click a session in the sidebar.
+`Ctrl-Shift-Up/Down` moves between sessions with zero delay. No prefix key, no menu, no mode to enter. Or just click a session in the sidebar. Indicators only clear when you actually interact with a session — not when you're cycling through.
 
 ### New Session Modal
 
 `Ctrl-a n` opens a two-step fzf flow: fuzzy-search your git repos for a directory, then name the session. Pre-filled with the directory basename.
 
-### Window Picker
+### Bring Your Own Everything
 
-`Ctrl-a j` opens a full-height fzf popup with every window in the current session. Type to filter, Enter to switch.
+jmux works with your existing `~/.tmux.conf`. Your plugins, theme, prefix key, and custom bindings carry over. jmux applies its defaults first, then your config overrides them. Only a small set of core settings are enforced.
 
-![fzf window picker popup](docs/screenshots/window-picker.png)
+Use any editor. Any Git tool. Any AI agent. Any shell. jmux doesn't replace your tools — it organizes them.
 
-### Bring Your Own Config
+### Works Great With
 
-jmux works with your existing `~/.tmux.conf`. Your plugins, theme, prefix key, and custom bindings carry over — jmux applies its defaults first, then your config overrides them. Only a small set of core settings the sidebar needs are enforced.
+- **[wtm](https://github.com/jarredkenny/worktree-manager)** — Git worktree manager. Create isolated worktrees for each agent, one session per branch. `wtm create feature-auth --from main` + jmux = parallel agents on parallel branches.
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — AI coding agent with built-in attention flag support.
+- **[lazygit](https://github.com/jesseduffield/lazygit)** — Terminal Git UI. Run it in a jmux pane alongside your agent.
+- **[gh](https://cli.github.com/)** / **[glab](https://gitlab.com/gitlab-org/cli)** — GitHub and GitLab CLIs for PRs, issues, and reviews without leaving the terminal.
 
-### Claude Code Integration
+### Agent Integration
 
-Built for agentic workflows. Run Claude Code in multiple sessions and get notified when each one finishes.
+Built for running multiple coding agents in parallel. One command sets up attention notifications:
 
 ```bash
 jmux --install-agent-hooks
 ```
 
-One command adds a hook to `~/.claude/settings.json`. When Claude finishes a response, the orange `!` appears on that session. Switch to it, review the work, move on. See [docs/claude-code-integration.md](docs/claude-code-integration.md) for details.
+When Claude Code finishes a response, the orange `!` appears on that session in the sidebar. Switch to it, review the work, move on. Works with any agent that can run a shell command on completion. See [docs/claude-code-integration.md](docs/claude-code-integration.md) for details.
 
 ---
 
@@ -81,6 +98,7 @@ One command adds a hook to `~/.claude/settings.json`. When Claude finishes a res
 | `Ctrl-a r` | Rename session |
 | `Ctrl-a m` | Move window to another session |
 | Click sidebar | Switch to session |
+| Scroll wheel (sidebar) | Scroll session list |
 
 ### Windows
 
@@ -97,8 +115,9 @@ One command adds a hook to `~/.claude/settings.json`. When Claude finishes a res
 |-----|--------|
 | `Ctrl-a \|` | Split horizontal |
 | `Ctrl-a -` | Split vertical |
-| `Shift-arrows` | Navigate panes |
-| `Ctrl-a arrows` | Resize panes |
+| `Shift-Left/Right/Up/Down` | Navigate panes (vim-aware) |
+| `Ctrl-a Left/Right/Up/Down` | Resize panes |
+| `Ctrl-a P` | Toggle pane border titles |
 
 ### Utilities
 
@@ -106,7 +125,7 @@ One command adds a hook to `~/.claude/settings.json`. When Claude finishes a res
 |-----|--------|
 | `Ctrl-a k` | Clear pane + scrollback |
 | `Ctrl-a y` | Copy pane to clipboard |
-| `Ctrl-a P` | Toggle pane border titles |
+| `Ctrl-a i` | Settings |
 
 ---
 
@@ -115,12 +134,12 @@ One command adds a hook to `~/.claude/settings.json`. When Claude finishes a res
 Config loads in three layers:
 
 ```
-config/defaults.conf      ← jmux defaults (baseline)
-~/.tmux.conf              ← your config (overrides defaults)
-config/core.conf          ← jmux core (always wins)
+config/defaults.conf      <- jmux defaults (baseline)
+~/.tmux.conf              <- your config (overrides defaults)
+config/core.conf          <- jmux core (always wins)
 ```
 
-Override any default in your `~/.tmux.conf` — prefix key, colors, keybindings, plugins. Only four core settings are enforced: `detach-on-destroy off`, `mouse on`, `prefix + n` binding, and empty `status-left`.
+Override any default in your `~/.tmux.conf` — prefix key, colors, keybindings, plugins. Only core settings the sidebar depends on are enforced (`mouse on`, `detach-on-destroy off`, window naming, `status-left`).
 
 See [docs/configuration.md](docs/configuration.md) for the full guide.
 
@@ -130,15 +149,15 @@ See [docs/configuration.md](docs/configuration.md) for the full guide.
 
 ```
 Terminal (Ghostty, iTerm, etc.)
-  └── jmux (owns the terminal surface)
-       ├── Sidebar (24 cols) ── session groups, indicators
-       ├── Border (1 col)
-       └── tmux PTY (remaining cols)
-            ├── PTY client ──── @xterm/headless for VT emulation
-            └── Control client ─ tmux -C for real-time metadata
+  +-- jmux (owns the terminal surface)
+       +-- Sidebar (26 cols) -- session groups, indicators
+       +-- Border (1 col)
+       +-- tmux PTY (remaining cols)
+            +-- PTY client ---- @xterm/headless for VT emulation
+            +-- Control client - tmux -C for real-time metadata
 ```
 
-~1500 lines of TypeScript. No opinions about what you run inside tmux.
+~1800 lines of TypeScript. No opinions about what you run inside tmux.
 
 ---
 

package/config/defaults.conf

@@ -63,6 +63,9 @@ bind y run-shell "tmux capture-pane -pS - -E - | grep . | pbcopy" \; display-mes
 # Move window to another session (C-a m)
 bind-key m display-popup -E -w 40% -h 50% -b heavy -S 'fg=#4f565d' "$JMUX_DIR/config/move-window.sh"
 
+# Settings modal (C-a i)
+bind-key i display-popup -E -w 50% -h 40% -b heavy -S 'fg=#4f565d' "$JMUX_DIR/config/settings.sh"
+
 # Rename session (C-a r)
 bind-key r display-popup -E -w 40% -h 8 -b heavy -S 'fg=#4f565d' "$JMUX_DIR/config/rename-session.sh"
 

package/config/new-session.sh

@@ -1,19 +1,29 @@
 #!/bin/bash
-# jmux new session — name + directory picker
+# jmux new session — name + directory picker with wtm worktree support
 # Called via: display-popup -E "new-session.sh"
 
 FZF_COLORS="border:#4f565d,header:#b5bcc9,prompt:#9fe8c3,label:#9fe8c3,pointer:#9fe8c3,fg:#6b7280,fg+:#b5bcc9,hl:#fbd4b8,hl+:#fbd4b8"
 
 # ─── Step 1: Pick a directory ─────────────────────────────────────────
 
+# Read project directories from config, fall back to defaults
+CONFIG_FILE="$HOME/.config/jmux/config.json"
+SEARCH_DIRS=""
+if [ -f "$CONFIG_FILE" ]; then
+    SEARCH_DIRS=$(bun -e "
+        const c = await Bun.file('$CONFIG_FILE').json().catch(() => ({}));
+        const dirs = c.projectDirs ?? [];
+        console.log(dirs.map(d => d.replace('~', process.env.HOME)).join('\n'));
+    " 2>/dev/null)
+fi
+if [ -z "$SEARCH_DIRS" ]; then
+    SEARCH_DIRS=$(printf "%s\n%s\n%s\n%s\n%s" \
+        "$HOME/Code" "$HOME/Projects" "$HOME/src" "$HOME/work" "$HOME/dev")
+fi
+
 # Build project list: find directories with .git (dir or file — worktrees use a file)
 # Search common code directories, limit depth for speed
-PROJECT_DIRS=$(find \
-    "$HOME/Code" \
-    "$HOME/Projects" \
-    "$HOME/src" \
-    "$HOME/work" \
-    "$HOME/dev" \
+PROJECT_DIRS=$(echo "$SEARCH_DIRS" | xargs -I{} find "{}" \
     -maxdepth 4 -name ".git" 2>/dev/null \
     | sed 's|/\.git$||' \
     | sort -u)
@@ -40,26 +50,152 @@ SELECTED_DIR=$(echo "$DISPLAY_DIRS" | fzf \
 # Expand ~ back to $HOME
 WORK_DIR="${SELECTED_DIR/#\~/$HOME}"
 
-# Default session name to directory basename
-DEFAULT_NAME=$(basename "$WORK_DIR")
+# ─── Step 1.5: Detect wtm bare repo ──────────────────────────────────
 
-# ─── Step 2: Session name ─────────────────────────────────────────────
+# Check if this is a bare repo (wtm-managed) and wtm is available
+IS_BARE=false
+WTM_ENABLED=$(bun -e "
+    const c = await Bun.file('$CONFIG_FILE').json().catch(() => ({}));
+    console.log(c.wtmIntegration ?? true);
+" 2>/dev/null || echo "true")
+if [ "$WTM_ENABLED" = "true" ] && command -v wtm &>/dev/null && [ -f "$WORK_DIR/.git/config" ]; then
+    if git --git-dir="$WORK_DIR/.git" config --get core.bare 2>/dev/null | grep -q "true"; then
+        IS_BARE=true
+    fi
+fi
 
-SESSION_NAME=$(echo "" | fzf --print-query \
-    --height=100% \
-    --layout=reverse \
-    --border=rounded \
-    --border-label=" New Session — Name " \
-    --header="Directory: $SELECTED_DIR" \
-    --header-first \
-    --prompt="Name: " \
-    --query="$DEFAULT_NAME" \
-    --pointer="" \
-    --no-info \
-    --color="$FZF_COLORS" \
-    | head -1)
-
-[ -z "$SESSION_NAME" ] && exit 0
+if [ "$IS_BARE" = true ]; then
+    # ─── wtm flow: create worktree or pick existing ───────────────
+
+    # List existing worktrees (non-bare)
+    EXISTING=$(git --git-dir="$WORK_DIR/.git" worktree list --porcelain 2>/dev/null \
+        | grep "^branch " \
+        | sed 's|branch refs/heads/||' \
+        | sort)
+
+    # Detect default branch
+    DEFAULT_BRANCH=""
+    for b in main master develop; do
+        if git --git-dir="$WORK_DIR/.git" rev-parse --verify "refs/remotes/origin/$b" &>/dev/null; then
+            DEFAULT_BRANCH="$b"
+            break
+        fi
+    done
+
+    # Build options: existing worktrees + "new worktree" option
+    OPTIONS=""
+    if [ -n "$EXISTING" ]; then
+        OPTIONS=$(echo "$EXISTING" | sed 's/^/  /')
+    fi
+    OPTIONS=$(printf "+ new worktree\n%s" "$OPTIONS" | grep -v '^$')
+
+    PROJECT_NAME=$(basename "$WORK_DIR")
+    CHOICE=$(echo "$OPTIONS" | fzf \
+        --height=100% \
+        --layout=reverse \
+        --border=rounded \
+        --border-label=" $PROJECT_NAME — Worktree " \
+        --header="Pick a worktree or create a new one" \
+        --header-first \
+        --prompt="Branch: " \
+        --pointer="▸" \
+        --color="$FZF_COLORS")
+
+    [ -z "$CHOICE" ] && exit 0
+
+    if [ "$CHOICE" = "+ new worktree" ]; then
+        # ─── New worktree: pick base branch, then name ────────────
+
+        # List remote branches for base selection
+        REMOTE_BRANCHES=$(git --git-dir="$WORK_DIR/.git" for-each-ref \
+            --format='%(refname:short)' refs/remotes/origin/ 2>/dev/null \
+            | sed 's|^origin/||' \
+            | grep -v '^HEAD$' \
+            | sort)
+
+        BASE_BRANCH=$(echo "$REMOTE_BRANCHES" | fzf \
+            --height=100% \
+            --layout=reverse \
+            --border=rounded \
+            --border-label=" $PROJECT_NAME — Base Branch " \
+            --header="Branch to create worktree from" \
+            --header-first \
+            --prompt="From: " \
+            --pointer="▸" \
+            --query="$DEFAULT_BRANCH" \
+            --color="$FZF_COLORS")
+
+        [ -z "$BASE_BRANCH" ] && exit 0
+
+        # Prompt for worktree/branch name
+        WORKTREE_NAME=$(echo "" | fzf --print-query \
+            --height=100% \
+            --layout=reverse \
+            --border=rounded \
+            --border-label=" $PROJECT_NAME — Branch Name " \
+            --header="From: $BASE_BRANCH" \
+            --header-first \
+            --prompt="Name: " \
+            --pointer="" \
+            --no-info \
+            --color="$FZF_COLORS" \
+            | head -1)
+
+        [ -z "$WORKTREE_NAME" ] && exit 0
+
+        # Create session in bare repo dir, split into two panes
+        WORKTREE_PATH="$WORK_DIR/$WORKTREE_NAME"
+        PARENT_CLIENT=$(tmux display-message -p '#{client_name}' 2>/dev/null)
+        # Left pane: run wtm create (fetch, hooks visible here)
+        tmux new-session -d -s "$WORKTREE_NAME" -c "$WORK_DIR" \
+            "wtm create $WORKTREE_NAME --from $BASE_BRANCH --no-shell; cd $WORKTREE_NAME; exec \$SHELL"
+        # Right pane: wait for worktree, then open shell
+        tmux split-window -h -d -t "$WORKTREE_NAME" -c "$WORK_DIR" \
+            "while [ ! -d '$WORKTREE_PATH' ]; do sleep 0.2; done; cd '$WORKTREE_PATH' && exec \$SHELL"
+        # Switch to the session (focus on left pane)
+        tmux select-pane -t "$WORKTREE_NAME.0"
+        tmux switch-client -c "$PARENT_CLIENT" -t "$WORKTREE_NAME"
+        exit 0
+    else
+        # Existing worktree selected — find its path
+        BRANCH_NAME=$(echo "$CHOICE" | sed 's/^  //')
+        WORKTREE_PATH=$(git --git-dir="$WORK_DIR/.git" worktree list --porcelain 2>/dev/null \
+            | awk -v branch="$BRANCH_NAME" '
+                /^worktree / { path = substr($0, 10) }
+                /^branch / { b = $0; sub(/branch refs\/heads\//, "", b); if (b == branch) print path }
+            ')
+
+        if [ -z "$WORKTREE_PATH" ]; then
+            echo "Could not find worktree path for $BRANCH_NAME"
+            sleep 2
+            exit 1
+        fi
+
+        WORK_DIR="$WORKTREE_PATH"
+        SESSION_NAME="$BRANCH_NAME"
+    fi
+else
+    # ─── Standard flow: just pick a name ──────────────────────────
+
+    # Default session name to directory basename
+    DEFAULT_NAME=$(basename "$WORK_DIR")
+
+    SESSION_NAME=$(echo "" | fzf --print-query \
+        --height=100% \
+        --layout=reverse \
+        --border=rounded \
+        --border-label=" New Session — Name " \
+        --header="Directory: $SELECTED_DIR" \
+        --header-first \
+        --prompt="Name: " \
+        --query="$DEFAULT_NAME" \
+        --pointer="" \
+        --no-info \
+        --color="$FZF_COLORS" \
+        | head -1)
+
+    [ -z "$SESSION_NAME" ] && exit 0
+fi
 
 # ─── Create session ───────────────────────────────────────────────────
 

package/config/release-notes.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Show release notes for a jmux version in a formatted popup
+# Usage: release-notes.sh <tag>
+
+TAG="${1:-v0.0.0}"
+REPO="jarredkenny/jmux"
+
+# Colors
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+CYAN="\033[36m"
+RESET="\033[0m"
+
+# Fetch release data
+BODY=$(gh release view "$TAG" --repo "$REPO" --json body,publishedAt,name -q '"\(.name)\n\(.publishedAt)\n\(.body)"' 2>/dev/null)
+
+if [ -z "$BODY" ]; then
+    echo -e "\n  ${DIM}jmux ${TAG}${RESET}\n"
+    echo -e "  ${DIM}No release notes available.${RESET}\n"
+    echo -e "  ${DIM}Press q to close${RESET}"
+    read -rsn1
+    exit 0
+fi
+
+NAME=$(echo "$BODY" | head -1)
+DATE=$(echo "$BODY" | sed -n '2p' | cut -dT -f1)
+NOTES=$(echo "$BODY" | tail -n +3)
+
+{
+    echo ""
+    echo -e "  ${BOLD}${GREEN}jmux ${NAME}${RESET}"
+    echo -e "  ${DIM}Released ${DATE}${RESET}"
+    echo ""
+    # Format markdown: bold **text**, headers ##, bullet points
+    echo "$NOTES" | sed \
+        -e "s/^## \(.*\)/  $(printf '\033[1m')\1$(printf '\033[0m')/" \
+        -e "s/^- /  • /" \
+        -e "s/\*\*\([^*]*\)\*\*/$(printf '\033[1m')\1$(printf '\033[0m')/g" \
+        -e "s/\`\([^\`]*\)\`/$(printf '\033[36m')\1$(printf '\033[0m')/g" \
+        -e '/^$/s/^$//'
+    echo ""
+    echo -e "  ${DIM}https://github.com/${REPO}/releases/tag/${TAG}${RESET}"
+    echo ""
+    echo -e "  ${DIM}Press q to close${RESET}"
+}
+read -rsn1

package/config/settings.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# jmux settings modal — reads/writes ~/.config/jmux/config.json
+# Called via: display-popup -E "settings.sh"
+
+CONFIG_DIR="$HOME/.config/jmux"
+CONFIG_FILE="$CONFIG_DIR/config.json"
+FZF_COLORS="border:#4f565d,header:#b5bcc9,prompt:#9fe8c3,label:#9fe8c3,pointer:#9fe8c3,fg:#6b7280,fg+:#b5bcc9,hl:#fbd4b8,hl+:#fbd4b8"
+
+# ─── Helpers ──────────────────────────────────────────────────────────
+
+read_config() {
+    bun -e "
+        const c = await Bun.file('$CONFIG_FILE').json().catch(() => ({}));
+        console.log(JSON.stringify(c));
+    " 2>/dev/null || echo "{}"
+}
+
+write_config() {
+    local json="$1"
+    mkdir -p "$CONFIG_DIR"
+    echo "$json" | bun -e "
+        const stdin = await Bun.stdin.text();
+        const c = JSON.parse(stdin);
+        await Bun.write('$CONFIG_FILE', JSON.stringify(c, null, 2) + '\n');
+    "
+}
+
+get_value() {
+    local json="$1" key="$2" default="$3"
+    echo "$json" | bun -e "
+        const stdin = await Bun.stdin.text();
+        const c = JSON.parse(stdin);
+        console.log(c['$key'] ?? '$default');
+    " 2>/dev/null || echo "$default"
+}
+
+set_value() {
+    local json="$1" key="$2" value="$3" type="$4"
+    echo "$json" | bun -e "
+        const stdin = await Bun.stdin.text();
+        const c = JSON.parse(stdin);
+        const v = '$value';
+        const t = '$type';
+        if (t === 'number') c['$key'] = parseInt(v, 10);
+        else if (t === 'bool') c['$key'] = v === 'true';
+        else if (t === 'array') c['$key'] = v.split(',').map(s => s.trim()).filter(Boolean);
+        else c['$key'] = v;
+        console.log(JSON.stringify(c));
+    " 2>/dev/null
+}
+
+# ─── Main loop ────────────────────────────────────────────────────────
+
+while true; do
+    CONFIG=$(read_config)
+
+    SIDEBAR_WIDTH=$(get_value "$CONFIG" "sidebarWidth" "26")
+    PROJECT_DIRS_RAW=$(echo "$CONFIG" | bun -e "
+        const c = JSON.parse(await Bun.stdin.text());
+        const dirs = c.projectDirs ?? ['~/Code', '~/Projects', '~/src', '~/work', '~/dev'];
+        console.log(dirs.join(', '));
+    " 2>/dev/null || echo "~/Code, ~/Projects, ~/src, ~/work, ~/dev")
+    WTM_ENABLED=$(get_value "$CONFIG" "wtmIntegration" "true")
+
+    # Format display
+    WTM_DISPLAY="on"
+    [ "$WTM_ENABLED" = "false" ] && WTM_DISPLAY="off"
+
+    SELECTION=$(printf "%s\n%s\n%s" \
+        "Sidebar Width            $SIDEBAR_WIDTH" \
+        "Project Directories      $PROJECT_DIRS_RAW" \
+        "wtm Integration          $WTM_DISPLAY" \
+        | fzf \
+            --height=100% \
+            --layout=reverse \
+            --border=rounded \
+            --border-label=" Settings " \
+            --header="Select a setting to change" \
+            --header-first \
+            --prompt="  " \
+            --pointer="▸" \
+            --no-info \
+            --color="$FZF_COLORS")
+
+    [ -z "$SELECTION" ] && exit 0
+
+    case "$SELECTION" in
+        "Sidebar Width"*)
+            NEW_WIDTH=$(echo "" | fzf --print-query \
+                --height=100% \
+                --layout=reverse \
+                --border=rounded \
+                --border-label=" Sidebar Width " \
+                --header="Current: $SIDEBAR_WIDTH (takes effect on restart)" \
+                --header-first \
+                --prompt="Width: " \
+                --query="$SIDEBAR_WIDTH" \
+                --pointer="" \
+                --no-info \
+                --color="$FZF_COLORS" \
+                | head -1)
+
+            if [ -n "$NEW_WIDTH" ]; then
+                CONFIG=$(set_value "$CONFIG" "sidebarWidth" "$NEW_WIDTH" "number")
+                write_config "$CONFIG"
+            fi
+            ;;
+
+        "Project Directories"*)
+            NEW_DIRS=$(echo "" | fzf --print-query \
+                --height=100% \
+                --layout=reverse \
+                --border=rounded \
+                --border-label=" Project Directories " \
+                --header="Comma-separated list of directories to search" \
+                --header-first \
+                --prompt="Dirs: " \
+                --query="$PROJECT_DIRS_RAW" \
+                --pointer="" \
+                --no-info \
+                --color="$FZF_COLORS" \
+                | head -1)
+
+            if [ -n "$NEW_DIRS" ]; then
+                CONFIG=$(set_value "$CONFIG" "projectDirs" "$NEW_DIRS" "array")
+                write_config "$CONFIG"
+            fi
+            ;;
+
+        "wtm Integration"*)
+            if [ "$WTM_ENABLED" = "true" ]; then
+                CONFIG=$(set_value "$CONFIG" "wtmIntegration" "false" "bool")
+            else
+                CONFIG=$(set_value "$CONFIG" "wtmIntegration" "true" "bool")
+            fi
+            write_config "$CONFIG"
+            ;;
+    esac
+done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jx0/jmux",
-  "version": "0.3.9",
+  "version": "0.5.0",
   "description": "The terminal workspace for agentic development",
   "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.3.9";
+const VERSION = "0.5.0";
 
 const HELP = `jmux — a persistent session sidebar for tmux
 
@@ -108,9 +108,22 @@ function installAgentHooks(): void {
 
 // --- TUI startup ---
 
-const SIDEBAR_WIDTH = 24;
+// Read sidebar width from user config, fall back to default
+function loadUserConfig(): Record<string, any> {
+  const configPath = resolve(homedir(), ".config", "jmux", "config.json");
+  try {
+    if (existsSync(configPath)) {
+      return JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+  } catch {
+    // Invalid config — use defaults
+  }
+  return {};
+}
+const userConfig = loadUserConfig();
+let sidebarWidth = (userConfig.sidebarWidth as number) || 26;
 const BORDER_WIDTH = 1;
-const SIDEBAR_TOTAL = SIDEBAR_WIDTH + BORDER_WIDTH;
+function sidebarTotal(): number { return sidebarWidth + BORDER_WIDTH; }
 
 // Resolve paths relative to source
 const jmuxDir = resolve(dirname(import.meta.dir));
@@ -138,7 +151,7 @@ for (let i = 2; i < process.argv.length; i++) {
 const cols = process.stdout.columns || 80;
 const rows = process.stdout.rows || 24;
 const sidebarVisible = cols >= 80;
-const mainCols = sidebarVisible ? cols - SIDEBAR_TOTAL : cols;
+const mainCols = sidebarVisible ? cols - sidebarTotal() : cols;
 
 // Enter alternate screen, raw mode, enable mouse tracking
 process.stdout.write("\x1b[?1049h");
@@ -155,15 +168,17 @@ process.stdin.resume();
 const pty = new TmuxPty({ sessionName, socketName, configFile, jmuxDir, cols: mainCols, rows });
 const bridge = new ScreenBridge(mainCols, rows);
 const renderer = new Renderer();
-const sidebar = new Sidebar(SIDEBAR_WIDTH, rows);
+const sidebar = new Sidebar(sidebarWidth, rows);
 const control = new TmuxControl();
 
 let currentSessionId: string | null = null;
 let ptyClientName: string | null = null;
 let sidebarShown = sidebarVisible;
 let currentSessions: SessionInfo[] = [];
+
+sidebar.setVersion(VERSION);
 const lastViewedTimestamps = new Map<string, number>();
-const sessionDetailsCache = new Map<string, { directory?: string; gitBranch?: string }>();
+const sessionDetailsCache = new Map<string, { directory?: string; gitBranch?: string; project?: string }>();
 
 function switchByOffset(offset: number): void {
   const ids = sidebar.getDisplayOrderIds();
@@ -303,12 +318,16 @@ function clearSessionIndicators(): void {
 
 const inputRouter = new InputRouter(
   {
-    sidebarCols: SIDEBAR_WIDTH,
+    sidebarCols: sidebarWidth,
     onPtyData: (data) => {
       pty.write(data);
       clearSessionIndicators();
     },
     onSidebarClick: (row) => {
+      if (sidebar.isVersionRow(row)) {
+        showVersionInfo();
+        return;
+      }
       const session = sidebar.getSessionByRow(row);
       if (session) switchSession(session.id);
     },
@@ -393,15 +412,76 @@ process.on("SIGWINCH", () => {
   const newCols = process.stdout.columns || 80;
   const newRows = process.stdout.rows || 24;
   const newSidebarVisible = newCols >= 80;
-  const newMainCols = newSidebarVisible ? newCols - SIDEBAR_TOTAL : newCols;
+  const newMainCols = newSidebarVisible ? newCols - sidebarTotal() : newCols;
 
   sidebarShown = newSidebarVisible;
   inputRouter.setSidebarVisible(newSidebarVisible);
   pty.resize(newMainCols, newRows);
   bridge.resize(newMainCols, newRows);
-  sidebar.resize(SIDEBAR_WIDTH, newRows);
+  sidebar.resize(sidebarWidth, newRows);
 });
 
+// --- Config file watcher ---
+
+const configPath = resolve(homedir(), ".config", "jmux", "config.json");
+try {
+  const { watch } = await import("fs");
+  watch(configPath, () => {
+    const updated = loadUserConfig();
+    const newWidth = (updated.sidebarWidth as number) || 26;
+    if (newWidth !== sidebarWidth) {
+      sidebarWidth = newWidth;
+      const cols = process.stdout.columns || 80;
+      const rows = process.stdout.rows || 24;
+      const newSidebarVisible = cols >= 80;
+      const newMainCols = newSidebarVisible ? cols - sidebarTotal() : cols;
+
+      sidebarShown = newSidebarVisible;
+      inputRouter.setSidebarVisible(newSidebarVisible);
+      pty.resize(newMainCols, rows);
+      bridge.resize(newMainCols, rows);
+      sidebar.resize(sidebarWidth, rows);
+    }
+  });
+} catch {
+  // Config file may not exist yet — watcher will fail silently
+}
+
+// --- Update check ---
+
+async function checkForUpdates(): Promise<void> {
+  try {
+    const resp = await fetch(
+      "https://api.github.com/repos/jarredkenny/jmux/releases/latest",
+      { headers: { "Accept": "application/vnd.github.v3+json" } },
+    );
+    if (!resp.ok) return;
+    const data = await resp.json() as { tag_name?: string };
+    const latest = data.tag_name?.replace(/^v/, "");
+    if (latest && latest !== VERSION) {
+      sidebar.setVersion(VERSION, latest);
+      scheduleRender();
+    }
+  } catch {
+    // Offline or rate-limited — no problem
+  }
+}
+
+async function showVersionInfo(): Promise<void> {
+  if (!ptyClientName) await resolveClientName();
+  if (!ptyClientName) return;
+  const tag = `v${VERSION}`;
+  const cmd = `${jmuxDir}/config/release-notes.sh ${tag}`;
+  // Use tmux CLI directly — confirmed working from terminal tests
+  const args = ["tmux"];
+  if (socketName) args.push("-L", socketName);
+  args.push("display-popup", "-c", ptyClientName, "-E", "-w", "70%", "-h", "40%", "-b", "heavy", "-S", "fg=#4f565d", "sh", "-c", cmd);
+  Bun.spawn(args, { stdout: "ignore", stderr: "ignore" });
+}
+
+// Check for updates in the background (non-blocking)
+checkForUpdates();
+
 // --- Control mode events ---
 
 control.onEvent((event: ControlEvent) => {
@@ -446,10 +526,31 @@ async function lookupSessionDetails(sessions: SessionInfo[]): Promise<void> {
         .catch(() => "");
       const gitBranch = branch.trim() || undefined;
 
+      // Detect wtm worktree — .git is a file pointing to a bare repo
+      let project: string | undefined;
+      try {
+        const commonDir = await $`git -C ${cwd} rev-parse --git-common-dir`
+          .text()
+          .catch(() => "");
+        const gitDir = await $`git -C ${cwd} rev-parse --git-dir`
+          .text()
+          .catch(() => "");
+        if (commonDir.trim() && gitDir.trim() && commonDir.trim() !== gitDir.trim()) {
+          // In a worktree — commonDir points to the bare repo's .git
+          // Bare repo structure: /path/to/project/.git → project name is parent dir basename
+          const resolved = resolve(cwd, commonDir.trim());
+          const bareRoot = dirname(resolved);
+          project = bareRoot.split("/").pop();
+        }
+      } catch {
+        // Not a worktree
+      }
+
       // Write to persistent cache
-      sessionDetailsCache.set(session.id, { directory, gitBranch });
+      sessionDetailsCache.set(session.id, { directory, gitBranch, project });
       session.directory = directory;
       session.gitBranch = gitBranch;
+      session.project = project;
     } catch {
       // Session may not exist or no git repo
     }

package/src/sidebar.ts

@@ -98,12 +98,11 @@ function buildRenderPlan(sessions: SessionInfo[]): {
   const ungrouped: number[] = [];
 
   for (let i = 0; i < sessions.length; i++) {
-    const dir = sessions[i].directory;
-    if (!dir) {
-      ungrouped.push(i);
-      continue;
-    }
-    const label = getGroupLabel(dir);
+    // Prefer project name (wtm) over directory-based grouping
+    const label = sessions[i].project ?? (() => {
+      const dir = sessions[i].directory;
+      return dir ? getGroupLabel(dir) : null;
+    })();
     if (!label) {
       ungrouped.push(i);
       continue;
@@ -162,6 +161,11 @@ function itemHeight(item: RenderItem): number {
 
 // --- Sidebar class ---
 
+const UPDATE_AVAILABLE_ATTRS: CellAttrs = {
+  fg: 3,
+  fgMode: ColorMode.Palette,
+};
+
 export class Sidebar {
   private width: number;
   private height: number;
@@ -172,6 +176,8 @@ export class Sidebar {
   private rowToSessionIndex = new Map<number, number>();
   private activitySet = new Set<string>();
   private scrollOffset = 0;
+  private currentVersion: string = "";
+  private latestVersion: string | null = null;
 
   constructor(width: number, height: number) {
     this.width = width;
@@ -213,6 +219,19 @@ export class Sidebar {
       .filter(Boolean) as string[];
   }
 
+  setVersion(current: string, latest?: string): void {
+    this.currentVersion = current;
+    this.latestVersion = latest ?? null;
+  }
+
+  hasUpdate(): boolean {
+    return this.latestVersion !== null && this.latestVersion !== this.currentVersion;
+  }
+
+  isVersionRow(row: number): boolean {
+    return this.currentVersion !== "" && row === this.height - 1;
+  }
+
   getSessionByRow(row: number): SessionInfo | null {
     const sessionIdx = this.rowToSessionIndex.get(row);
     if (sessionIdx === undefined) return null;
@@ -232,7 +251,7 @@ export class Sidebar {
 
   scrollToActive(): void {
     if (!this.activeSessionId) return;
-    const viewportHeight = this.height - HEADER_ROWS;
+    const viewportHeight = this.viewportHeight();
     let vRow = 0;
     for (const item of this.items) {
       const h = itemHeight(item);
@@ -252,10 +271,17 @@ export class Sidebar {
     }
   }
 
+  private footerRows(): number {
+    return this.currentVersion ? 1 : 0;
+  }
+
+  private viewportHeight(): number {
+    return this.height - HEADER_ROWS - this.footerRows();
+  }
+
   private clampScroll(): void {
     const totalRows = this.items.reduce((sum, item) => sum + itemHeight(item), 0);
-    const viewportHeight = this.height - HEADER_ROWS;
-    const maxOffset = Math.max(0, totalRows - viewportHeight);
+    const maxOffset = Math.max(0, totalRows - this.viewportHeight());
     this.scrollOffset = Math.max(0, Math.min(maxOffset, this.scrollOffset));
   }
 
@@ -267,7 +293,8 @@ export class Sidebar {
     writeString(grid, 0, 1, "jmux", { ...ACCENT_ATTRS, bold: true });
     writeString(grid, 1, 0, "\u2500".repeat(this.width), DIM_ATTRS);
 
-    const viewportHeight = this.height - HEADER_ROWS;
+    const vpHeight = this.viewportHeight();
+    const contentBottom = HEADER_ROWS + vpHeight;
     let vRow = 0;
     let totalRows = 0;
 
@@ -282,7 +309,7 @@ export class Sidebar {
         continue;
       }
       // Track total rows even after viewport
-      if (screenRow >= this.height) {
+      if (screenRow >= contentBottom) {
         vRow += h;
         totalRows += h;
         continue;
@@ -308,8 +335,23 @@ export class Sidebar {
     if (this.scrollOffset > 0) {
       writeString(grid, HEADER_ROWS, this.width - 1, "\u25b2", DIM_ATTRS);
     }
-    if (this.scrollOffset + viewportHeight < totalRows) {
-      writeString(grid, this.height - 1, this.width - 1, "\u25bc", DIM_ATTRS);
+    if (this.scrollOffset + vpHeight < totalRows) {
+      const scrollRow = this.footerRows() ? contentBottom - 1 : this.height - 1;
+      writeString(grid, scrollRow, this.width - 1, "\u25bc", DIM_ATTRS);
+    }
+
+    // Version footer
+    if (this.currentVersion) {
+      const footerRow = this.height - 1;
+      const versionText = `v${this.currentVersion}`;
+      if (this.hasUpdate()) {
+        const updateText = `v${this.latestVersion} avail`;
+        const maxLen = this.width - 2;
+        const display = updateText.length <= maxLen ? updateText : `v${this.latestVersion}`;
+        writeString(grid, footerRow, 1, display, UPDATE_AVAILABLE_ATTRS);
+      } else {
+        writeString(grid, footerRow, 1, versionText, DIM_ATTRS);
+      }
     }
 
     return grid;

package/src/types.ts

@@ -36,4 +36,5 @@ export interface SessionInfo {
   attention: boolean;
   windowCount: number;
   directory?: string;
+  project?: string; // wtm project name (bare repo basename)
 }