@jx0/jmux 0.3.9 → 0.4.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,6 @@ 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 |
 
 ---
 
@@ -115,12 +133,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 +148,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/new-session.sh

@@ -1,5 +1,5 @@
 #!/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"
@@ -40,26 +40,148 @@ 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
+if 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jx0/jmux",
-  "version": "0.3.9",
+  "version": "0.4.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.4.0";
 
 const HELP = `jmux — a persistent session sidebar for tmux
 
@@ -108,7 +108,7 @@ function installAgentHooks(): void {
 
 // --- TUI startup ---
 
-const SIDEBAR_WIDTH = 24;
+const SIDEBAR_WIDTH = 26;
 const BORDER_WIDTH = 1;
 const SIDEBAR_TOTAL = SIDEBAR_WIDTH + BORDER_WIDTH;
 
@@ -163,7 +163,7 @@ let ptyClientName: string | null = null;
 let sidebarShown = sidebarVisible;
 let currentSessions: SessionInfo[] = [];
 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();
@@ -446,10 +446,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;

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)
 }