projmux 0.6.1 → 0.6.2

package/README-ko.md

@@ -12,7 +12,11 @@ attention까지 함께 다루는 터미널 workspace 도구입니다.
 
 [English README](README.md)
 
-![projmux shell project sidebar demo](docs/assets/projmux-shell-sidebar.gif)
+<p align="center">
+  <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
+  <br>
+  <em>다른 프로젝트에서 일하는 동안 agent 작업이 끝나면 notification에서 바로 해당 pane으로 돌아갑니다.</em>
+</p>
 
 ## 무엇인가
 
@@ -88,6 +92,7 @@ projmux shell
 - [Hooks](docs/hooks.md)
 - [Usage tracking](docs/usage-tracking.md)
 - [Agent Workflow](docs/agent-workflow.md)
+- [README Hero GIF Recording](docs/readme-hero-gif-recording.md)
 
 ## 개발
 

package/README.md

@@ -4,24 +4,41 @@
   <img src="docs/assets/projmux-icon.png" alt="projmux icon" width="112">
 </p>
 
-Project-aware tmux workspaces with fast switching, previews, status context,
-and AI-pane attention built in.
+<p align="center">
+  <strong>A tmux-native workspace for multi-agent AI development.</strong>
+  <br>
+  <em>First-class Claude Code and Codex integration with hook-driven attention and agent-aware session resume.</em>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/projmux?logo=npm)](https://www.npmjs.com/package/projmux)
-[![CI](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml/badge.svg)](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml)
+<p align="center">
+  <a href="https://www.npmjs.com/package/projmux"><img src="https://img.shields.io/npm/v/projmux?logo=npm" alt="npm version"></a>
+  <a href="https://github.com/crevissepartners/projmux/actions/workflows/ci.yml"><img src="https://github.com/crevissepartners/projmux/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/crevissepartners/projmux" alt="MIT license"></a>
+  <a href="README-ko.md"><img src="https://img.shields.io/badge/lang-한국어-blue" alt="Korean README"></a>
+</p>
 
-[Korean README](README-ko.md)
+```sh
+npm install -g projmux
+projmux shell
+```
 
-![projmux shell project sidebar demo](docs/assets/projmux-shell-sidebar.gif)
+<p align="center">
+  <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
+  <br>
+  <em>An agent finishes in another project. Open notifications, select it, and jump straight back.</em>
+</p>
 
-## What It Is
+## Why
 
-`projmux` turns project directories into durable tmux sessions. It gives you a
-keyboard-first workspace app for switching projects, previewing sessions,
-opening AI splits, and keeping useful context visible in tmux.
+Six tmux windows. Each one is running Claude Code or Codex on a different
+repo. Three are idle. One is waiting on a permission prompt. One crashed an
+hour ago and you have no idea which.
 
-Use it when you want one command to open your terminal workspace and one set of
-keys to move between projects, windows, panes, notifications, and settings.
+projmux ingests Claude Code and Codex hook events directly, shows live
+per-pane state in the tmux status bar, and lets one keystroke take you to
+the pane that actually needs you. It also remembers each agent's resume id,
+so after a reboot every pane comes back as the *same* conversation — not a
+fresh one.
 
 ## Requirements
 
@@ -32,14 +49,12 @@ Run `projmux doctor` after installing to check the local runtime.
 
 ## Install
 
-```sh
-npm install -g projmux
-projmux version
-```
+The npm package shown above installs a small Node.js shim plus the matching
+projmux binary for Linux and macOS on x64 or arm64. npm is the primary
+distribution path for normal users.
 
-The npm package installs a small Node.js shim plus the matching projmux binary
-for Linux and macOS on x64 or arm64. npm is the primary distribution path for
-normal users.
+Verify with `projmux version`. Then `projmux doctor` checks the local runtime
+(tmux 3.4+ and hook integration health).
 
 Manual Go, source checkout, GitHub Release, and packaging details live in
 [Install](docs/install.md).
@@ -84,11 +99,13 @@ For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 - [Install](docs/install.md)
 - [Configuration](docs/configuration.md)
 - [Terminal Keybindings](docs/keybindings.md)
+- [AI Agent Shortcuts](docs/ai-agent-shortcuts.md)
 - [CLI Reference](docs/cli.md)
 - [Statusbar](docs/statusbar.md)
 - [Hooks](docs/hooks.md)
 - [Usage tracking](docs/usage-tracking.md)
 - [Agent Workflow](docs/agent-workflow.md)
+- [README Hero GIF Recording](docs/readme-hero-gif-recording.md)
 
 ## Development
 

package/docs/agent-workflow.md

@@ -30,7 +30,10 @@
 - `make fix`: safe automatic fixes such as `go fix` and repository-approved cleanup steps.
 - `make npm-pack`: local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages.
 - `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including branch block styling, statusbar pwd display-only native-framed path popup, no clipboard or tmux buffer copy, and simple Enter-close popup command, statusbar usage native HUD popup alignment/threshold/sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, first-run/version-bump shell welcome state and inline update handling, shell startup update prompt actions for fresh installer-aware cached updates, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, and no-live-tmux save behavior, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
-- `make test` also covers Settings IA regression guards for `send-noti` visibility in Hooks, no nested Project recipe inside Hooks, Project recipe/AI/Labs view-first detail rows, Notifications root/Desktop notifications/Delivery sources relocation, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
+- `make test` also covers direct `projmux ai split --agent <claude|codex|shell|selective>` launches, 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, and invalid direct-agent usage errors.
+- `make test` also covers Settings IA regression guards for `send-noti` visibility in Hooks, no nested Project recipe inside Hooks, Project recipe/AI/Labs view-first detail rows, Appearance Path/Git/Notify icon direct off/symbol/emoji preview selection with no Change page, Notifications root/Desktop notifications/Delivery sources relocation, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
+- `make test` also covers AI desktop notification dedupe precedence (env override > Settings saved value > default), configured dedupe-window collapse/send behavior, Settings > Notifications AI dedupe preset/custom rows, explicit notify focus consume rules for selected critical rows and older same-pane non-critical AI cleanup, preservation of critical/permission/stop-failure/external/git/k8s rows during bulk cleanup, OS Toast click-to-focus queue consume, WSL Toast protocol handler hidden-launcher registration with `wsl.exe --exec` URI forwarding, and attention clear paths that do not ack the queue.
+- `make test` also covers AI hook runtime action precedence over catalog defaults, runtime quiet for known Codex notify events, runtime notify for known Claude quiet events, generic in-app-only notify rows for known Codex hook events without specialized handlers, suppression of desktop notification and `send-noti` dispatch on that generic path, separation of runtime hook action from catalog install events, Settings > Notifications hook quiet policy display/write behavior without external install/remove execution, hook desktop notification payload parity with the in-app queue text across the shared OS notification payload, normal/transient OS urgency and expiration for critical AI queue rows, and dormant title/capture fallback gating once a pane is hook-active.
 - `make test` also covers Settings > Session State as global settings-only UI with default-off auto-save and no window/pane tree, Settings > Project > Session State project-derived identity plus project auto-save override/effective source rows and distinct Save latest snapshot / Save named snapshot labels, closed-project save disabled reasons, named snapshot portable path conversion, project/global auto-save precedence, Projects > Sessions > State read-only latest/named snapshot overview with window/pane cwd/recipe/agent-resume health, user-facing `projmux session-state` status/save/delete/restore dry-run actions including explicit manual save bypass of disabled autosave and agent resume status/confidence preview, and Project open sidebar startup coverage for Labs opt-in `Start project`, default-off empty creation, Latest snapshot, Named snapshot, Empty session, Back, saved-at row metadata, existing-session skip, startup-before-trust ordering, trust approve continuation, and trust deny/cancel no-session behavior.
 - `make test` also covers `projmux shell` usage without startup selector flags, project-context default target lookup from `PROJMUX_CWD` or nearest project marker, explicit `--session` separation from project-derived defaults, and direct empty attach behavior without shell startup picker/replay.
 - `make test` also covers manual Session State Save snapshot and restore dry-run preview actions, title-first pane preview labels with legacy snapshot fallback, missing-snapshot messaging, and the absence of the removed statusbar State shortcut.
@@ -42,11 +45,14 @@
 - `make test` also covers `projmux ai integrate tmux-bell` dry-run/install/remove tmux command planning, managed `alert-bell` hook append/idempotence/removal, preservation of unmanaged bell hooks, and `projmux ai ingest bell --pane` queue push/metadata/dedupe behavior for non-AI-managed panes.
 - `make test` also covers `projmux ai ingest log` tail/path rendering and bounded JSONL log trimming for ingest diagnostics.
 - `make test` also now covers onboarding revisit and welcome wiring (`projmux welcome`, `Settings > About > Welcome`, `pending_attach_welcome`, attach-time `welcome --popup` one-time claim/env suppression/tmux popup payload, and generated `client-attached` app config wiring) via shell welcome tests.
+- `make test` also covers `projmux quit` action-picker rows, cancel/close no-op behavior, explicit quit of only app-owned `tmux -L projmux` runtimes marked by `@projmux_app=1`, missing/default runtime no-ops, dispatcher wiring, and `Settings > About > Quit projmux` routing through the same picker before any shutdown side effect.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,
   reconcile reports stale rows), `notify list --live` queue/live explanations, notify sidebar
   two-line card rendering with age/project/window/pane metadata plus focus/ack/clear-all
-  actions, and `focus` dispatch diagnostics for session fallback, unresolved
+  actions, including in-place `x` ack that refreshes the sidebar without
+  focusing, preserves selection position where possible, and renders the empty
+  state after the last row is acked, and `focus` dispatch diagnostics for session fallback, unresolved
   targets, window fallback, pane fallback, explicit id failures as unresolved exits, and
   notify-only fallback.
 - Picker focused unit coverage includes backend-neutral picker item/action mapping, native title-focused filtering, numeric selection, shared close actions including raw and CSI-u Ctrl-X native custom actions, deprecated picker backend value normalization, AI picker title chrome and stable search-key ordering, Settings title chrome and root section order, Settings Labs shell without backend choices plus keybinding diagnostic list/detail/probe outcome/init delegation coverage, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, multiline partial next/previous item row rendering with rendered-row scrollbar units, fixed split-preview and sidebar list viewports with scrollbar tracks, native up/down-family navigation wrap with empty-list safety and PageUp/PageDown/Home/End clamp regression coverage, native mouse down/follow-drag/release behavior, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with titlebar border reset guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, and notify sidebar title/popup sizing.

package/docs/ai-agent-shortcuts.md

@@ -0,0 +1,264 @@
+# AI Agent Shortcut Registration
+
+`projmux ai split` is intentionally tool-general: user-level shortcuts,
+skills, slash commands, terminal actions, and editor commands can all map to
+the same split contract.
+
+```sh
+projmux ai split --agent <agent> <right|down>
+projmux ai split --agent <agent> <right|down> -- <extra args...>
+```
+
+Use this page for shareable registration patterns. Keep machine-local policy,
+private prompt text, and personal workflow recipes in your own dotfiles or
+local tool configuration, not in tracked repo docs.
+
+## Command Contract
+
+Choose a direct agent when a shortcut should always open that agent:
+
+```sh
+projmux ai split --agent codex right
+projmux ai split --agent claude down
+```
+
+Add the separator only when you have extra arguments for the selected agent:
+
+```sh
+projmux ai split --agent codex right -- --model <model>
+projmux ai split --agent claude down -- <agent flags>
+```
+
+The `--` separates projmux arguments from agent arguments. Everything after
+that separator is passed to the resolved selected agent executable. It is not
+an executable override. In the examples above, projmux still chooses the
+configured `codex` or `claude` executable, creates the tmux split, sets pane
+metadata, applies the title watcher, and appends the tail arguments to the
+agent command.
+
+Model, permission, and other agent flags are examples to customize privately in
+your user-level config. Avoid treating placeholder flags in this guide as
+project defaults or current recommendations. If there are no private extra
+arguments, omit the separator entirely; do not leave a trailing bare `--`.
+
+`shell` and `selective` are not targets for extra agent arguments. Use them
+without a tail:
+
+```sh
+projmux ai split --agent shell right
+projmux ai split --agent selective down
+```
+
+`shell` opens a plain shell split. `selective` opens the existing picker, where
+the user chooses the launch mode interactively.
+
+## Naming Pattern
+
+Pick names that encode the target agent and split direction, then keep the
+body as a small command wrapper.
+
+For Codex-style skill surfaces, names can follow:
+
+```text
+$projmux-<agent>-right
+$projmux-<agent>-down
+```
+
+Concrete examples:
+
+```text
+$projmux-codex-right
+$projmux-claude-down
+```
+
+For Claude-style slash-command surfaces, names can follow:
+
+```text
+/projmux:<agent>-right
+/projmux:<agent>-down
+```
+
+Concrete examples:
+
+```text
+/projmux:codex-right
+/projmux:claude-down
+```
+
+The same pattern also works for editor commands, launcher actions, shell
+aliases, or terminal custom actions. The important part is that the registered
+surface calls `projmux ai split --agent <agent> <direction>` and passes only
+agent flags after `--`.
+
+### Bare-Name Default
+
+When a surface registers a bare agent name without an explicit direction
+suffix, treat it as the `right` variant. `right` is the convention for the
+unqualified shortcut; `down` is always spelled out.
+
+For Codex-style skill surfaces:
+
+```text
+$projmux-codex      → projmux ai split --agent codex right
+$projmux-claude     → projmux ai split --agent claude right
+```
+
+For Claude-style slash-command surfaces:
+
+```text
+/projmux:codex      → projmux ai split --agent codex right
+/projmux:claude     → projmux ai split --agent claude right
+```
+
+Register the bare name as a thin alias of the `*-right` shortcut so that the
+two surfaces stay in lockstep. The `*-down` variant must be invoked by its
+full name; do not introduce a separate bare default for `down`.
+
+## Skill Template
+
+Use this shape when a tool lets you define a user-level skill that tells an
+agent to run a shell command. Actual loader paths vary by installation; the
+intended home is user-level config or dotfiles, not this repository.
+
+Example Codex-style skill file:
+
+```text
+~/.codex/skills/projmux-codex-right/SKILL.md
+```
+
+````markdown
+---
+name: projmux-codex-right
+description: Open a projmux-managed Codex split to the right.
+---
+
+Run this command:
+
+```sh
+projmux ai split --agent codex right
+```
+
+If you have private Codex flags, use the explicit extra-args form instead:
+
+```sh
+projmux ai split --agent codex right -- --model <model>
+```
+````
+
+Non-Codex target example:
+
+```text
+~/.codex/skills/projmux-claude-down/SKILL.md
+```
+
+````markdown
+---
+name: projmux-claude-down
+description: Open a projmux-managed Claude split below.
+---
+
+Run this command:
+
+```sh
+projmux ai split --agent claude down
+```
+
+If you have private Claude flags, use the explicit extra-args form instead:
+
+```sh
+projmux ai split --agent claude down -- <agent flags>
+```
+````
+
+If your tool stores skills as JSON, TOML, or another format, keep the same
+fields conceptually:
+
+- Name: the user-facing shortcut, such as `$projmux-codex-right`.
+- Description: one sentence saying which agent and direction it opens.
+- Command: the `projmux ai split` invocation.
+- Arguments: optional agent arguments placed after `--`.
+
+## Slash Command Template
+
+Use this shape when a tool lets you define user-level slash commands. Actual
+loader paths and interpolation variables can vary by installation; user-level
+config or dotfiles is the intended home.
+
+```text
+~/.claude/commands/projmux/codex-right.md
+```
+
+This maps to a slash command named `/projmux:codex-right`:
+
+````markdown
+Open a Codex split to the right in the current projmux session.
+
+Run this command:
+
+```sh
+projmux ai split --agent codex right
+```
+````
+
+For an argument-aware wrapper, include the separator only when arguments are
+non-empty. Adapt this shell shape to the tool's command-file format:
+
+```sh
+if [ -n "$ARGUMENTS" ]; then
+  projmux ai split --agent codex right -- $ARGUMENTS
+else
+  projmux ai split --agent codex right
+fi
+```
+
+Then invoke it with private agent flags only when needed, such as
+`/projmux:codex-right --model <model>`.
+
+For a Claude target, use a sibling file such as:
+
+```text
+~/.claude/commands/projmux/claude-down.md
+```
+
+This maps to `/projmux:claude-down`:
+
+````markdown
+Open a Claude split below in the current projmux session.
+
+Run this command:
+
+```sh
+projmux ai split --agent claude down
+```
+````
+
+For an argument-aware wrapper, use the same non-empty check:
+
+```sh
+if [ -n "$ARGUMENTS" ]; then
+  projmux ai split --agent claude down -- $ARGUMENTS
+else
+  projmux ai split --agent claude down
+fi
+```
+
+Then pass private Claude flags at invocation time only when needed, such as
+`/projmux:claude-down <agent flags>`.
+
+If the tool separates command metadata from the shell body, put only the
+`projmux ai split ...` line in the executable body. Avoid embedding
+machine-specific project roots, permission policies, or personal model choices
+in shared docs; put those in your private user-level command files.
+
+## Checklist
+
+- Register shortcuts at user level in the AI tool, editor, launcher, or
+  terminal that owns the surface.
+- Use `--agent codex` or `--agent claude` when passing extra agent arguments.
+- Put agent flags after the separator, for example `-- --model <model>`.
+- Omit the separator entirely when there are no extra agent arguments.
+- Use `--agent shell` with no tail for a plain shell split.
+- Use `--agent selective` with no tail for the picker.
+- Treat a bare agent name (`/projmux:codex`, `$projmux-claude`) as the
+  `right` variant; spell out `*-down` shortcuts in full.
+- Keep tracked project docs and `AGENTS.md` free of private shortcut policy.

package/docs/cli.md

@@ -31,6 +31,7 @@ projmux <command> [args...]
 | `pin` | Manage pinned project directories. |
 | `preview` | Manage persisted tmux preview selection. |
 | `prune` | Trim stale tmux lifecycle state. |
+| `quit` | Quit the app-owned projmux tmux runtime. |
 | `sessions` | Pick and open an existing tmux session. |
 | `session-popup` | Read tmux popup preview state. |
 | `settings` | Configure projmux. |
@@ -318,7 +319,7 @@ supplied window.
 ## ai
 
 ```
-projmux ai split    --inside <right|down> [--agent <name>] ...
+projmux ai split    [--agent <claude|codex|shell|selective>] [right|down] [-- <extra-arg>...]
 projmux ai picker   --inside <right|down>
 projmux ai settings
 projmux ai status   set <thinking|waiting|idle> [--pane <id>]
@@ -340,6 +341,16 @@ notifier. `status set waiting` is the trigger that flips a pane to the
 reply-ready state — that transition pushes an `ai:<session>:<pane>`
 entry into the notify queue.
 
+`ai split right|down` uses the configured default split mode. Add
+`--agent claude`, `--agent codex`, `--agent shell`, or `--agent selective` for
+a one-shot launch without changing that default. `--agent selective` opens the
+existing picker flow; `--agent shell` opens the existing plain shell split.
+Arguments after `--` are extra arguments appended to the resolved `claude` or
+`codex` executable inside the managed wrapper; projmux still sets the context
+directory, tmux title, AI pane metadata, title watcher, and split layout.
+For user-level skill, slash-command, editor, or launcher registrations that
+call this contract, see [AI Agent Shortcuts](ai-agent-shortcuts.md).
+
 `ingest codex-hook` is the hook-facing entrypoint for Codex hooks-engine JSON.
 It reads one JSON payload from stdin and handles the default Codex hook catalog
 `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
@@ -357,6 +368,17 @@ to quiet/log-only handling. A local catalog entry with `"action": "quiet"`
 therefore lets newly discovered events be installed and observed without
 creating notification noise; `"notify"` and `"state"` still require a built-in
 handler before they can change pane state or push queue rows.
+Runtime action overrides from
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json` take
+precedence over catalog `action` during ingest, including known events such as
+`Stop` and `PermissionRequest`. These overrides are managed by
+`Settings > Notifications > Hook quiet policy` and do not change the catalog
+`install` field used by `projmux ai integrate codex`. A runtime `notify`
+override for a known Codex event without a specialized handler, such as
+`PreToolUse` or `PostToolUse`, pushes a short generic in-app row like
+`Codex · PreToolUse · Bash`. Generic rows are queue/sidebar/statusbar only and
+do not dispatch OS desktop notifications, `PROJMUX_NOTIFY_HOOK`, or
+`[hooks.send-noti]`.
 
 `ingest claude-hook` is the hook-facing entrypoint for Claude Code hooks. It
 reads one JSON payload from stdin and handles the default Claude Code 2.1.140
@@ -378,6 +400,11 @@ push a queue entry.
 Unknown Claude events also fall back to quiet/log-only handling after pane
 matching. Catalog `action` is honored for quiet fallback events; notify/state
 actions need built-in handlers for event-specific body text and state changes.
+Runtime action overrides from
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json` take
+precedence over catalog `action` for known Claude events too; for example a
+noisy notify event can be made state-only or quiet without changing installed
+Claude hook commands.
 
 `ingest bell --pane <pane_id>` is the narrow tmux-bell fallback ingest path.
 It does not require the pane to be AI-managed. Projmux resolves session,
@@ -653,7 +680,7 @@ flags with the top-level `switch` UX:
   retention window.
 - `tag` — manage the tagged-selection set.
 
-## current / shell / attach / settings
+## current / shell / attach / settings / quit
 
 - `current` — print `pane_current_path` for the active tmux pane (used
   by the shell jump binding).
@@ -666,6 +693,12 @@ flags with the top-level `switch` UX:
   snapshot`, and `Empty session` before creating a closed project session.
   `Latest snapshot` is auto-saved; named snapshots are fixed until the user
   saves or replaces them.
+- `quit` — open an action picker with `Quit projmux` and `Cancel`. Selecting
+  `Quit projmux` terminates only a `tmux -L projmux` runtime whose global
+  `@projmux_app` option is set by the generated app config. Missing servers,
+  default tmux servers, embedded tmux servers, and other tmux runtimes without
+  that marker are no-ops. Non-interactive callers must pass `--yes` or
+  `--force`; the default command always goes through the action picker.
 - `attach auto [--keep=N] [--fallback=home|ephemeral]` — auto-attach to
   the most recent session, with bounded retention and a fallback policy.
 - `settings` — interactive configuration UI for the project picker, AI
@@ -686,9 +719,10 @@ flags with the top-level `switch` UX:
   available for experimental settings. The About section reads the cached
   update status without network access;
   selecting Check Updates runs `projmux update check`, and Update Now runs
-  `projmux update apply`. The same About section also lists the keybinding
-  diagnostic path: zero-config first, `setup` for swallowed keys, `init` for
-  supported terminal fallbacks, and `doctor` for dependencies.
+  `projmux update apply`. `Settings > About > Quit projmux` routes through the
+  same `projmux quit` action picker. The same About section also lists the
+  keybinding diagnostic path: zero-config first, `setup` for swallowed keys,
+  `init` for supported terminal fallbacks, and `doctor` for dependencies.
 
 ## See also
 

package/docs/configuration.md

@@ -156,6 +156,7 @@ configured key opens and closes the popup.
 | `TMUX_SESSIONIZER_ROOTS` | Legacy alias still honored at runtime for managed roots. |
 | `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in Linux/WSL sender. Separate from declarative `[hooks.send-noti]`. |
 | `PROJMUX_NOTIFY_HOOK_DEPTH` | Internal recursion guard for `send-noti` hooks. Depth `>= 1` suppresses nested hook dispatch while still allowing the queue write itself. |
+| `PROJMUX_NOTIFY_EXPIRE_MS` | AI desktop notification expiration in milliseconds. Defaults to `5000`; unset, zero, negative, and non-numeric values fall back to the default. |
 | `PROJMUX_DESKTOP_NOTIFY_MODE` | OS desktop notification mode override. `none` / `notify` / `raise` (case insensitive). When set, this takes priority over every other resolution rung. The in-app notify queue is not affected. |
 | `PROJMUX_DESKTOP_NOTIFY` | Legacy on/off override kept for backward compatibility. `on` maps to `notify`, `off` maps to `none`. Honored only when `PROJMUX_DESKTOP_NOTIFY_MODE` is unset. |
 | `PROJMUX_WSL_TOAST_ICON_DIR` | Directory used when copying the WSL toast icon into a Windows-readable path. |
@@ -205,7 +206,17 @@ This environment variable remains the imperative "replace desktop notification
 sender" escape hatch. It does not run through the declarative hook trust/config
 system and it does not receive the notify-queue JSON payload. For additive
 forwarding after a successful queue write, prefer `[hooks.send-noti]` in
-`config.toml`.
+`config.toml`. The `urgency` argument is the OS notification urgency, not the
+internal notify-queue severity; AI desktop notifications default to OS urgency
+`normal` even when the statusbar, Alt-2, and persistent queue row remain
+critical.
+
+AI desktop notifications are transient by default. Linux `notify-send` receives
+`--urgency=normal` and `--expire-time=${PROJMUX_NOTIFY_EXPIRE_MS:-5000}`. WSL
+PowerShell Toasts use `duration="short"` and set `ExpirationTime` explicitly.
+If WSL falls back to `wsl-notify-send.exe`, urgency and expiration are
+best-effort because that adapter does not expose a stable equivalent for every
+host setup.
 
 `[hooks.send-noti]` and `PROJMUX_NOTIFY_HOOK` can coexist:
 
@@ -221,6 +232,38 @@ the Linux `--app-name`, the macOS sender label, and the Windows
 ships with a one-shot Windows cleanup that removes the legacy Start Menu
 shortcut and registry entry the first time projmux runs.
 
+AI desktop notifications collapse repeated pane-local notifications using a
+seconds window. Resolution priority is:
+
+1. `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS`
+2. Settings saved value at
+   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-notify-dedupe-seconds`
+3. default `120`
+
+Settings exposes this at `Settings > Notifications > AI notification dedupe`.
+The value is stored as integer seconds and applies only to AI desktop
+notification dispatch. The tmux bell fallback keeps its fixed 5 second
+dedupe window.
+
+AI hook runtime actions are stored at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json
+```
+
+Settings exposes this at `Settings > Notifications > Hook quiet policy`.
+The file maps provider/event names to `notify`, `state`, or `quiet` and
+overrides catalog `action` values during ingest, including known Codex and
+Claude events. It does not change hook installation; `projmux ai integrate`
+continues to use the embedded/local catalog `install` fields.
+
+Delivery depends on the event handler. Specialized notify handlers, such as
+Codex `PermissionRequest` and `Stop`, can write the in-app notify queue and use
+the configured OS desktop notification path. Known Codex events without a
+specialized handler can be runtime-overridden to `notify`, but that creates
+only a generic in-app queue/sidebar/statusbar row; it does not fire OS toast,
+`notify-send`, `PROJMUX_NOTIFY_HOOK`, or `[hooks.send-noti]`.
+
 ### Desktop notification mode
 
 The OS-level dispatch carries three modes. The in-app notify queue, the
@@ -236,7 +279,7 @@ gated here.
 
 Click activation is wired only for `raise`. The `projmux://` URI handler is
 registered on the first `raise` Notify of each tmux server (gated by the
-`@projmux_uri_protocol_registered_v2` marker). The
+`@projmux_uri_protocol_registered_v6` marker). The
 mode only controls whether a toast fires at all and whether to follow it
 up with an on-push auto-raise.
 
