projmux 0.4.4 → 0.4.6

package/docs/notify-queue.md

@@ -0,0 +1,199 @@
+# Notify queue
+
+`projmux` keeps a persistent JSON queue of pending AI notifications.
+`attention` is live tmux pane state; `notify` is the user's pending
+notification source of truth. The queue is derived from live state and user
+pushes, but an entry remains pending until explicit ack. Each entry can route
+the status-bar notify segment or notify sidebar to the originating tmux pane
+via `projmux focus`, and feeds the HUD pill rendered by
+`projmux status notify`.
+
+## File layout
+
+```
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json.lock
+```
+
+The lock file is acquired via `O_CREATE|O_EXCL` with bounded retry
+(default ~200 attempts, 2ms–50ms jittered backoff) and a 30s
+stale-after window so a crashed writer never permanently wedges the
+queue.
+
+The queue file is a pretty-printed JSON array of `Notification`
+objects, sorted newest-first on read. `expires_at` is freshness metadata;
+expired entries are not filtered or deleted by `list`.
+
+## Data model
+
+`internal/core/notify`:
+
+```go
+type Notification struct {
+    ID        string    // stable key for dedupe / ack
+    Text      string    // capped at 80 runes
+    Severity  string    // info | warn | critical
+    Source    string    // ai | k8s | git | external
+    CreatedAt time.Time
+    ExpiresAt time.Time
+    Target            // session, window, pane, socket
+}
+
+type Target struct {
+    Socket  string  // tmux -L socket path; empty = default
+    Session string
+    Window  string  // optional; "" means session-only
+    Pane    string  // optional; "" means window-level
+}
+```
+
+Defaults: `DefaultTTL = 600s`, `MaxTextLength = 80`. TTL is retained as a
+freshness/display field, not a removal condition. `Severity` and
+`Source` are validated against the constants above; an invalid value
+returns `ErrInvalidSeverity` / `ErrInvalidSource` which the CLI maps to
+exit code 2.
+
+## CLI surface
+
+### push
+
+```
+projmux notify push --text <s> --target <SESSION[:WINDOW[.PANE]]>
+                    [--socket <s>] [--severity info|warn|critical]
+                    [--source ai|k8s|git|external]
+                    [--ttl <seconds>] [--id <s>] [--json]
+```
+
+Appends one entry. With `--id` an existing entry is overwritten in
+place (text + timestamp refresh), enabling idempotent producers like
+the AI reply-ready transition. `--ttl` accepts a positive integer
+number of seconds. `--json` prints `{id, queued}` for scripting.
+
+### list
+
+```
+projmux notify list [--live] [--json] [--limit N] [--ui table|sidebar]
+                    [--severity ...] [--source ...]
+```
+
+Newest-first pending queue entries. Default output is the tab-aligned
+table `ID AGE SEV SRC TARGET TEXT`. `--severity` / `--source` are
+repeatable filters. Without `--live`, this command reads only the queue and
+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. `a` acks the selected row. `Ctrl-A` 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; id/source/severity/target remain searchable.
+
+`--live` adds a non-mutating explanation view that reads
+`tmux list-panes -a` and compares the queue with live reply-state panes. It
+does not push, ack, or otherwise repair anything. Human output keeps the
+queue table and adds a `STATE TARGET ID EXPLANATION TEXT` section; JSON
+output becomes `{queue, live, rows, errors}`. Typical states:
+
+- `live-manual-reply` — a live reply/green badge exists, but no queue entry
+  is expected because the pane has no AI agent metadata.
+- `live-ai-reply-queued` — a live AI reply pane has the matching actionable
+  queue entry.
+- `live-ai-reply-missing-queue` — a live AI reply pane lacks the derived
+  queue entry; run `projmux notify reconcile` to back-fill it.
+- `queue-stale` — an `ai:` queue entry exists, but the live pane no longer
+  matches reply+agent state; it remains pending until explicit ack.
+- `queue-only` — a non-AI/external queue entry is pending and has no live AI
+  reply-pane requirement.
+
+To inspect live pane attention without queue context, use
+`projmux attention list`.
+
+### ack
+
+```
+projmux notify ack <id>
+projmux notify ack --all
+```
+
+Removes one entry by id, or flushes the queue. `--all` returns the
+removed count.
+
+### reconcile
+
+```
+projmux notify reconcile [--json]
+```
+
+Walks `tmux list-panes -a -F` with the producer-key format (session,
+window id, pane id, attention state, AI state, agent, topic, socket
+path), then:
+
+- pushes/refreshes one `ai:<session>:<pane>` entry for every pane
+  whose attention state is `reply` AND whose agent option is non-empty;
+- reports every existing queue entry whose id starts with `ai:` and whose
+  pane no longer matches that condition as stale, without acking it.
+
+Soft-fails when tmux is not running (returns a populated `errors`
+field rather than a non-zero exit) so the post-install hook does not
+break. Run this as the recovery path when the on-disk queue has drifted
+from live pane state.
+
+Output: `reconcile: pushed N, acked M, kept K, stale S`.
+
+Ack behavior is intentionally queue-local: only `ack` removes explicit ids or
+flushes the queue. TTL is freshness metadata, and `reconcile` only repairs
+derived `ai:` entries. Manual attention badges without agent metadata remain
+live attention only.
+
+## Producer (AI reply-ready)
+
+`internal/app/notify_producer.go`. The attention state machine calls
+`PushReplyReady` when a pane flips to `reply`. The producer reads
+`@projmux_ai_pane_agent`, `@projmux_ai_pane_topic`, `#S`,
+`#{window_id}`, `#{pane_id}`, `#{socket_path}` off the pane and writes
+an entry with:
+
+- id: `ai:<session>:<pane>`
+- text: `<agent>: <topic>` (or `<agent>: ready` when no topic is set)
+- severity: `info`, source: `ai`, freshness TTL: 10 minutes
+
+When the pane leaves the reply state (manual `attention clear`,
+`status set idle`, or a window close), `AckReplyReady` intentionally does not
+remove the entry. The user consumes it through explicit ack. Store errors are
+swallowed so the live tmux UI never blocks on disk IO.
+
+Manual `projmux attention toggle` on a pane without an agent option
+does NOT push — the queue is intentionally AI-driven; reconcile honours
+the same contract.
+
+## Consumer (status-bar click)
+
+`internal/app/statusbar.go::handleNotify`. A click on the notify range
+or the `prefix s n` chord reads the newest queue entry and dispatches:
+
+```
+projmux focus --target <target> --source status-bar --kind segment-click [--socket <s>]
+```
+
+Outcomes:
+
+- **Focus succeeded** — ack the entry. Focus is the single consume path for
+  routed notification clicks.
+- **Focus exited 2 (target unresolved)** — keep the entry pending and toast
+  `notify target gone; ack to clear`.
+- **Other failure** — keep the entry, toast `focus failed: <reason>`
+  so the user can retry without losing the row.
+
+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.
+
+## Render (status segment)
+
+`projmux status notify` is the HUD-style renderer wired to the tmux
+status interval. See [statusbar.md](statusbar.md) for the layout and
+degradation tiers. It shows the newest pending item as a single notification
+block with project, state, optional agent, text, age, and an extra-count
+marker. Window/pane ids remain routable metadata but are not displayed in the
+compact HUD. The renderer is silent on every failure mode (no store, list
+error, empty queue) so the status line never carries a stack trace.

