projmux 0.7.2 → 0.7.4

package/README-ko.md

@@ -16,7 +16,7 @@ workspace 도구입니다.
 <p align="center">
   <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
   <br>
-  <em>project를 오가며 AI permission 대기를 상태줄에서 확인하고, notification list에서 해당 pane으로 돌아갑니다.</em>
+  <em>기존 AI session을 이어서 열고 다른 project에서 작업하다가, permission이 필요하면 notification list에서 managed pane으로 돌아갑니다.</em>
 </p>
 
 ## 무엇인가
@@ -63,14 +63,15 @@ projmux shell
 - `Alt-1`: project sidebar.
 - `Alt-2`: notification list.
 - `Alt-3`: Recent Windows.
-- `Alt-4`: AI split picker.
+- `Alt-4`: AI resume session picker.
 - `Alt-5`: settings.
-- `Alt-6`: project switcher popup.
-- `Alt-7`: AI resume session picker.
+- `Alt-7`: AI split picker.
 
-전체 key map은 [Terminal Keybindings](docs/keybindings.md)를 참고하세요. 키가
-동작하지 않으면 tmux 밖에서 `projmux setup`을 실행한 뒤,
-지원 터미널에서는 `projmux init [terminal] --apply`를 사용하세요.
+`Alt-1`부터 `Alt-5`까지는 zero-config 보장 기본값이고, `Alt-7`은 추가로
+편집 가능한 built-in 기본값입니다. 전체 key map은
+[Terminal Keybindings](docs/keybindings.md)를 참고하세요. 키가 동작하지 않으면
+tmux 밖에서 `projmux setup`을 실행한 뒤, 지원 터미널에서는
+`projmux init [terminal] --apply`를 사용하세요.
 
 ## 일상 사용
 
@@ -78,42 +79,47 @@ projmux shell
 - 중요한 project는 pin으로 고정합니다.
 - 전환 전에 window, pane, git branch, Kubernetes context, AI pane state를
   preview합니다.
+- 기존 Claude/Codex conversation을 resume하거나 새 managed AI split을 엽니다.
+- permission/completion event를 하나의 notification queue에서 확인하고 바로
+  attention이 필요한 pane으로 이동합니다.
 - env var를 직접 편집하지 않고 Settings > Project Picker에서 root와 workdir을
   추가할 수 있습니다.
 - Settings > About > Update 또는 `projmux update apply`로 업그레이드합니다.
 
+<p align="center">
+  <img src="docs/assets/projmux-shell-sidebar.gif" alt="projmux project 전환 및 managed Codex 데모" width="820">
+  <br>
+  <em>project를 전환하고 managed Codex pane을 연 뒤 completion notification을 확인합니다.</em>
+</p>
+
 `PROJMUX_PROJDIR`, managed roots, notification, usage tracking 같은 자세한
 설정은 [Configuration](docs/configuration.md)을 참고하세요. installer별 update
 동작은 [Upgrading](docs/upgrading.md)에 있습니다.
 
-## 에이전트 스킬
+## 멀티 에이전트 워크플로
 
-projmux shortcut은 AI 도구의 user-level skill 또는 slash command로도 등록할
-수 있습니다. 스킬은 같은 CLI contract를 감싸는 얇은 wrapper입니다:
+하나의 tmux window에 shell과 여러 managed agent를 함께 띄워 둡니다. pane을
+이동하며 독립 작업을 시작하면 projmux가 permission/completion event를 하나의
+notification queue에 모읍니다.
+
+<p align="center">
+  <img src="docs/assets/projmux-three-pane-workflow.gif" alt="projmux shell, Codex, Claude 3-pane workflow 데모" width="820">
+  <br>
+  <em>동일 폭의 shell, Codex, Claude pane을 이동하며 독립 작업의 완료 알림을 하나의 notification queue에서 확인합니다.</em>
+</p>
+
+## 에이전트 스킬 자동화
+
+AI 도구도 같은 projmux CLI를 호출해 managed pane을 열고 prompt를 전달할 수
+있습니다:
 
 ```sh
-projmux ai split --agent codex right
-projmux ai split --agent claude down
-projmux ai split --agent antigravity right
+projmux ai split --agent codex right -- "Review the retry logic."
 ```
 