@@ -276,7 +319,16 @@ the first time a Toast is dispatched on each tmux server. Clicking the
 toast hands control back to projmux inside WSL via the registered command:
 
 ```text
-wsl.exe -d $WSL_DISTRO_NAME --exec <absolute-path-to-projmux> focus --uri "%1"
+wscript.exe //B //Nologo "%LOCALAPPDATA%\projmux\projmux-uri-handler.vbs" "%1"
+```
+
+Registration writes the VBScript launcher under `%LOCALAPPDATA%\projmux`.
+The launcher receives `%1` as a WScript argument, caret-escapes command-line
+metacharacters such as `&`, and starts a hidden `%ComSpec% /d /s /c` command
+that invokes `wsl.exe`. Its argv semantics are equivalent to:
+
+```text
+wsl.exe -d $WSL_DISTRO_NAME --exec <absolute-path-to-projmux> focus --uri <uri>
 ```
 
 For click activation to work in our unpackaged Win32 setup, four
@@ -298,13 +350,17 @@ notify path so users do not configure anything:
    silently quarantines such shortcuts moments after creation, which
    leaves no AppID-tagged shortcut and breaks both the routing and the
    click path. `cmd.exe /c exit` is treated as benign and survives.
-4. The WSL handler command uses `--exec`, not `--`. `wsl.exe -- <cmd>`
-   routes its tail through the user's login shell, which parses `&`
-   query-string separators as background-job operators (zsh emits
-   `parse error near '&'`). `--exec` skips the shell and invokes the
-   binary directly. The absolute WSL filesystem path to the binary is
-   captured at registration so PATH does not need to be populated under
-   `--exec`.
+4. The WSL handler uses a WScript launcher instead of launching `wsl.exe` or
+   `powershell.exe` directly, avoiding the transient Windows console flash on
+   Toast click. Inside that launcher it still uses `--exec`, not `--`.
+   `wsl.exe -- <cmd>` routes its tail through the user's login shell, which
+   parses `&` query-string separators as background-job operators (zsh emits
+   `parse error near '&'`). `--exec` skips the shell and invokes the binary
+   directly. The `%1` URI is passed as a WScript argument and then forwarded
+   through a hidden cmd.exe command line with `&` escaped as `^&`, so query
+   separators are data instead of PowerShell, cmd, or WSL login-shell syntax.
+   The absolute WSL filesystem path to the binary is captured at registration
+   so PATH does not need to be populated under `--exec`.
 
 The URI carries the originating pane id and tmux socket so the click
 round-trips back to the exact pane that fired the notification, which