package/docs/npm-distribution.md

@@ -0,0 +1,86 @@
+# npm Distribution
+
+`projmux` remains a Go CLI. npm is a distribution channel that installs a
+small Node.js shim plus one platform-specific Go binary package.
+
+The public npm package `projmux` is the root shim package. Release builds use
+this package layout:
+
+| package | contents |
+| --- | --- |
+| `projmux` | `npm/projmux.js` shim and optional dependencies |
+| `@projmux/linux-x64` | `linux/amd64` `bin/projmux` |
+| `@projmux/linux-arm64` | `linux/arm64` `bin/projmux` |
+| `@projmux/darwin-x64` | `darwin/amd64` `bin/projmux` |
+| `@projmux/darwin-arm64` | `darwin/arm64` `bin/projmux` |
+
+The shim sets `PROJMUX_INSTALLER=npm` before executing the real binary so
+`projmux update status` and the Settings About screen can present
+npm-specific guidance. npm is only an update/install source label here; the
+keybinding flow remains `projmux shell` first, then `projmux setup` and
+`projmux init` only for terminals that swallow shortcuts.
+
+## Local Packaging
+
+Build and dry-run pack all npm packages:
+
+```bash
+make npm-pack
+```
+
+or:
+
+```bash
+scripts/package-npm.sh --version 0.4.0 --out /tmp/projmux-npm --pack
+```
+
+The script stages package directories under `dist/npm` by default. It builds
+the Go binary for each supported platform, copies package metadata and docs,
+updates package versions in the staged copies, then runs `npm pack --dry-run`
+when `--pack` is set.
+
+## Publish Order
+
+The platform packages must be published before the root package:
+
+```text
+@projmux/linux-x64
+@projmux/linux-arm64
+@projmux/darwin-x64
+@projmux/darwin-arm64
+projmux
+```
+
+Publishing the scoped platform packages requires control of the `@projmux`
+npm scope. Configure npm Trusted Publishing for every package before merging a
+release PR:
+
+| npm package | GitHub organization/user | repository | workflow filename |
+| --- | --- | --- | --- |
+| `@projmux/linux-x64` | `crevissepartners` | `projmux` | `release.yml` |
+| `@projmux/linux-arm64` | `crevissepartners` | `projmux` | `release.yml` |
+| `@projmux/darwin-x64` | `crevissepartners` | `projmux` | `release.yml` |
+| `@projmux/darwin-arm64` | `crevissepartners` | `projmux` | `release.yml` |
+| `projmux` | `crevissepartners` | `projmux` | `release.yml` |
+
+Leave the npm trusted publisher environment field empty unless the workflow is
+later moved behind a GitHub deployment environment.
+
+Tag releases publish npm packages from GitHub Actions after release archives
+are uploaded. The workflow runs:
+
+```bash
+scripts/package-npm.sh --version "${GITHUB_REF_NAME#v}" --out dist/npm
+```
+
+then publishes each staged package with `npm publish --access public`.
+The npm publish job uses GitHub Actions OIDC (`id-token: write`) instead of a
+long-lived `NPM_TOKEN` secret. PR CI runs `make npm-pack` so package staging and
+dry-run packing fail before release.
+
+## Non-Goals
+
+The npm installer must not install system dependencies, edit shell startup
+files, or mutate tmux config. Those actions stay behind explicit
+`projmux doctor`, `projmux init`, Settings About update actions, or future
+opt-in install commands.