-`/projmux:codex-right` 같은 Claude slash command를 등록한 뒤 prompt와 함께
-실행시키면, Claude가 projmux command를 호출하고 현재 project에 붙은 managed
-Codex pane이 새로 열립니다. prompt는 새 pane으로 바로 전달되고,
-permission/completion hook event가 tmux 상태줄과 notification list에
-표시됩니다.
-Antigravity도 같은 managed split 경로로 실행되며, 수동 hook ingest와 session
-resume 지원 범위는 CLI reference에 정리되어 있습니다.
-
-설치 template과 naming convention은
+Claude, Codex와 다른 agent용 template 및 naming convention은
 [AI Agent Shortcuts](docs/ai-agent-shortcuts.md)에 정리되어 있습니다.
 
-<p align="center">
-  <img src="docs/assets/projmux-skill-workflow.gif" alt="projmux skill workflow demo" width="820">
-  <br>
-  <em>Claude가 prompt와 함께 등록된 projmux skill을 호출해 managed Codex pane을 열고, Codex가 그 자리에서 응답합니다.</em>
-</p>
-
 ## 추가 문서
 
 - [Install](docs/install.md)

package/README.md

@@ -25,7 +25,7 @@ projmux shell
 <p align="center">
   <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
   <br>
-  <em>Switch between projects while an AI pane waits for permission, then jump back from the tmux notification list.</em>
+  <em>Resume an existing AI session, keep working in another project, then jump back when the managed pane needs permission.</em>
 </p>
 
 ## Why
@@ -72,15 +72,15 @@ Inside the app:
 - `Alt-1` opens the project sidebar.
 - `Alt-2` opens the notification list.
 - `Alt-3` opens Recent Windows.
-- `Alt-4` opens the AI split picker.
+- `Alt-4` opens the AI resume session picker.
 - `Alt-5` opens settings.
-- `Alt-7` opens the AI resume session picker.
+- `Alt-7` opens the AI split picker.
 
 The `Alt-1` through `Alt-5` launch keys are the guaranteed zero-config
-defaults. Add more
-aliases in Settings > Keybindings or `~/.config/projmux/keymap.toml`. If a key
-does not fire, run `projmux setup` outside tmux, then use
-`projmux init [terminal] --apply` for supported terminal delivery fallbacks.
+defaults. `Alt-7` is an additional editable built-in default. Add aliases in
+Settings > Keybindings or `~/.config/projmux/keymap.toml`. If a key does not
+fire, run `projmux setup` outside tmux, then use `projmux init [terminal]
+--apply` for supported terminal delivery fallbacks.
 
 ## Day-To-Day Use
 
@@ -88,43 +88,48 @@ does not fire, run `projmux setup` outside tmux, then use
 - Pin important projects so they stay easy to reach.
 - Preview windows, panes, git branch, Kubernetes context, and AI pane state
   before switching.
+- Resume an existing Claude or Codex conversation, or open a new managed AI
+  split.
+- Review permission and completion events in one notification queue, then jump
+  directly to the pane that needs attention.
 - Use Settings > Project Picker to add roots and workdirs without editing env
   vars.
 - Use Settings > About > Update or `projmux update apply` to upgrade.
 
+<p align="center">
+  <img src="docs/assets/projmux-shell-sidebar.gif" alt="projmux project switch and managed Codex demo" width="820">
+  <br>
+  <em>Switch projects, launch a managed Codex pane, and review its completion notification.</em>
+</p>
+
 For detailed configuration, including `PROJMUX_PROJDIR`, managed roots,
 notifications, and usage tracking, see [Configuration](docs/configuration.md).
 For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 
-## Agent Skills
+## Multi-Agent Workflow
 