@@ -315,12 +371,15 @@ Registration markers and the writes involved:
 - Registry keys (HKCU): `SOFTWARE\Classes\projmux\(Default)`,
   `SOFTWARE\Classes\projmux\URL Protocol`, and
   `SOFTWARE\Classes\projmux\shell\open\command\(Default)`.
-- tmux user-option marker `@projmux_uri_protocol_registered_v2` records that
+- Launcher file: `%LOCALAPPDATA%\projmux\projmux-uri-handler.vbs`.
+- tmux user-option marker `@projmux_uri_protocol_registered_v6` records that
   registration has been attempted on this server so the script runs at most
-  once per server boot. (The v1 marker `@projmux_uri_protocol_registered`
-  was bumped when the registry command switched to `--exec`; existing v1
-  users re-register transparently on the next Notify after upgrade and the
-  orphaned v1 key requires no cleanup.)
+  once per server boot. (The v5 marker
+  `@projmux_uri_protocol_registered_v5` was bumped when the WScript launcher
+  added the hidden cmd.exe parser hop; existing v5 users re-register
+  transparently on the next Notify after upgrade. After successful v6
+  registration, projmux removes legacy URI marker keys from v1 through v5 so
+  tmux state reflects only the active handler generation.)
 
 Limitations:
 
@@ -456,7 +515,7 @@ These are intended for debugging or local policy, not routine setup:
 
 | Variable | Purpose |
 | --- | --- |
