@jx0/jmux 0.5.3 → 0.6.0

package/README.md

@@ -22,7 +22,9 @@ bun install -g @jx0/jmux
 jmux
 ```
 
-Requires [Bun](https://bun.sh) 1.2+, [tmux](https://github.com/tmux/tmux) 3.2+, [fzf](https://github.com/junegunn/fzf), and optionally [git](https://git-scm.com/) for branch display.
+Requires [Bun](https://bun.sh) 1.2+, [tmux](https://github.com/tmux/tmux) 3.2+, [fzf](https://github.com/junegunn/fzf), and optionally [git](https://git-scm.com/) for branch display. jmux will offer to install tmux and fzf for you on first run.
+
+New to tmux? See the **[Getting Started guide](docs/getting-started.md)** — no prior tmux knowledge needed.
 
 ---
 

package/config/welcome.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# jmux first-run welcome screen
+# Called via: display-popup -E "welcome.sh"
+
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+CYAN="\033[36m"
+RESET="\033[0m"
+
+clear
+echo ""
+echo -e "  ${GREEN}${BOLD}Welcome to jmux${RESET}"
+echo -e "  ${DIM}The terminal workspace for agentic development${RESET}"
+echo ""
+echo -e "  ${DIM}────────────────────────────────────────────${RESET}"
+echo ""
+echo -e "  ${BOLD}Essential keybindings${RESET}"
+echo ""
+echo -e "  ${GREEN}Ctrl-Shift-Up/Down${RESET}     Switch between sessions"
+echo -e "  ${GREEN}Ctrl-a${RESET} then ${GREEN}n${RESET}          New session"
+echo -e "  ${GREEN}Ctrl-a${RESET} then ${GREEN}c${RESET}          New window (tab)"
+echo -e "  ${GREEN}Ctrl-a${RESET} then ${GREEN}|${RESET}          Split pane horizontally"
+echo -e "  ${GREEN}Ctrl-a${RESET} then ${GREEN}-${RESET}          Split pane vertically"
+echo -e "  ${GREEN}Shift-Arrow${RESET}            Move between panes"
+echo -e "  ${GREEN}Ctrl-a${RESET} then ${GREEN}i${RESET}          Settings"
+echo ""
+echo -e "  ${DIM}────────────────────────────────────────────${RESET}"
+echo ""
+echo -e "  ${BOLD}The sidebar${RESET} on the left shows all your sessions."
+echo -e "  ${GREEN}●${RESET} Green dot = new output    ${YELLOW}!${RESET} Orange = needs review"
+echo -e "  Click a session to switch to it."
+echo ""
+echo -e "  ${DIM}────────────────────────────────────────────${RESET}"
+echo ""
+echo -e "  ${BOLD}Next steps${RESET}"
+echo ""
+echo -e "  ${CYAN}1.${RESET} Try ${GREEN}Ctrl-a n${RESET} to create a new session"
+echo -e "  ${CYAN}2.${RESET} Run ${GREEN}jmux --install-agent-hooks${RESET} for Claude Code notifications"
+echo -e "  ${CYAN}3.${RESET} Full guide: ${DIM}github.com/jarredkenny/jmux/blob/main/docs/getting-started.md${RESET}"
+echo ""
+echo -e "  ${DIM}Press any key to start${RESET}"
+read -rsn1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jx0/jmux",
-  "version": "0.5.3",
+  "version": "0.6.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.5.3";
+const VERSION = "0.6.0";
 
 const HELP = `jmux — the terminal workspace for agentic development
 
@@ -58,12 +58,6 @@ if (process.argv.includes("-v") || process.argv.includes("--version")) {
   process.exit(0);
 }
 
-if (process.env.JMUX) {
-  console.error("Already running inside jmux.");
-  process.exit(1);
-}
-process.env.JMUX = "1";
-
 if (process.argv.includes("--install-agent-hooks")) {
   installAgentHooks();
   process.exit(0);
@@ -122,6 +116,14 @@ function installAgentHooks(): void {
   console.log("will show an orange ! on that session.");
 }
 
+// --- Nesting guard (after CLI commands, before TUI) ---
+
+if (process.env.JMUX) {
+  console.error("Already running inside jmux.");
+  process.exit(1);
+}
+process.env.JMUX = "1";
+
 // --- TUI startup ---
 
 // Read sidebar width from user config, fall back to default
@@ -686,6 +688,22 @@ async function start(): Promise<void> {
   await resolveClientName();
   renderFrame();
 
+  // First-run welcome screen
+  const configDir = resolve(homedir(), ".config", "jmux");
+  const configPath = resolve(configDir, "config.json");
+  if (!existsSync(configPath)) {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(configPath, JSON.stringify({}, null, 2) + "\n");
+    if (!ptyClientName) await resolveClientName();
+    if (ptyClientName) {
+      const welcomeScript = resolve(jmuxDir, "config", "welcome.sh");
+      const args = ["tmux"];
+      if (socketName) args.push("-L", socketName);
+      args.push("display-popup", "-c", ptyClientName, "-E", "-w", "55%", "-h", "60%", "-b", "heavy", "-S", "fg=#4f565d", welcomeScript);
+      Bun.spawn(args, { stdout: "ignore", stderr: "ignore" });
+    }
+  }
+
   // Subscribe to @jmux-attention across all sessions
   await control.registerSubscription(
     "attention",