package/docs/picker-ui-plan.md

@@ -0,0 +1,111 @@
+# Picker UI Plan
+
+## Goal
+
+The project switcher needs a richer picker surface than a single-line fzf row.
+The target interaction is a card-like list where each item can show a title plus
+small contextual lines such as session state, window/pane summary, branch, or
+path. Search should stay focused on stable identity text, especially the project
+or session title, instead of matching every contextual preview line.
+
+## Current Contract
+
+The picker contract is split in two layers:
+
+- `internal/ui/picker` owns backend-neutral items, actions, preview metadata,
+  backend selection, title-focused filtering, and the opt-in native runner.
+- `internal/ui/fzf` adapts that model into the historical fzf command line.
+
+The default fzf backend still sends one logical row per item:
+
+```text
+<visible label>\t<selection value>
+```
+
+fzf is configured with:
+
+- `--delimiter "\t"`
+- `--with-nth 1`
+- `--exit-0`
+- optional `--preview` and `--preview-window`
+
+The app depends on fzf returning the selected row and then extracts the hidden
+value after the first tab. This contract is simple and stable, but it limits each
+row to one visible line.
+
+## fzf Capability Check
+
+The installed fzf version supports multi-line items with `--read0`. That means a
+single item can contain newline characters when input records are NUL-delimited.
+This can render card-like rows.
+
+The simple fzf option path is not enough for the desired search behavior:
+
+- `--read0` can display multi-line items.
+- `--nth` can restrict search to selected fields.
+- `--with-nth` can transform the displayed fields.
+- In practice, once `--with-nth` is used to show a card field, fzf searches the
+  transformed visible text. Context lines become searchable.
+
+So fzf can support "multi-line cards", but not "multi-line cards with title-only
+search" through a small option-only extension while preserving the current
+selection contract.
+
+## Viable Paths
+
+### 1. fzf card approximation
+
+Use `--read0` and NUL-delimited multi-line entries. This is the smallest change,
+but contextual card text will participate in search unless the visible card is
+kept title-only. This does not meet the intended search model.
+
+This path is acceptable only as a temporary visual experiment.
+
+### 2. fzf custom filtering
+
+Run fzf in a more controlled mode where query changes reload a filtered list
+from `projmux`, and `projmux` performs title-focused matching. This keeps fzf as
+the renderer but moves filtering into the app.
+
+Tradeoffs:
+
+- More shell quoting and reload complexity.
+- More edge cases around selection identity and tracking.
+- Still constrained by fzf's list layout and event model.
+
+This is viable, but it is a bridge rather than a clean long-term model.
+
+### 3. Native picker TUI
+
+Introduce a picker abstraction and implement a native terminal UI for card rows,
+title-focused search, stable selection identity, and app-owned key handling. fzf
+remains the default backend until parity is reached.
+
+This best matches the desired product direction:
+
+- card rows are first-class data, not encoded fzf strings
+- search fields are explicit
+- preview/context fields can be visible but non-searchable
+- future key behavior can be tested without relying on fzf internals
+
+## Implemented Direction
+
+Do not extend the current fzf row format again as the main implementation. The
+previous hidden-field attempt showed that small fzf encoding changes can break
+selection and navigation in subtle ways.
+
+Current implementation:
+
+- Picker-domain model exists as `picker.Item` with `Title`, `Value`,
+  `SearchText`, `MetaLines`, `Badges`, and `PreviewTarget`.
+- `picker.Options` carries backend-neutral actions, preview metadata, prompt,
+  footer, initial query, and multiline intent.
+- fzf remains the default backend and renders the same popup/sidebar surfaces.
+- `PROJMUX_PICKER_BACKEND=native` opts into the native runner. It supports
+  multiline item rendering, title-focused search via `SearchText`, numeric
+  selection, and shared close actions.
+- Switcher popup/sidebar still use the fzf backend for full preview and key
+  action parity. Native preview panes, raw-key navigation, and sidebar focus
+  tracking remain follow-up work.
+
+fzf can stay as the stable fallback while the native picker reaches parity.