-| `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` | Collapse window for duplicate AI notifications keyed on `(summary, tag)`. |
+| `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` | Override the Settings/default collapse window for duplicate AI desktop notifications keyed on the pane-local AI notification key. |
 | `PROJMUX_CODEX_TITLE_WATCH_INTERVAL` | Title-watch loop pacing for Codex panes. |
 | `PROJMUX_CODEX_REPLY_SETTLE_LOOPS` | Reply-detection settle-loop pacing for Codex panes. |
 | `TMUX_KUBE_CACHE_TTL` | Kubernetes status segment cache TTL. |

package/docs/hooks.md

@@ -199,6 +199,13 @@ Claude, and tmux AI notify diagnostics: status, conflicts, config paths, and
 copyable CLI install/remove/dry-run commands. It does not install or remove
 external Codex, Claude, or tmux settings.
 
+`PROJMUX_NOTIFY_HOOK` is separate from `[hooks.send-noti]`: it replaces the
+desktop sender and receives positional arguments
+`summary body urgency app-name tag group icon-path`. That `urgency` value is
+the OS notification urgency, not the notify-queue severity. AI approval,
+input, selection, and confirmation rows can stay critical in the queue and UI
+while the desktop notification hook receives `normal`.
+
 ## Codex Hooks Engine
 
 `projmux doctor` reports Codex hooks-engine wiring separately from legacy
