@projmux/darwin-x64 0.0.0-reserved

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crevisse Partners
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# projmux
+
+Project-aware tmux workspace management for people who live in terminals.
+
+`projmux` turns project directories into durable tmux workspaces with previews,
+sidebar navigation, generated keybindings, status metadata, and AI-pane
+attention signals. It can run as its own tmux app (`projmux shell`) or install
+the same behavior into your existing tmux server.
+
+[한국어 README](README-ko.md)
+
+## Why projmux
+
+Most tmux project switchers stop at "pick a directory and attach a session".
+`projmux` treats that as the foundation, then adds the app-level pieces needed
+for a daily terminal workspace:
+
+- **Project identity stays stable.** Directories, pins, live sessions, preview
+  selection, and lifecycle commands all use the same normalized session model.
+- **The UI shows context before you switch.** Popup and sidebar pickers preview
+  sessions, windows, panes, git branch, Kubernetes context, and pane metadata.
+- **The tmux layer is generated, not hand-spliced.** `projmux` writes the tmux
+  config it needs for popup launchers, window/pane rename flows, status
+  segments, pane borders, attention badges, and app mode.
+- **AI panes are first-class.** Codex and Claude panes can be launched,
+  labeled, tracked as thinking or waiting, surfaced in pane/window/session
+  badges, and announced through desktop notifications.
+- **You can choose isolation or integration.** Use `projmux shell` as a
+  self-contained tmux app, or install the generated snippet into your normal
+  tmux server.
+
+## What's new in 0.4
+
+- **`projmux setup` / `projmux init`** — diagnose terminal key delivery,
+  then auto-merge the right CSI-u bindings into Ghostty or Windows
+  Terminal configs.
+- **`projmux doctor`** — runtime dependency report with minimum-version
+  enforcement (tmux 3.4, fzf 0.55).
+- **`projmux focus`** — unified switch-client dispatch shared by the
+  AI reply-ready flow and the status-bar notify click.
+- **Persistent notify queue** — `projmux notify push|list|ack|reconcile`
+  with TTL, severity, source, and target metadata. See
+  [notify-queue.md](docs/notify-queue.md).
+- **Authoritative usage tracking** — `projmux usage` reads Claude's
+  OAuth usage endpoint and Codex's local rollout `rate_limits`. See
+  [usage-tracking.md](docs/usage-tracking.md).
+- **Two-line clickable status bar** — row 0 keeps the native window
+  list (click a tab to switch), row 1 splits a notify HUD pill (left)
+  and a usage HUD bar (right). Both segments degrade gracefully on
+  narrow status budgets. See [statusbar.md](docs/statusbar.md).
+
+## What It Does
+
+- Creates or switches to tmux sessions from project directories.
+- Shows existing sessions with window and pane previews.
+- Provides popup and sidebar navigation surfaces backed by `fzf`.
+- Pins important projects and scans common source roots for new ones.
+- Persists preview selection for fast window and pane cycling.
+- Generates tmux bindings for launchers, rename prompts, pane borders, status
+  segments, and attention hooks.
+- Displays git branch and Kubernetes context/namespace in the status area.
+- Renders a two-line clickable status bar with click-to-switch tabs on
+  row 0 and HUD-style notify (left) and AI usage (right) segments on
+  row 1.
+- Launches AI splits and keeps their agent name, topic, status, and
+  notification state visible in tmux.
+
+## Typical Workflow
+
+```sh
+projmux shell
+```
+
+Open the app once, then use its generated tmux bindings to:
+
+- jump between projects from a sidebar or popup,
+- inspect sessions before attaching,
+- split Codex, Claude, or a plain shell into the current workspace,
+- rename windows and AI pane topics without losing metadata,
+- see which panes need review from badges and desktop notifications.
+
+## Requirements
+
+- [Go 1.24+](https://go.dev/dl/) — required to install or build the binary.
+- [tmux](https://github.com/tmux/tmux/wiki/Installing) **≥ 3.4** — the workspace runtime. Earlier versions miss `display-popup -T` and other features projmux depends on.
+- [fzf](https://github.com/junegunn/fzf#installation) **≥ 0.55** — interactive popup/sidebar pickers. The multiline picker uses `--marker-multi-line`, `--gap-line`, and `--highlight-line`, which landed by 0.55.
+- [zsh](https://zsh.sourceforge.io/) — default shell of the generated app config (`projmux shell`).
+- [git](https://git-scm.com/downloads) — branch/status metadata.
+- `stty` — POSIX terminal control, used by `projmux setup`. Already shipped by every macOS / Linux base system; not applicable on Windows hosts.
+- [kubectl](https://kubernetes.io/docs/tasks/tools/) — optional, only for the Kubernetes status segment.
+
+Desktop notifications: Linux uses `notify-send`; WSL routes Windows toasts via
+`powershell.exe`. Override either with `PROJMUX_NOTIFY_HOOK`.
+
+Run `projmux doctor` any time to verify everything is on `PATH` and that
+tmux/fzf meet the minimum supported versions.
+
+## Install
+
+```sh
+go install github.com/crevissepartners/projmux/cmd/projmux@latest
+```
+
+This drops the binary in `$(go env GOBIN)` (when set) or `$(go env GOPATH)/bin`
+(default `~/go/bin`). Make sure that directory is on your `PATH`:
+
+```sh
+export PATH="$(go env GOPATH)/bin:$PATH"
+```
+
+Verify:
+
+```sh
+projmux version
+```
+
+### Optional: `PROJMUX_PROJDIR`
+
+`PROJMUX_PROJDIR` is the default project root projmux uses for picker and
+discovery. It is optional — when unset, projmux falls back to its built-in
+source-root discovery (`~/source`, `~/work`, `~/projects`, `~/src`, `~/code`,
+`~/source/repos`).
+
+```sh
+export PROJMUX_PROJDIR="$HOME/source/repos"
+```
+
+Add the line to `~/.zshrc` (or your shell's rc file). The resolved value is
+memoized to `~/.config/projmux/projdir` after first use, so later shells keep
+the same root even without the env var.
+
+`PROJMUX_PROJDIR` accepts an OS-native PATH-style multi-value (`:` on
+Linux/macOS, `;` on Windows). The first non-empty entry is the primary
+project root; any additional entries are prepended to the managed-roots
+search list, so they participate in discovery just like
+`PROJMUX_MANAGED_ROOTS`. Only the primary path is memoized to
+`~/.config/projmux/projdir`.
+
+```sh
+# Linux/macOS — primary repo + secondary search root
+export PROJMUX_PROJDIR="$HOME/source/repos:/srv/work/repos"
+```
+
+#### Set the project root at install time
+
+```sh
+PROJMUX_PROJDIR=/your/path go install github.com/crevissepartners/projmux/cmd/projmux@latest
+PROJMUX_PROJDIR=/your/path projmux tmux apply
+```
+
+The first invocation that sees the env var writes
+`~/.config/projmux/projdir`, so later shells without the env var still
+resolve the same root.
+
+### From source
+
+```sh
+git clone https://github.com/crevissepartners/projmux.git
+cd projmux
+make install
+```
+
+`make install` builds, atomically replaces `$(go env GOPATH)/bin/projmux`, and
+runs `projmux tmux apply` so the live `-L projmux` server picks up new bindings
+without a restart. Override the destination with `INSTALL_DIR=/usr/local/bin`.
+
+## Quick Start
+
+Launch the isolated projmux tmux app:
+
+```sh
+projmux shell
+```
+
+projmux owns this tmux server, its generated config, status bar, and popup
+bindings. The left status badge shows the current project name; the right side
+shows path, kube segment, git segment, and clock.
+
+If a key does not fire, run `projmux setup` to see which sequences your
+terminal swallows, then `projmux init [terminal] --apply` (auto-detects when
+no terminal is given) to merge the right CSI-u bindings into your terminal
+config. Dotfiles users on multi-machine setups should pass
+`--allow-symlink` or `--config <path>` to make their intent explicit. Full
+flow and the manual CSI-u fallback are in
+[Terminal Keybindings](docs/keybindings.md).
+
+If anything looks off, `projmux doctor` reports which dependency is
+missing or stale and how to install it. See [Requirements](#requirements)
+for the supported versions.
+
+## Upgrading
+
+`projmux upgrade` reinstalls the binary via `go install`, atomically replaces
+the active file, and reapplies the live tmux config so a running `-L projmux`
+server picks up new bindings without a restart.
+
+```sh
+projmux upgrade                                  # @latest, replace + apply
+projmux upgrade --ref @v0.2.0                    # pin a specific tag
+projmux upgrade --ref @main                      # track a branch
+projmux upgrade --target /usr/local/bin/projmux  # replace another path
+projmux upgrade --no-apply                       # skip 'projmux tmux apply'
+projmux upgrade --dry-run                        # print the steps only
+```
+
+The upgrade reads `PROJMUX_PROJDIR` from the calling shell and memoizes the
+primary (first) path to `~/.config/projmux/projdir`, so the new binary keeps
+the same project root context as the one it replaces.
+
+Pass a new project root inline to atomically switch the binary and the saved
+projdir in one step:
+
+```sh
+PROJMUX_PROJDIR=/new/path projmux upgrade
+
+# Multi-path also works; only the primary entry is persisted to the saved file.
+PROJMUX_PROJDIR="/main/repos:/secondary/repos" projmux upgrade   # Linux/macOS
+# Windows: PROJMUX_PROJDIR="C:\main\repos;C:\secondary\repos"
+```
+
+## Usage
+
+Day-to-day, projmux is driven by tmux keybindings inside `projmux shell` — see
+[Terminal Keybindings](docs/keybindings.md). For the full CLI surface (pins,
+preview state, status helpers, `upgrade`, etc.), run `projmux help` or
+`<command> --help`.
+
+## How It Finds Projects
+
+`projmux switch` combines pinned directories, live tmux sessions, and discovered
+project roots. The default discovery logic favors common source locations such
+as `~/source`, `~/work`, `~/projects`, `~/src`, `~/code`, and `~/source/repos`
+when they exist. `projmux settings` also has `Project Picker > Add Project...`,
+which scans those filesystem roots up to depth 3 so projects outside `~` and
+`~rp` can be added to the picker. Session names are derived from normalized
+directory paths, so a project keeps the same tmux session name across launches.
+
+For permanent search-root customization, the Project Picker section also
+includes:
+
+- `+ Add Workdir...` - append a single directory to the saved workdirs list.
+- `Workdirs` - review and remove saved workdirs. The same picker also surfaces
+  any active `PROJMUX_MANAGED_ROOTS` / `TMUX_SESSIONIZER_ROOTS` env values as
+  read-only rows so you can see why an env list might be overriding the saved
+  file.
+
+`Add Workdir > Type path manually...` gives you a typed entry that skips the
+filesystem scan. Use it for paths you do not want crawled, e.g. WSL mounts
+(`/mnt/c/Users/...`), large NFS mounts, or per-project temp roots.
+
+The saved file lives at `~/.config/projmux/workdirs` (one absolute path per
+line, `#` comments allowed). It is consulted only when the env vars are unset.
+
+## Hooks
+
+projmux runs an optional user script at `~/.config/projmux/hooks/post-create`
+whenever it creates a new tmux session. Use it to inject per-session env via
+`tmux set-environment` (e.g. picking a `GH_TOKEN` based on the project path).
+Missing or non-executable hooks are skipped silently; failures never block
+session creation. See [Hooks](docs/hooks.md) for the env contract, examples,
+and troubleshooting.
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `PROJMUX_PROJDIR` | Default project root for the current shell. Accepts an OS-native PATH-style multi-value: the first entry is the primary repo root (memoized to `~/.config/projmux/projdir`), and any additional entries are prepended to the managed-roots search list. |
+| `PROJMUX_MANAGED_ROOTS` | Colon-separated list of search roots. Overrides the saved/default list. |
+| `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in sender. |
+| `PROJMUX_USAGE_STATE_DIR` | Override directory for the AI-usage snapshot cache. Defaults to `<state>/projmux/usage`. Point this at a synced location (Dropbox, iCloud Drive, etc) to share authoritative usage between machines. |
+| `PROJMUX_USAGE_DEBUG` | When non-empty, surfaces adapter errors from `projmux status usage` to stderr instead of swallowing them. |
+| `PROJMUX_USAGE_LIMITS_PATH` | Deprecated. Limits now come from the upstream APIs (Anthropic OAuth usage endpoint, Codex `rate_limits`); this variable is read but ignored. |
+
+## AI usage tracking
+
+`projmux usage` reports authoritative 5-hour and weekly utilisation for both
+Claude Code and the Codex CLI. Both adapters read from the upstream's own
+view of your account so the percentages match what `claude /usage` and
+`codex` show natively:
+
+- **Claude** — calls `GET https://api.anthropic.com/api/oauth/usage` with the
+  bearer token in `~/.claude/.credentials.json`. The adapter performs a
+  single refresh round-trip on 401 and rewrites the credentials file with
+  the rotated tokens. Tokens are never logged.
+- **Codex** — reads the most recent `rate_limits` payload from the newest
+  `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. `primary` maps to the 5h
+  window, `secondary` to the weekly window.
+
+Snapshots are persisted under `<state>/projmux/usage/snapshots.json` (or
+`PROJMUX_USAGE_STATE_DIR`) and refreshed at most every 30 seconds when
+`projmux status usage` runs in the tmux status bar.
+
+## Scope
+
+`projmux` owns the portable session-management core: naming, discovery, pins,
+preview state, tmux orchestration, status segments, and generated tmux bindings.
+
+## Development
+
+Useful commands:
+
+```sh
+make build
+make fmt
+make fix
+make test
+make test-integration
+make test-e2e
+make verify
+```
+
+More documentation:
+
+- [Architecture](docs/architecture.md)
+- [CLI Reference](docs/cli.md)
+- [Statusbar](docs/statusbar.md)
+- [Notify queue](docs/notify-queue.md)
+- [Usage tracking](docs/usage-tracking.md)
+- [Hooks](docs/hooks.md)
+- [Migration Plan](docs/migration-plan.md)
+- [Repo Layout](docs/repo-layout.md)
+- [Terminal Keybindings](docs/keybindings.md)
+- [Agent Workflow](docs/agent-workflow.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@projmux/darwin-x64",
+  "version": "0.0.0-reserved",
+  "description": "macOS x64 binary for projmux",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crevissepartners/projmux.git"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "bin/projmux",
+    "README.md",
+    "LICENSE"
+  ]
+}