package/docs/pr-guideline.md

@@ -0,0 +1,106 @@
+# PR Guideline
+
+Audience: every contributor — humans and agents alike. Agents working in this
+repo (`claude` / `codex` panes, the team-lead session, etc.) MUST follow these
+rules; the conventions here are what `release-please` parses for the next
+release notes, so a sloppy PR title silently breaks the changelog.
+
+For the surrounding workflow (worktree, validation gates, post-merge install)
+see [AGENTS.md](../AGENTS.md). This document covers only the PR itself.
+
+## PR title — Conventional Commits
+
+Default merge method is **squash**, so the PR title becomes the only commit
+subject that lands on `main`. Format:
+
+```
+<type>(<optional scope>): <imperative summary>
+```
+
+Examples:
+
+```
+feat(ai): add codex split picker keybinding
+fix(ai): prepend agent bin dir to PATH so node-managed CLIs find node
+docs(readme): drop Releases and Configuration sections
+chore: bump release-please manifest to 0.3.0
+refactor(picker): collapse duplicate fzf bootstrap code
+```
+
+Rules:
+
+- Subject is in the imperative ("add", "fix", "drop"), no trailing period.
+- Keep the title under ~70 characters when possible. Long detail goes in the
+  body.
+- The scope is optional but recommended for non-trivial diffs (`ai`, `picker`,
+  `tmux`, `readme`, `ci`, etc.).
+- A `!` after the type or scope marks a breaking change:
+  `feat(ai)!: rename PROJMUX_NOTIFY_HOOK to PROJMUX_NOTIFY_BIN`.
+- Or include a `BREAKING CHANGE: <description>` footer in the body. Either form
+  bumps the major version on the next release-please run.
+
+### Allowed types
+
+| type | use for | release impact |
+| --- | --- | --- |
+| `feat` | user-visible new behavior or capability | minor bump |
+| `fix` | bug fix that ships to users | patch bump |
+| `perf` | measurable runtime/memory improvement | patch bump |
+| `refactor` | code restructure with no user-visible change | none |
+| `docs` | docs-only change | none |
+| `test` | adding or restructuring tests | none |
+| `build` | build system, Makefile, dependencies | none |
+| `ci` | CI workflow / GitHub Actions | none |
+| `chore` | release plumbing, tooling, repo housekeeping | none |
+| `style` | formatting only, no logic change | none |
+
+If the change includes both a feat and a fix, split it into two PRs. release-please
+classifies the whole PR by its title type, not by content.
+
+## PR body
+
+Use this template:
+
+```markdown
+## Summary
+- 1–3 bullets describing what changed and why.
+
+## Test plan
+- [ ] make fmt-check
+- [ ] make test
+- [ ] manual verification step (if relevant)
+```
+
+Notes:
+
+- **Why** matters more than **what**. Diff already shows the what.
+- Reference issues with `Closes #<n>` so they auto-close on merge.
+- Mention follow-ups explicitly when scope was deliberately deferred.
+
+## Branch protection in effect
+
+`main` is governed by ruleset `main-protect`:
+
+- Direct push to `main` is blocked. Even repository admin must use a PR.
+- Required status check: the CI `Test` job. The PR cannot merge until it is
+  green.
+- Admin bypass is `pull_request` mode — admin can self-merge without
+  approvals, but the PR itself is mandatory.
+- Linear history is enforced. The merge methods exposed are
+  `merge` / `squash` / `rebase`; **default is squash** and that is what the
+  team-lead session uses unless the change explicitly needs preserved history.
+- Force pushes and branch deletions on `main` are blocked.
+
+`gh pr merge <num> --squash --delete-branch` is the canonical merge command.
+Use `--auto` if you want the merge queued automatically once CI passes.
+
+## Release-please coupling
+
+Every PR title that lands on `main` is parsed by `release-please-action`.
+A `feat:` or `fix:` PR adds an entry to the next release notes; `chore:` /
+`docs:` / `refactor:` etc. do not. To force a release of accumulated non-user
+changes, open a `chore` PR titled `chore: release X.Y.Z` (or wait for any
+real change). The `internal/version/version.go` constant carries the
+`x-release-please-version` marker so release-please bumps it automatically.
+
+Do not hand-author CHANGELOG.md or version bumps. release-please owns both.