@@ -325,6 +332,27 @@ catalog `"action": "quiet"` makes that quiet fallback explicit. Catalog
 `"notify"` and `"state"` entries still need a built-in handler before they can
 push queue rows or change pane state.
 
+Runtime action overrides are stored separately from the install catalog at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json
+```
+
+`Settings > Notifications > Hook quiet policy` reads and writes that file. The
+runtime file only changes ingest behavior (`notify`, `state`, or `quiet`);
+`projmux ai integrate codex` still uses the catalog `install` field to decide
+which hooks to write. Runtime overrides also apply to known specialized
+events, so `Stop` or `PermissionRequest` can be made state-only or quiet
+without changing which hook commands are installed. When a known Codex event
+without a specialized handler, such as `PreToolUse` or `PostToolUse`, is set to
+runtime `notify`, projmux pushes a generic in-app notify row such as
+`Codex · PreToolUse · Bash`. That generic path is queue/sidebar/statusbar only:
+it does not dispatch `[hooks.send-noti]`, `PROJMUX_NOTIFY_HOOK`, `notify-send`,
+or Windows toast.
+Generic metadata is limited to safe summary fields such as provider, event,
+tool, cwd, thread, session, turn, and model; raw payloads and tool input are
+not stored.
+
 Codex may require reviewing or trusting hooks through its `/hooks` flow before
 commands run. Projmux only writes the managed config block; it does not attempt
 to auto-trust hooks.
@@ -420,7 +448,10 @@ fire at high volume.
 Pane matching follows the shared AI ingest order: inherited `$TMUX_PANE`, then
 payload `cwd`, then cached session id pane options. A matched pane is marked
 with `@projmux_ai_hook_active=1`, so `projmux ai watch-title` skips the pane
-and hook payloads become the primary signal.
+after a minimal hook-active gate instead of polling pane title/capture output;
+hook payloads become the primary signal. The tmux bell fallback does not mark
+panes hook-active, so title/capture fallback remains available for panes that
+only emit bells.
 
 The Claude hook payload is intentionally accepted directly at the ingest
 boundary. Core identity fields accept `hook_event_name`/`event_name`,
@@ -558,11 +589,16 @@ and ingest debugging only.
 ```
 
 Claude ingest has built-in notify/state handlers for the known completion,