-projmux shortcuts can also live in your AI tool as user-level skills or slash
-commands. A skill is just a thin wrapper around the same CLI contract:
+Keep a shell and multiple managed agents visible in the same tmux window.
+Move between panes to start independent tasks while projmux collects their
+permission and completion events in one notification queue.
+
+<p align="center">
+  <img src="docs/assets/projmux-three-pane-workflow.gif" alt="projmux shell, Codex, and Claude 3-pane workflow demo" width="820">
+  <br>
+  <em>Move across equal-width shell, Codex, and Claude panes while independent tasks report back through one notification queue.</em>
+</p>
+
+## Automation With Agent Skills
+
+AI tools can invoke the same projmux CLI to open a managed pane and deliver a
+prompt:
 
 ```sh
-projmux ai split --agent codex right
-projmux ai split --agent claude down
-projmux ai split --agent antigravity right
+projmux ai split --agent codex right -- "Review the retry logic."
 ```
 
-After registering a Claude slash command such as `/projmux:codex-right`, ask
-Claude to use it with a prompt. Claude runs the projmux command, Codex opens in
-a managed pane attached to the current project, and the prompt is delivered
-there immediately.
-projmux tracks hook events from the opened pane and shows permission or
-completion notifications in tmux.
-Antigravity uses the same managed split path, with manual hook ingest and
-session resume support documented in the CLI reference.
-
-Install templates and naming conventions are in
+Templates and naming conventions for Claude, Codex, and other agents are in
 [AI Agent Shortcuts](docs/ai-agent-shortcuts.md).
 
-<p align="center">
-  <img src="docs/assets/projmux-skill-workflow.gif" alt="projmux skill workflow demo" width="820">
-  <br>
-  <em>Claude invokes a registered projmux skill with a prompt, opens a managed Codex pane, and Codex answers there.</em>
-</p>
-
 ## More Docs
 
 - [Install](docs/install.md)

package/docs/agent-workflow.md

@@ -38,6 +38,7 @@
 - `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, response-complete live badge consume on attention clear without idling action-required/progress badges, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border, Alt-1 sidebar window/preview tabs, and tmux window-status compatibility with dot as the persisted/config fallback.
 - `make test` also covers AI semantic badge Phase 3 theme-role hardening: `@projmux_ai_badge_kind` storage values and aggregate priority stay unchanged, `minimal` remains a read-time alias for the `off` badge style, progress/success/action-required badge roles stay distinct, permission/input status badges do not use critical red, and critical notify queue severity does not drive live AI status badge colors or desktop notification urgency.
 - `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Settings delivery diagnostics that split logical key/raw bytes/tmux received key while distinguishing missing, ambiguous, adapter-needed, and delivered states, safe direct key pool and risky/reserved diagnostic-only copy, Projmux-owned Ghostty/Windows Terminal advanced delivery copy, raw escape/CSI-u/xterm modified/UserKey/UserSequence rejection from primary keymap storage, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- `make test` covers the default picker key ownership across catalog, generated tmux config, terminal adapters, setup probes, and native popup close hints: `Alt-4` opens AI Resume as a guaranteed launch default, while `Alt-7` opens the AI split picker as its editable default.
 - `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.
 - `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective|resume>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, resume picker routing/New delegation/zero-session fallback/Phase 1 fresh fallback contract, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.

package/docs/cli.md

@@ -705,18 +705,25 @@ fresh cached update is available, the shell welcome uses Enter=Continue,
 `${XDG_CACHE_HOME:-~/.cache}/projmux/update-skip.json` and suppresses that tag
 until a newer latest release appears.
 
-Installer detection honors
-`PROJMUX_INSTALLER=npm|go|github-release|source`. When unset or invalid,
-the source is reported as `unknown` with guidance to set the variable.
+Installer detection honors an explicit
+`PROJMUX_INSTALLER=npm|go|github-release|source` first. When it is unset,
+detection falls back to inspecting the running binary: an npm install tree
+(`node_modules/@projmux/...`) is reported as `npm`, a `go install …@latest`
+binary in `$GOBIN`/`$GOPATH/bin`/`~/go/bin` as `go`, and a local `go build`
+(`make install`) — which reports a `(devel)` main-module version — as `source`.
+`github-release` installs are indistinguishable from a hand-placed binary and
+still require an explicit `PROJMUX_INSTALLER=github-release`. Anything else is
+reported as `unknown` with guidance.
 `apply` is installer-aware and only runs after explicit user selection.