package/docs/repo-layout.md

@@ -0,0 +1,50 @@
+# Repository Layout
+
+## Planned layout
+
+```text
+projmux/
+  cmd/
+    projmux/
+  internal/
+    app/
+    config/
+    core/
+      candidates/
+      pins/
+      preview/
+      sessions/
+    integrations/
+      filesystem/
+      git/
+      kube/
+      tmux/
+    state/
+    ui/
+      fzf/
+      render/
+    version/
+  docs/
+  scripts/
+  test/
+    integration/
+    e2e/
+```
+
+## Notes
+
+- `cmd/projmux` contains only CLI wiring.
+- `internal/core` contains product behavior that should be testable without tmux.
+- `internal/integrations/tmux` should be the only place that knows tmux command strings and output formats.
+- `internal/ui/fzf` may depend on shelling out to `fzf`, but should call typed core services.
+- `scripts/` is for development tooling only, not product logic.
+
+## Early implementation order
+
+1. `internal/core/sessions`
+2. `internal/core/candidates`
+3. `internal/core/pins`
+4. `internal/state`
+5. `internal/integrations/tmux`
+6. `internal/ui/fzf`
+7. CLI command wiring

package/docs/roadmap.md

@@ -0,0 +1,95 @@
+# Roadmap
+
+## Done (0.4.x)
+
+The 0.4 line filled in the operational surface around the session-management
+core that 0.3 had landed.
+
+### Setup and install
+
+- `projmux setup` — TTY raw-mode probe that reports which projmux key
+  sequences (`Alt-1..5`, `Ctrl-N`, `Ctrl-Shift-{R,L,M}`, `Ctrl-M`,
+  `Alt-Shift-{Left,Right}`) reach the process and which the terminal
+  swallows.
+- `projmux init [terminal]` — auto-merges projmux's CSI-u + chord
+  bindings into a terminal config. Adapters: Ghostty (with the
+  `config` / `config.ghostty` candidate split and symlink guard) and
+  Windows Terminal (WSL + native).
+
+### Diagnostics
+
+- `projmux doctor` — runtime dependency report. Enforces minimum tmux
+  3.4 and fzf 0.65.0 (`stale` status when present but below the floor).
+
+### Focus
+
+- `projmux focus` — unified switch-client dispatch. Resolves a target
+  session against the live tmux inventory, redirects an existing client
+  if one is attached, otherwise emits a desktop notification. Used by
+  the status-bar notify click and by the AI reply-ready handler.
+
+### Notify queue
+
+- `projmux notify push|list|ack` — persistent JSON-backed queue at
+  `<state>/projmux/notify.json` with TTL, severity, source, and target
+  metadata.
+- `projmux notify reconcile` — back-fills the queue from live pane
+  state by walking `tmux list-panes -a`.
+- Producer wired to the attention state machine: a pane transitioning
+  to `reply` with an AI agent option set pushes an `ai:<session>:<pane>`
+  entry; the matching `clear` acks it.
+
+### Usage tracking
+
+- `projmux usage` (and `status usage`) — authoritative 5h + weekly
+  utilisation for both Claude (OAuth `api/oauth/usage` endpoint with
+  401 token refresh) and Codex (latest rollout `rate_limits` JSONL).
+- Per-adapter throttle (Claude `5m`, default `30s`), 429 backoff
+  (`30m`–`60m` exponential), `--force` to bypass both. Snapshots
+  preserved on failure so a 429 does not erase prior rows.
+
+### Statusbar and HUD
+
+- Two-line clickable status bar: row 0 is the existing
+  session/window/path/git/kube row, row 1 splits notify (left) and
+  usage (right).
+- `projmux statusbar click` — single dispatcher for both mouse clicks
+  and the `prefix s {u,n,g,k,p,s}` keyboard chord. Window-list clicks
+  on tabs short-circuit to native `select-window`.
+- `pwd` status click copies the current pane path into the tmux paste
+  buffer and shows a compact path popup instead of a transient
+  warning-coloured toast.
+- HUD-style notify segment with severity+agent badge, midpoint dot
+  separators, and an age field.
+- HUD-style usage segment with bars, last-sync age indicator (Claude),
+  and graceful degradation through six tiers as `--max-width` shrinks.
+
+## Next (0.5+)
+
+Carried forward from earlier milestones — items still outstanding when
+v0.4 shipped.
+
+### Picker UI
+
+- Picker-domain model separate from fzf row encoding (kept fzf as the
+  stable fallback backend). Done in the 0.5 picker contract slice.
+- Opt-in native picker backend for multi-line card rows and
+  title-focused search. Done in the 0.5 picker contract slice via
+  `PROJMUX_PICKER_BACKEND=native`.
+- Port switcher popup/sidebar surfaces after parity tests cover
+  selection, preview, and key actions.
+
+### Picker dismissal
+
+- Picker-agnostic popup close/toggle handling so AI picker dismissal
+  does not depend on fzf-specific key bindings. Done in the 0.5 picker
+  contract slice; fzf maps close actions to `abort`, and the native runner
+  consumes the same close action keys.
+
+### Docker install and E2E harness
+
+- Initial Docker-backed Linux smoke suites are available through
+  `make test-integration`, `make test-install-smoke`, and `make test-e2e`.
+  They cover install/runtime substrate checks against real `tmux`; host-only
+  terminal, WSL, macOS, and GUI checks remain separate in
+  [docs/testing.md](testing.md).