-notification, approval, prompt-submit, error, and teammate-idle events. Events
-without a specialized handler, including unknown future events, are
-quiet/log-only after pane matching. Catalog `"action": "quiet"` is used for
+notification, approval, prompt-submit, error, subagent-stop, and teammate-idle
+events. Events without a specialized handler, including unknown future events,
+are quiet/log-only after pane matching. Catalog `"action": "quiet"` is used for
 that fallback; catalog `"notify"` and `"state"` entries still need built-in
-handler code for event-specific queue rows or state transitions.
+handler code for event-specific queue rows or state transitions. Runtime action
+overrides live in the same
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json` file used by
+Codex and are managed from `Settings > Notifications > Hook quiet policy`.
+They only affect ingest delivery; `projmux ai integrate claude` still uses the
+catalog `install` field for installed hook events.
 
 ## Ingest Debug Log
 

package/docs/keybindings.md

@@ -80,6 +80,13 @@ These open the projmux popups and the sidebar. No prefix needed.
 When a pane closes, projmux re-spreads remaining panes so the surviving split
 does not stretch lopsided.
 
+The AI split bindings use the configured default mode. For one-shot launches,
+run `projmux ai split --agent claude|codex|shell|selective right|down`. Extra
+args after `--` are appended to the resolved `claude` or `codex` executable for
+a managed pane. To register user-level skills, slash commands, editor actions,
+or launcher shortcuts that call those one-shot launches, see
+[AI Agent Shortcuts](ai-agent-shortcuts.md).
+
 ### Inside the pickers
 
 | Surface | Shortcut | Action |

package/docs/notify-os-focus-poc.md

@@ -279,8 +279,10 @@ carries a `launch="projmux://focus?..." activationType="protocol"`
 attribute, and the first dispatch of a tmux server boot registers the
 `projmux://` scheme in `HKCU\SOFTWARE\Classes\projmux\…` so Windows
 routes the click to
-`wsl.exe -d <distro> --exec <abs-path> focus --uri "%1"`. Inside WSL,
-`projmux focus --uri` parses the URI, resolves the pane id to its
+`powershell.exe -NoProfile -WindowStyle Hidden ... "%1"`. That hidden
+launcher starts `wsl.exe -d <distro> --exec <abs-path> focus --uri <uri>`
+without routing the URI through a shell. Inside WSL, `projmux focus --uri`
+parses the URI, resolves the pane id to its
 `session:window.%paneID` target via `tmux display-message`, and reuses
 the existing focus dispatch. This closes the previously-deferred (a)
 on-push trigger mode in the Windows-only scope: the toast becomes the
@@ -325,13 +327,20 @@ machine is:
    leaves no AppID-tagged shortcut at all and breaks both the toast
    routing and (since the AppID has to be live when the toast fires) the
    click path. `cmd.exe /c exit` is benign and survives.