-For npm installs, it runs `npm update -g projmux` and then
-`projmux tmux apply` unless `--no-apply` is set. For Go installs, it
-delegates to the existing atomic `projmux upgrade` flow. For
-`github-release` installs, it downloads the latest matching
-`projmux_<version>_<goos>_<goarch>.tar.gz` release asset, extracts the
+For npm installs, it runs `npm install -g projmux@latest` (which reliably
+crosses minor/major versions where `npm update -g` does not, and re-resolves
+the per-platform optional dependency) and then `projmux tmux apply` unless
+`--no-apply` is set. For Go installs, it delegates to the existing atomic
+`projmux upgrade` flow. For `github-release` installs, it downloads the latest
+matching `projmux_<version>_<goos>_<goarch>.tar.gz` release asset, extracts the
 binary, atomically replaces the current executable, then applies tmux
 configuration unless `--no-apply` is set. `source` installs report an
-actionable error because they must be updated from the source checkout.
+actionable error to update the checkout with `git pull --ff-only && make install`.
 
 ## upgrade
 
@@ -729,7 +736,7 @@ projmux upgrade [--ref @latest|@<tag>|@<branch>]
 runs `projmux tmux apply` (skipped with `--no-apply`). Reads
 `PROJMUX_PROJDIR` from the calling shell and memoizes the primary entry
 to `~/.config/projmux/projdir`. npm-installed binaries reject this
-command; use `projmux update apply` or `npm update -g projmux` for npm
+command; use `projmux update apply` or `npm install -g projmux@latest` for npm
 installs.
 
 ## welcome

package/docs/keybindings.md

@@ -2,7 +2,7 @@
 
 projmux is keyboard-driven, but the guaranteed launch contract is small:
 fresh installs bind `Alt-1` through `Alt-5` as plain Meta sequences
-(`M-1`..`M-5`, bytes `\x1b1`..`\x1b5`). The AI resume picker ships with an
+(`M-1`..`M-5`, bytes `\x1b1`..`\x1b5`). The AI split picker ships with an
 editable `Alt-7` default. Other actions remain discoverable in
 Settings > Keybindings. Transport-dependent actions keep their built-in
 transport default key, and Settings can add separate safe tmux plain keys to
@@ -46,7 +46,7 @@ These shortcuts are the guaranteed launch defaults. They need no tmux prefix.
 | `Alt-1` | Project sidebar |
 | `Alt-2` | Notify sidebar |
 | `Alt-3` | Recent Windows |
-| `Alt-4` | AI split popup picker |
+| `Alt-4` | AI resume session picker |
 | `Alt-5` | Settings |
 
 `RecentWindows:Open` opens the cross-project recent windows queue. It switches
@@ -84,14 +84,14 @@ Optional direct keys can be added for actions such as:
 | --- | --- |
 | `RecentWindows:Open` | Recent windows queue across projects |
 | `ProjectSwitcherToggle` | Project switcher popup |
-| `AISplitPickerToggle` | AI split popup picker; pressing again closes the picker popup |
-| `AIResumePickerToggle` | AI resume session picker; default `Alt-7`; pressing again closes the picker popup |
+| `AISplitPickerToggle` | AI split popup picker; default `Alt-7`; pressing again closes the picker popup |
+| `AIResumePickerToggle` | AI resume session picker; default `Alt-4`; pressing again closes the picker popup |
 | `ai-split-right` | Open a new direct AI split to the right |
 | `ai-split-down` | Open a new direct AI split below |
 | `new-window` | New tmux window in the current pane directory |
 | `rename-window` | Rename the current tmux window |
 
-`AISplitPickerToggle` is the `Alt-4` popup picker toggle. It opens or closes
+`AISplitPickerToggle` is the `Alt-7` popup picker toggle. It opens or closes
 the picker UI where the user chooses the AI split mode. It is separate from
 the direct `ai-split-right` and `ai-split-down` actions.
 