package/docs/shell-autostart.md

@@ -0,0 +1,33 @@
+# Shell Auto-Start
+
+If you want every new interactive bash or zsh shell to drop you straight into
+the projmux app, add a guarded hook to `~/.bashrc`, `~/.zshrc`, or the
+equivalent interactive rc file for your shell:
+
+```sh
+if [[ $- == *i* && -z "${TMUX:-}" ]] && command -v projmux >/dev/null 2>&1; then
+  exec projmux shell
+fi
+```
+
+The three guards each prevent a common breakage:
+
+- `$- == *i*` — only fire for interactive shells. Without this you would
+  break `scp`, `ssh host cmd`, `git` over SSH, and any `bash -c '...'` or
+  `zsh -c '...'` invocation.
+- `-z "${TMUX:-}"` — skip when already inside tmux. Without this the hook
+  recurses every time projmux opens a new pane.
+- `command -v projmux >/dev/null 2>&1` — skip on machines where projmux is not
+  installed yet. Without this a fresh login on a new box hangs at a missing
+  binary.
+
+To bypass the hook for one shell, set `TMUX` before launching:
+
+```sh
+TMUX=1 bash
+TMUX=1 zsh
+```
+
+This is **opt-in** behavior. projmux does not assume you want every shell to
+auto-start the app; the snippet above is here only as a known-safe starting
+point for users who do.