-4. **WSL handler command uses `--exec` not `--`**. `wsl.exe -- <cmd>`
-   routes its tail through the user's default login shell, which parses
-   `&` query-string separators as background-job operators (zsh emits
-   `parse error near '&'`). `--exec` skips the shell and invokes the
-   binary directly. PATH is empty under `--exec`, so the registry
-   command uses the absolute WSL filesystem path captured at registration
-   time.
+4. **WSL handler command uses a GUI launcher and keeps `--exec`**. The
+   registry protocol handler launches `wscript.exe //B //Nologo` with a
+   VBScript launcher written under `%LOCALAPPDATA%\projmux`, so ShellExecute
+   does not start a console-subsystem first process. The launcher starts a
+   hidden `%ComSpec% /d /s /c` command through `WScript.Shell.Run`; that cmd
+   command invokes `wsl.exe` after stripping caret escapes from URI query
+   separators. Inside that command, `wsl.exe -- <cmd>` remains forbidden
+   because it routes its tail through the user's default login shell, which
+   parses `&` query-string separators as background-job operators (zsh emits
+   `parse error near '&'`). `--exec` skips the shell and invokes the binary
+   directly. PATH is empty under `--exec`, so the registry command uses the
+   absolute WSL filesystem path captured at registration time. The `%1` URI is
+   passed as a WScript argument and then forwarded as the `--uri` argv value,
+   not shell-interpolated.
 
 #### Lessons (so future readers don't repeat them)
 
@@ -345,10 +354,12 @@ machine is:
 - Do not use `wsl.exe -- projmux ...` in the registry handler.
   Re-introducing the login-shell hop will surface as `parse error near
   '&'` from the user's shell at click time.
-- The `@projmux_uri_protocol_registered_v2` marker exists because the
-  v1 marker came before the `--exec` fix. Re-registration is idempotent
-  so upgrades from v1 transparently install the new handler — the old
-  marker key just goes orphaned.
+- The `@projmux_uri_protocol_registered_v6` marker exists because v5 invoked
+  `wsl.exe` directly from WScript with quoted fixed arguments, which avoided
+  flash but broke the focus command. Re-registration is idempotent so upgrades
+  from v5 transparently install the new handler. Once v6 registration
+  succeeds, projmux removes the legacy URI marker keys from v1 through v5 so
+  old handler generations do not linger in tmux state.
 
 Multi-distro dispatch (one handler per distro, or a distro-selector
 arg) is a known tier-2 follow-up — current registration captures the

package/docs/notify-queue.md

@@ -94,11 +94,14 @@ preserves the stable JSON array used by scripts.
 
 `--ui=sidebar` opens the notify queue as an interactive right-side list when
 run inside the tmux popup surface. Enter focuses the selected target pane and
-acks the row after focus succeeds. `x` acks the selected row. `Ctrl-X` clears
-all rows via `notify ack --all`. Rows are intentionally compact: the visible
-label keeps notification text first, then age, project, window, and pane
-metadata; hidden queue ids remain action values but the sidebar has no search
-input and intentionally does not expose a separate metadata detail view.
+acks the row after focus succeeds. `x` acks the selected row in place, keeps
+the sidebar open, and refreshes the list from the queue while preserving the
+selection position where possible; acking the last remaining row renders the
+empty state until the popup is closed. `Ctrl-X` clears all rows via `notify ack
+--all` and exits. Rows are intentionally compact: the visible label keeps
+notification text first, then age, project, window, and pane metadata; hidden
+queue ids remain action values but the sidebar has no search input and
+intentionally does not expose a separate metadata detail view.
 
 `--live` adds a non-mutating explanation view that reads
 `tmux list-panes -a` and compares the queue with live reply-state panes. It
@@ -213,13 +216,24 @@ client selection policy.
 
 Outcomes:
 
-- **Focus succeeded** — ack the entry. Focus is the single consume path for
-  routed notification clicks.
+- **Focus succeeded** — ack the selected entry, even when it is critical.
+  Then bulk-ack older same-session/same-pane non-critical AI rows. Bulk cleanup
+  never consumes `critical`, permission-request, stop-failure, `external`,
+  `git`, or `k8s` rows; those remain pending unless the user selected that row
+  directly.
 - **Focus exited 2 (target unresolved)** — ack the entry and toast
   `notify target gone; cleared`.
 - **Other failure** — keep the entry, toast `focus failed: <reason>`
   so the user can retry without losing the row.
 
+The same consume policy is shared by notify-sidebar Enter and OS
+click-to-focus Toast callbacks after a real tmux focus dispatch succeeds.
+Pane focus hooks and attention clear paths remain live-attention-only and do
+not ack the notify queue. Non-critical AI completion producers also compact
+older same-pane non-critical AI rows after replacing/pushing their latest row,
+so reply-ready/stop/bell-style completion rows stay latest-state centered
+without changing the queue schema or TTL contract.
+
 The handler never returns a non-zero error to tmux's `run-shell`; every
 failure becomes a `display-message` toast so a transient miss does not
 trigger a tmux error popup.

package/docs/readme-hero-gif-recording.md

@@ -0,0 +1,97 @@
+# README Hero GIF Recording
+
+This recipe records the README hero GIF:
+
+- `docs/assets/projmux-ai-attention.gif`
+
+The maintained recorder is kept in the local dotfiles checkout at:
+
+```sh
+/home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
+```
+
+## Prerequisites
+
+Install or verify these local tools before recording:
+
+- `python3`
+- `git`
+- `tmux`
+- `ffmpeg` and `ffprobe`
+- `Xvfb`
+- `openbox`
+- `ghostty`
+- `xdotool`
+- `xwininfo`
+- `script` from util-linux
+- authenticated `codex`
+
+Build the local projmux binary first:
+
+```sh
+make build
+```
+
+The script expects `.bin/projmux` by default. Override paths only when needed:
+
+```sh
+PROJMUX_RECORD_REPO=/path/to/projmux \
+PROJMUX_RECORD_BIN=/path/to/projmux \
+PROJMUX_RECORD_DISPLAY=117 \
+PROJMUX_RECORD_SCREEN=2560x1440x24 \
+PROJMUX_RECORD_KEEP_TMP=1 \
+python3 /home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
+```
+
+For the normal checkout, run:
+
+```sh
+python3 /home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
+```
+
+## Scenario Contract
+
+The recording uses a private demo home, XDG config/state dirs, demo git
+projects, and an isolated `CODEX_HOME`. It copies the local Codex auth/config
+into that isolated home, trusts the demo projects/hooks, and seeds usage cache
+data so the tmux status line shows the Codex HUD during the capture.
+
+The scenario records the AI attention flow:
+
+1. Start in `mobile-client` with no pending notification.
+2. Open the AI picker and launch a real Codex pane.
+3. Ask Codex to do a short task.
+4. Use the projmux sessionizer sidebar to move to `atlas-api`.
+5. Keep working in zsh while Codex finishes in the previous project.
+6. When the Codex completion notification exists, open the notification sidebar.
+7. Select the notification and return focus to the original Codex pane.
+
+## Visual Guardrails
+
+- Keep the native picker UI native. The script runs picker commands through
+  `script(1)` with a fixed PTY size so fzf/terminal UI rendering is captured
+  instead of degraded line-mode output.
+- Keep the terminal in zsh with the demo prompt so the project and git branch
+  are visible.
+- Keep the Codex usage HUD visible in the tmux status line.
+- Use the sessionizer sidebar for project movement in 4a.
+- Capture the Ghostty X11 window geometry with `xwininfo` and feed that exact
+  rectangle to ffmpeg. This prevents the GIF from drifting away from `(0, 0)`.
+
+## Verification
+
+After recording, inspect the resulting streams:
+
+```sh
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,nb_frames,duration \
+  -of default=noprint_wrappers=1 \
+  docs/assets/projmux-ai-attention.gif
+```
+
+Expected final shape is roughly 1110px wide and about 16-18 seconds, with the
+native picker, zsh prompt, Codex pane, notification sidebar, and usage HUD
+visible in the relevant frames.
+
+Set `PROJMUX_RECORD_KEEP_TMP=1` when you need to inspect intermediate MP4s,
+Ghostty logs, or palette files under `/tmp/projmux-readme-record-*`.

