feat(workmux): global config, workmux-palette source, mise package, docs

This commit is contained in:
root committed 2026-11-10 11:17:01 -05:00
1 parent 796885e5f4
commit 59d963b128
7 files changed
+215 -1

No files matched your search

+30
View File
@@ -54,6 +54,7 @@ Several scripts below also exist as fish functions of the same name (`ai`, `c2p`
| [`projects-sync`](#projects-sync) | bash | Symlink every `~/Code` repo into `~/Projects` |
| [`pj-palette`](#pj-palette) | bash | pj's tasks plus quick actions as a tmux-palette source |
| [`tmux-sessions`](#tmux-sessions) | bash | Session/window/zoxide switcher as a tmux-palette source |
| [`workmux-palette`](#workmux-palette) | bash | workmux agents and worktrees as a tmux-palette source |
| [`yazi-nvim-open`](#yazi-nvim-open) | sh | yazi opener that targets the host Neovim |
## ai
@@ -475,6 +476,35 @@ pj-palette's background task sessions (`@pj_task`) are left out. Sessions are ta
**Needs:** tmux, `jq`, `zoxide`.
## workmux-palette
```sh
workmux-palette
workmux-palette --add BRANCH
workmux-palette --popup DIR CMD…
workmux-palette --do DIR CMD…
```
The source of the **Workmux** [tmux command palette](../terminal/tmux.md#command-palette) (`palettes/workmux.json`) for [workmux](../tools/workmux.md). Open it with tmux `prefix w` or the "Workmux" item in the main palette.
With no arguments it prints palette items as JSON, grouped by category:
| Group | Items | Action |
| --- | --- | --- |
| Agents | Every agent `workmux status --all --json` tracks in this tmux server: waiting (yellow), done (green), working (blue), then idle, most recent first. Title `<repo>/<handle>`, description status, time since the change, and the pane title | `switch-client` to the agent's pane |
| Worktrees: `<repo>` | The active pane's repo's worktrees (`workmux list --json`, main checkout left out): branch, open/closed, dirty, path. Open ones are green | `workmux open` (starts the session if closed) |
| New | **New worktree from a prompt**, when the pane is in a repo | `workmux add -A -e` in a popup: `$EDITOR` for the prompt, omp names the branch |
| Workmux | **Dashboard** (90% popup), **Sidebar** (toggle), **Last done** (`workmux last-done`) | |
| Close | One per open worktree | `workmux close`: ends the session, keeps worktree and branch |
| Merge | One per worktree | `workmux merge` in a popup |
| Remove | One per worktree | `workmux remove` in a popup (asks before deleting unmerged commits) |
**`--add BRANCH`** is the palette's `query` item: the typed text, listed after the matches, becomes `workmux add BRANCH` in the active pane's directory, so a branch name that matches nothing creates its worktree and session and switches to it.
**`--popup DIR CMD…`** runs CMD in DIR in an 80% × 60% popup (argv form, so nothing is re-parsed by a shell or by tmux formats). The popup closes when CMD succeeds; on failure it shows `[exit N]` and waits for a key. **`--do DIR CMD…`** runs CMD in place and shows the last output line as a tmux message when it fails.
**Needs:** tmux, `jq`, `git`, `workmux`.
## yazi-nvim-open
```sh
+5 -1
View File
@@ -43,6 +43,7 @@ These settings are what [yazi](../tools/yazi.md) needs inside tmux. `allow-passt
| `prefix /` | Copy mode, then search upward |
| `prefix o` | Sessions palette ([`tmux-sessions`](../shell/scripts.md#tmux-sessions)): fuzzy-find the other sessions, every window of every session, zoxide's and `~/.config`'s directories, and Rename/Kill items per session. Typed text that is not a session starts one by that name in its zoxide match |
| `prefix t` | Project Tasks palette ([`pj-palette`](../shell/scripts.md#pj-palette)): install/dev/sync/make/compose quick actions plus every `pj` task. One-off tasks run in a full-width bottom split (25% of the window); dev servers and `docker compose up` run in a background `<session>:<tool-and-command>` session shown in a popup (`q` hides, `ctrl-c` asks `y/n` then stops), listed under Running to reopen |
| `prefix w` | Workmux palette ([`workmux-palette`](../shell/scripts.md#workmux-palette)): tracked agents by status, the repo's worktrees with Close/Merge/Remove, new worktree from the typed branch or a prompt, dashboard, sidebar, last-done. Replaces tmux's `choose-tree`, which the Sessions palette covers. See [workmux](../tools/workmux.md) |
| `prefix y` / `prefix e` | Yazi / Neovim in a new window in the pane cwd (Ghostty `ctrl+shift+f` / `ctrl+shift+e`) |
| `prefix g` | Lazygit in a 90% popup in the pane cwd (Ghostty `ctrl+shift+g`) |
| `prefix a` | omp in a background session `<session>:omp` (pane cwd), shown in a popup docked bottom-right (35% × 60%) and listed in the [omp palette](../shell/scripts.md#pj-palette) and under Running in the tasks palette. In the popup, `ctrl-c` hides it and `ctrl-q` quits omp. Inside any background-task popup, `prefix a` hides it too, so Ghostty `ctrl+shift+a` toggles omp |
@@ -82,6 +83,8 @@ Each window reads `<index> <icon> <label>`, updating as you work, the same rule
Labels longer than 27 characters end in `…`. The icon comes from tmux-nerd-font-window-name.
A window whose agent workmux tracks shows its status icon after the label (`#{@workmux_status}`: working, waiting, done; waiting and done clear when the window gets focus). workmux's own `status_format` is off so it does not rewrite these formats. See [workmux](../tools/workmux.md#agent-status).
## Plugins
| Plugin | Settings |
@@ -99,9 +102,10 @@ Labels longer than 27 characters end in `…`. The icon comes from tmux-nerd-fon
| File | Contents |
| --- | --- |
| `commands.json` | The kitty launchers ported as palette items: **Lazygit** (90% popup in the pane's cwd; kitty `ctrl+shift+g`), **Yazi** (new window; kitty `ctrl+shift+f`), **Neovim Split** (nvim in a split to the left, 60% of the pane; alias `nv`; kitty `ctrl+shift+e`), **Shell History (atuin)** (`atuin-pick` in a 25% split below; kitty `ctrl+shift+p`). Also **btop** (80% popup; aliases `top`, `htop`), **Lazydocker** (90% popup in the pane's cwd; alias `dd`), **mandible** (80% popup running [`mandible-pick`](../shell/scripts.md#mandible-pick); alias `man`), **television** (`tv channels`, the [channel picker](../tools/television.md), in a new window in the pane's cwd; alias `tv`), **gitframe** (git diff viewer in a new window in the pane's cwd; alias `gf`), **omp** (opens the omp palette; aliases `agent`, `ai`), **Project Tasks** (opens the tasks palette), **Sessions** (opens the sessions palette; aliases `sx`, `ss`), **Save Sessions**, and **Restore Sessions** (resurrect). Programs are started with `exec`, so the tab icon is the program's, not the shell's |
| `commands.json` | The kitty launchers ported as palette items: **Lazygit** (90% popup in the pane's cwd; kitty `ctrl+shift+g`), **Yazi** (new window; kitty `ctrl+shift+f`), **Neovim Split** (nvim in a split to the left, 60% of the pane; alias `nv`; kitty `ctrl+shift+e`), **Shell History (atuin)** (`atuin-pick` in a 25% split below; kitty `ctrl+shift+p`). Also **btop** (80% popup; aliases `top`, `htop`), **Lazydocker** (90% popup in the pane's cwd; alias `dd`), **mandible** (80% popup running [`mandible-pick`](../shell/scripts.md#mandible-pick); alias `man`), **television** (`tv channels`, the [channel picker](../tools/television.md), in a new window in the pane's cwd; alias `tv`), **gitframe** (git diff viewer in a new window in the pane's cwd; alias `gf`), **omp** (opens the omp palette; aliases `agent`, `ai`), **Workmux** (opens the workmux palette; aliases `wm`, `worktree`), **Project Tasks** (opens the tasks palette), **Sessions** (opens the sessions palette; aliases `sx`, `ss`), **Save Sessions**, and **Restore Sessions** (resurrect). Programs are started with `exec`, so the tab icon is the program's, not the shell's |
| `palettes/tasks.json` | The **Project Tasks** palette (`prefix t`, Ghostty `ctrl+shift+p` / `ctrl+shift+space`), fed by [`pj-palette`](../shell/scripts.md#pj-palette): running background tasks under Running, then `bun install`, `bun run dev`, `uv sync`, `uv run python`, `make`, `go run .`, `cargo run`, `docker compose up` as Quick items when the project has them, then every task `pj` finds, grouped by tool. One-off tasks run in a full-width split along the bottom (25% of the window) in their directory; `ctrl-c` stops a running task, and once it has exited, `enter` or `ctrl-c` closes the pane. Dev servers (`dev`/`start`/`serve`/`watch`/`preview` tasks) and `docker compose up` run in a background session `<session>:<tool-and-command>` shown in a popup: `q` hides it with the task still running, `ctrl-c` asks `Stop <session>? (y/n)` and on `y` stops the task and closes it |
| `palettes/omp.json` | The **omp** palette, fed by [`pj-palette --omp`](../shell/scripts.md#pj-palette): this tmux session's `<session>:omp` (open it, or start it when not running), every other tmux session's running omp, and a Quit item per session. Running agents have a green icon and show `open` or `hidden` |
| `palettes/workmux.json` | The **Workmux** palette (`prefix w`), fed by [`workmux-palette`](../shell/scripts.md#workmux-palette): Agents (by status), Worktrees of the pane's repo, New, Workmux tools, Close, Merge, Remove. Its `query` item lists the typed text last; `enter` on it runs `workmux-palette --add <text>` (new worktree and session for that branch) |
| `palettes/sessions.json` | The **Sessions** palette (`prefix o`, Ghostty `ctrl+shift+o`), fed by [`tmux-sessions`](../shell/scripts.md#tmux-sessions): Sessions (the last one first, attached ones green), Windows, Zoxide, Config, Rename, Kill. Its `query` item lists the typed text last; `enter` on it runs `tmux-sessions --new <text>` |
| `hidden.json` | Hides the built-in **Switch Theme...** item, and with it the Appearance section: the palette stays on the fixed cyberdream `theme.json` |
| `shortcuts.json` | Ghostty `ctrl+shift` chords shown next to the built-in items they trigger (New Window → `Ctrl+Shift+T`, …) |
+1
View File
@@ -21,6 +21,7 @@ Packages come from `.chezmoidata/packages.yaml` and are installed by `run_onchan
| [Hunk](hunk.md) | hunk diff viewer | `dot_config/hunk/config.toml` | `auto` |
| [drydock](drydock.md) | drydock repo fleet view | `dot_config/drydock/config.toml` | n/a |
| [television](television.md) | tv fuzzy picker, custom cables | external repo via `.chezmoiexternals/television.toml` | `cyberdream-transparent` |
| [workmux](workmux.md) | worktree + tmux session per agent | `dot_config/workmux/config.yaml` | n/a (palette: cyberdream) |
| [LeetCode](leetcode.md) | leetcode CLI, `lc-elir` | `dot_leetcode/` | n/a |
| [SSH and mosh](ssh.md) | ssh, mosh | `private_dot_ssh/config` | n/a |
+31
View File
@@ -0,0 +1,31 @@
# workmux
workmux global config: one git worktree and one tmux session per agent, driven from the Workmux palette.
[workmux](https://workmux.dev) pairs each git worktree with a tmux target and starts an agent in it. Here every worktree gets its own tmux session (an omp window and an nvim window), and the [Workmux palette](../shell/scripts.md#workmux-palette) (tmux `prefix w`, or `ctrl+space` → Workmux) covers the lifecycle: open, new, close, merge, remove, and jumping to agents by status.
| | |
| --- | --- |
| Source | `dot_config/workmux/config.yaml` |
| Target | `~/.config/workmux/config.yaml` (symlink) |
| Packages | `workmux` under `packages.shared.mise` |
| Status tracking | omp extension `~/.omp/agent/extensions/workmux-status.ts` (in the [omp external](../chezmoi/externals-and-ignore.md)) |
## config.yaml
| Key | Value | Effect |
| --- | --- | --- |
| `nerdfont` | `true` | Nerd Font icons in workmux's own UI. |
| `mode` | `session` | Each worktree is a tmux session, so the session pill, Ghostty's window title, and the [Sessions palette](../shell/scripts.md#tmux-sessions) list it like any other session. |
| `window_prefix` | `"{project}/"` | Session names read `<repo>/<handle>`. |
| `worktree_dir` | `~/Work/{project}` | Worktrees land in `~/Work/<repo>/<handle>`, next to worktrunk's `~/Work/<repo>-<branch>`. |
| `base_branch` | `auto` | New branches start from the repo's main branch, not the branch the pane is on. |
| `agent` | `omp` | `<agent>` runs omp; it receives `-p`/`-P`/`-e` prompts and names branches for `add -A`. |
| `windows` | omp (focused), nvim | Two unnamed windows, so `automatic-rename-format` labels them like every other tab. |
| `status_format` | `false` | workmux leaves `window-status-format` alone; `tmux.conf` renders `#{@workmux_status}` itself (see [Window tabs](../terminal/tmux.md#window-tabs)). |
A `.workmux.yaml` in a repo overrides any of these.
## Agent status
The omp extension reports `working`, `waiting`, and `done`. workmux stores the icon in the window option `@workmux_status`, which the tab formats print after the label. The palette's Agents group reads `workmux status --all --json`.