@@ -194,7 +194,7 @@ Legacy popup IDs such as `sessionizer-sidebar`, `notify-sidebar`,
 names: `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
 `AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`. Direct
 AI split actions keep their command IDs, `ai-split-right` and `ai-split-down`,
-so Settings can distinguish them from the `Alt-4` popup picker toggle.
+so Settings can distinguish them from the `Alt-7` popup picker toggle.
 
 ## Diagnose: `projmux setup`
 

package/docs/native-picker-no-fzf-poc.md

@@ -179,7 +179,7 @@ Manual UX checks for the Docker sandbox:
 - Alt-1 opens with the top border/title visible, not clipped.
 - Vertical borders stay continuous while moving Up/Down.
 - Alt-1 closes the sidebar immediately when pressed again.
-- Alt-2, Alt-4, and Alt-5 open their matching native popups and close
+- Alt-2, Alt-4, Alt-5, and Alt-7 open their matching native popups and close
   on the same Alt key immediately.
 - Alt-3 opens Recent Windows.
 - Arrow keys move selection without leaking `^[[` text into the query.

package/docs/testing.md

@@ -95,9 +95,9 @@ Observe:
 - `Alt-1` opens the project sidebar.
 - `Alt-2` opens the notification sidebar.
 - `Alt-3` opens Recent Windows.
-- `Alt-4` opens the AI split picker.
+- `Alt-4` opens the AI resume session picker.
 - `Alt-5` opens Settings.
-- `Alt-7` opens the AI resume session picker.
+- `Alt-7` opens the AI split picker.
 - Pressing the same launch key again closes the popup instead of typing escape
   bytes into the shell or picker input.
 

package/docs/upgrading.md

@@ -25,10 +25,18 @@ projmux update apply
 Use `--dry-run` to see the planned action and `--no-apply` to skip reloading
 the live tmux config after the binary changes.
 
-Shell Upgrade invokes only `projmux update apply`. Shell Skip until next stores
-the current latest release tag in `update-skip.json`; the prompt appears again
-when the cached latest tag changes. For `source` and unknown installer sources,
-Upgrade prints guidance and continues shell entry without applying anything.
+Shell Upgrade invokes only `projmux update apply`, then reports success or the
+specific failure inline and continues into the shell either way (a failed
+upgrade is never fatal to shell entry). Shell Skip until next stores the current
+latest release tag in `update-skip.json`; the prompt appears again when the
+cached latest tag changes. For `source` and unknown installer sources, Upgrade
+prints guidance and continues shell entry without applying anything.
+
+The installer is detected from an explicit `PROJMUX_INSTALLER` first, then
+inferred from the running binary when unset (npm install tree → `npm`,
+`go install …@latest` binary in `$GOBIN`/`$GOPATH/bin`/`~/go/bin` → `go`, a
+local `go build`/`make install` `(devel)` binary → `source`). `github-release`
+still requires an explicit `PROJMUX_INSTALLER=github-release`.
 
 ## Behavior Changes
 
@@ -118,12 +126,20 @@ npm install -g projmux
 For npm-managed installs, `projmux update apply` runs:
 
 ```sh
-npm update -g projmux
+npm install -g projmux@latest
 projmux tmux apply
 ```
 
+`npm install -g projmux@latest` is used instead of `npm update -g projmux`
+because `npm update -g` honors the installed semver range and frequently
+refuses to move a global install across a newer minor/major release, leaving it
+stuck on an old version. `install -g …@latest` always fetches the newest
+published release and re-resolves the per-platform optional dependency.
+
 The npm shim sets `PROJMUX_INSTALLER=npm` so projmux can detect this path
-automatically. You can also update manually with `npm update -g projmux`.
+automatically. Even when the shim is bypassed, projmux infers the npm install
+from the binary path (`node_modules/@projmux/...`). You can also update manually
+with `npm install -g projmux@latest`.
 
 ## Go Installs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.7.2",
-    "@projmux/linux-arm64": "0.7.2",
-    "@projmux/darwin-x64": "0.7.2",
-    "@projmux/darwin-arm64": "0.7.2"
+    "@projmux/linux-x64": "0.7.4",
+    "@projmux/linux-arm64": "0.7.4",
+    "@projmux/darwin-x64": "0.7.4",
+    "@projmux/darwin-arm64": "0.7.4"
   }
 }