package/docs/session-restore.md

@@ -38,6 +38,17 @@ unknown sources are low or none. The old statusbar Session State shortcut has
 been removed; use `Projects > Sessions > State` or the `projmux session-state`
 CLI for inspection/actions.
 
+Agent restore direct-starts supported resume commands when creating fresh tmux
+panes, matching the `projmux ai split` wrapper shape: the wrapper prepends the
+agent binary directory to `PATH`, changes to the saved cwd, sets the terminal
+and tmux pane title from the saved agent topic, then execs `codex resume <id>`
+or `claude --resume <id>`. This avoids typing agent resumes with
+`tmux send-keys`. The restore wrapper is still a non-interactive shell command
+tail, so it does not replay the original pane's interactive shell startup,
+environment, shell functions, aliases, or live process state. Startup recipes
+continue to use their saved `send-keys` command replay, and shell recipes only
+restore cwd/layout.
+
 Settings > Session State is global settings only: global auto-save, auto-save
 interval, and storage/retention policy. It does not show the current
 snapshot tree. Delete for current-session snapshots and destructive restore

package/docs/settings-ia.md

@@ -18,16 +18,25 @@ view-first layout:
 - `Settings > Keybindings` is the single entry point for keybinding work. The
   page is split into four chips: `Bindings`, `Diagnostic`, `Probe`, and `Init`.
 - `Settings > Notifications` owns notification delivery IA. Desktop notification
-  mode, delivery source diagnostics, in-app queue status, and
+  mode, AI desktop notification dedupe duration, delivery source diagnostics,
+  AI hook quiet policy, in-app queue status, and
   `PROJMUX_NOTIFY_HOOK` visibility live together without mixing mutation
   boundaries.
 - `Settings > Notifications > Desktop notifications` owns the desktop
   notification mode. The detail choices are `none`, `notify`, and `raise`.
+- `Settings > Notifications > AI notification dedupe` owns the duplicate
+  desktop AI notification collapse window. It stores integer seconds and shows
+  the effective source; `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` remains the top
+  override. The tmux bell fallback keeps its fixed 5 second window.
 - `Settings > Notifications > Delivery sources` shows Codex hooks, Claude, and
   tmux producer diagnostics plus copyable install/remove/dry-run commands.
   Settings copies command text only; it does not install or remove external
   notify wiring. The legacy Codex notify source is intentionally omitted from
   Settings.
+- `Settings > Notifications > Hook quiet policy` shows Codex/Claude hook
+  runtime action values and writes only
+  `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
+  edit catalog `install` values or run agent install/remove commands.
 - `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
   visible Labs row. The hidden compatibility action still redirects to the
   unified Keybindings page.
@@ -42,9 +51,9 @@ view-first layout:
   such as `Set startup command...`, `Clear startup command`, kube edits, and env
   add/remove rows live inside those details.
 - `Settings > Appearance` is view-first. The root opens `Path icon`, `Git icon`,
-  and `Notify icon` details. Each detail shows the current mode and off/symbol/
-  emoji rendered previews first, and its `Change` page contains only the
-  off/symbol/emoji mutation choices.
+  and `Notify icon` details. Each detail shows the current mode plus
+  immediately selectable off/symbol/emoji preview rows. There is no separate
+  `Change` page for icon decoration.
 
 Hooks remain the reference pattern for this IA:
 

package/docs/statusbar.md

@@ -75,6 +75,13 @@ The notify segment renders the newest queued item as a single notification
 block: project, state (`NEED`/`INFO`/`WARN`/`CRIT`), optional agent, text,
 age, and `+N` for older pending entries. Window/pane ids are not shown in the
 compact status segment.
+When the notify block is wider than its cell budget, clipping shrinks the body
+text first and appends an ellipsis while preserving project, state, agent, age,
+and count metadata. If the segment is still too wide, the age is dropped next
+while badges and the `+N` count stay visible when possible. Very narrow widths
+fall back to the severity-colored dot plus clipped text and count; the final
+hard-truncate path still closes with `#[default]` so later status segments do
+not inherit notification styling.
 `usage` opens a native-framed detail HUD for the compact usage bar. It reads
 the cached usage state in-process, keeps the existing `projmux usage` CLI
 output shape unchanged for external consumers, aligns model/window rows with
@@ -96,7 +103,10 @@ needed, and colors that sync line amber once it is more than 60 seconds old.
 The notification HUD detail surface (`Alt-2` / `User2`) opens the right-side
 notification popup with newest-first rows and an amber title. When notification
 icon decoration is `symbol` or `emoji`, the bell appears before the title text.
-Selecting a row still focuses and acknowledges that notification.
+Selecting a row still focuses and acknowledges that notification. Pressing `x`
+on a row acknowledges it without focusing, keeps the popup open, and refreshes
+the remaining rows from the queue while preserving the selection position where
+possible.
 
 Empty `#{mouse_status_range}` (a click on whitespace) falls through to
 `select-window -t @<mouse_window>` when `--mouse-window` is non-empty,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -24,10 +24,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.6.1",
-    "@projmux/darwin-x64": "0.6.1",
-    "@projmux/linux-arm64": "0.6.1",
-    "@projmux/linux-x64": "0.6.1"
+    "@projmux/darwin-arm64": "0.6.2",
+    "@projmux/darwin-x64": "0.6.2",
+    "@projmux/linux-arm64": "0.6.2",
+    "@projmux/linux-x64": "0.6.2"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",