Skip to content
Back to search

workmux

MarketplaceWorks with Claude CodeGitHub

git worktrees + tmux windows for zero-friction parallel dev

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/raine/workmux with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/raine/workmux'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/raine--workmux/badge.svg)](/listings/raine--workmux)

HTML

<a href="/listings/raine--workmux"><img src="/api/listings/raine--workmux/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Official sources:** [github.com/raine/workmux](https://github.com/raine/workmux) and [workmux.raine.dev](https://workmux.raine.dev/). This project is not affiliated with workmux.com.

Bash YOLO

curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash

Homebrew (macOS/Linux)

brew install raine/workmux/workmux

<details> <summary>Other methods (Cargo, mise, Nix)</summary>

**Cargo** (requires [rustup](https://rustup.rs/)):

cargo install workmux

**mise:**

mise use -g cargo:raine/workmux

**Nix** ([flake and home-manager setup](https://workmux.raine.dev/guide/nix)):

nix profile install github:raine/workmux

</details>

---

For manual installation, see [pre-built binaries](https://github.com/raine/workmux/releases/latest).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "workmux",
  3. "owner": {
  4. "name": "raine",
  5. "email": "raine.virta@gmail.com"
  6. },
  7. "metadata": {
  8. "description": "Plugins for workmux - git worktrees and tmux workflow tool"
  9. },
  10. "plugins": [
  11. {
  12. "name": "workmux-status",
  13. "source": "./",
  14. "description": "Display Claude agent status (working/waiting) in tmux window names"
  15. }
  16. ]
  17. }
README.md · README · 2,963 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="meta/logo-dark.svg">
  4. <img src="meta/logo.svg" alt="workmux icon" width="300">
  5. </picture>
  6. </p>
  7. <p align="center">
  8. <strong>Parallel development in tmux* with git worktrees</strong>
  9. </p>
  10. <p align="center">
  11. <a href="https://workmux.dev/"><strong>📖 Documentation</strong></a> ·
  12. <a href="#installation">Install</a> ·
  13. <a href="#quick-start">Quick start</a> ·
  14. <a href="#commands">Commands</a> ·
  15. <a href="CHANGELOG.md">Changelog</a>
  16. </p>
  17. ---
  18. Giga opinionated zero-friction workflow tool for managing
  19. [git worktrees](https://git-scm.com/docs/git-worktree) and tmux windows as
  20. isolated development environments. Perfect for running multiple AI agents in
  21. parallel without conflict.
  22. **Philosophy**: Build on tools you already use. tmux/zellij/kitty/etc. for
  23. windowing, git for worktrees, your agent for coding - workmux ties them together.
  24. <sup><sub>\* Also supports
  25. <a href="https://workmux.dev/guide/kitty">kitty</a>,
  26. <a href="https://workmux.dev/guide/wezterm">WezTerm</a>, and
  27. <a href="https://workmux.dev/guide/zellij">Zellij</a> as alternative
  28. backends.</sub></sup>
  29. 📖 **New to workmux?** Read the
  30. [introduction blog post](https://raine.dev/blog/introduction-to-workmux/) for a
  31. quick overview.
  32. ![workmux screenshot](https://raw.githubusercontent.com/raine/workmux/refs/heads/main/meta/screenshot_20260329_165534.webp)
  33. <a href="https://aventasks.dev/">
  34. <picture>
  35. <source media="(prefers-color-scheme: dark)" srcset="https://aventasks.dev/readme/aven-banner-dark.webp">
  36. <img src="https://aventasks.dev/readme/aven-banner-light.webp" alt="aven: one task queue for you and your coding agents" width="100%">
  37. </picture>
  38. </a>
  39. <sub>Also from the author of workmux: <a href="https://aventasks.dev/"><b>aven</b></a>, one
  40. queue for every project, with a keyboard-driven TUI for you and a CLI for your
  41. agents.</sub>
  42. ## Why workmux?
  43. **Parallel workflows.** Work on multiple features the same time, each with its
  44. own AI agent. No stashing, no branch switching, no conflicts.
  45. **One window per task.** A natural mental model. Each has its own terminal
  46. state, editor session, dev server, and AI agent. Context switching is switching
  47. tabs.
  48. **Automated setup.** New worktrees start broken (no `.env`, no `node_modules`,
  49. no dev server). workmux can copy config files, symlink dependencies, and run
  50. install commands on creation.
  51. **One-command cleanup.** `workmux merge` handles the full lifecycle: merge the
  52. branch, delete the worktree, close the tmux window, remove the local branch.
  53. **Terminal workflow.** Build on your terminal setup instead of yet another
  54. agentic GUI that won't exist next year. If you don't have one yet, tmux might be
  55. worth picking up.
  56. New to worktrees? See [Why git worktrees?](#why-git-worktrees)
  57. ## Features
  58. - Create git worktrees with matching tmux windows in a single command (`add`)
  59. - Merge branches and clean up everything (worktree, tmux window, branches) in
  60. one command (`merge`)
  61. - [Dashboard](#workmux-dashboard) for monitoring agents, reviewing changes, and
  62. sending commands
  63. - [Sidebar](https://workmux.dev/guide/sidebar/) for a persistent,
  64. at-a-glance view of all agents across tmux windows or Zellij tabs
  65. - [Delegate tasks to worktree agents](#delegating-tasks-with-worktree) with the
  66. `/worktree` skill
  67. - [Display agent status in tmux window names](#agent-status-tracking)
  68. - Automatically set up your preferred tmux pane layout (editor, shell, watchers,
  69. etc.)
  70. - Run post-creation hooks (install dependencies, setup database, etc.)
  71. - Copy or symlink configuration files (`.env`, `node_modules`) into new
  72. worktrees
  73. - [Sandbox agents](#sandbox) in containers or VMs for enhanced security
  74. - [Run agents on a remote server](https://workmux.dev/guide/remote/)
  75. over SSH while others stay local
  76. - [Automatic branch name generation](#automatic-branch-name-generation) from
  77. prompts using LLM
  78. - Shell completions
  79. ## What people say
  80. - *"I've been using (and loving) workmux which brings together tmux, git
  81. worktrees, and CLI agents into an opinionated workflow."* -
  82. [Coolin96 on Hacker News](https://news.ycombinator.com/item?id=46029809)
  83. - *"Thank you so much for your work with workmux! It's a tool I've been wanting
  84. to exist for a long time."* -
  85. [rstacruz on GitHub](https://github.com/raine/workmux/issues/2)
  86. - *"It's become my daily driver - the perfect level of abstraction over tmux +
  87. git, without getting in the way or obscuring the underlying tooling."* -
  88. [cisaacstern on GitHub](https://github.com/raine/workmux/issues/33)
  89. - *"I have to mention workmux at every opportunity because it's the perfect glue
  90. between worktrees, agents and tmux windows."* -
  91. [dedbrizz on Threads](https://www.threads.com/@dedbrizz/post/DVt1DtLkr_l)
  92. - *"Since I discovered workmux I'm cooking. Amazing parallel-agent driver if you
  93. like tmux and want to keep your config."* -
  94. [MatijaSosic on X](https://x.com/MatijaSosic/status/2080022087281127659)
  95. - *"Using workmux with a well-configured tmux has been a breath of fresh air"* -
  96. [sbeirakh_il on X](https://x.com/sbeirakh_il/status/2080279929778733305)
  97. - *"I've been using it for about a month now, and it's been nothing but
  98. great."* -
  99. [gabrielrockson_ on X](https://x.com/gabrielrockson_/status/2080386326566736189)
  100. - *"I still don't see the need for Herdr. Workmux adds busy/question/done
  101. status, manages worktrees by itself, and etc. It lives on an already existing
  102. tmux setup."* -
  103. [13hcoks on X](https://x.com/13hcoks/status/2080278051309355485)
  104. - *"workmux is fantastic. nothing too fancy, solves a real problem and stays in
  105. TMUX ❤️"* -
  106. [devopstoolbox on X](https://x.com/devopstoolbox/status/2094442083717390547)
  107. - *"Workmux is fantastic if you're mostly terminal bound."* -
  108. [cody1786 on X](https://x.com/cody1786/status/2033959173361213870)
  109. - *"Want modern terminal workspace features without abandoning your setup?
  110. Here is how to keep Tmux and boost your workflow using Workmux."* -
  111. [Sam Natale on YouTube](https://www.youtube.com/watch?v=ww1wykxJps8)
  112. ## Community videos
  113. Some kind people have made videos about workmux on YouTube. If you're looking
  114. for a demo, check them out.
  115. <table>
  116. <tr>
  117. <td width="33%">
  118. <a href="https://www.youtube.com/watch?v=ww1wykxJps8"><img src="https://raw.githubusercontent.com/raine/workmux/refs/heads/main/docs/src/assets/videos/ww1wykxJps8.webp" alt="Tmux is Still Better Than Herdr (Here's Why)"></a><br>
  119. <a href="https://www.youtube.com/watch?v=ww1wykxJps8">Tmux is Still Better Than Herdr (Here's Why)</a><br>
  120. Sam Natale
  121. </td>
  122. <td width="33%">
  123. <a href="https://www.youtube.com/watch?v=7uumknh43rM"><img src="https://raw.githubusercontent.com/raine/workmux/refs/heads/main/docs/src/assets/videos/7uumknh43rM.webp" alt="I Don't Want a New Terminal. I Want THIS for Tmux."></a><br>
  124. <a href="https://www.youtube.com/watch?v=7uumknh43rM">I Don't Want a New Terminal. I Want THIS for Tmux.</a><br>
  125. DevOps Toolbox
  126. </td>
  127. <td width="33%">
  128. <a href="https://www.youtube.com/watch?v=0RGyt3EDP-E"><img src="https://raw.githubusercontent.com/raine/workmux/refs/heads/main/docs/src/assets/videos/0RGyt3EDP-E.webp" alt="Tmux Didn't Need a Replacement, It Needed Workmux"></a><br>
  129. <a href="https://www.youtube.com/watch?v=0RGyt3EDP-E">Tmux Didn't Need a Replacement, It Needed Workmux</a><br>
  130. Seth Phaeno
  131. </td>
  132. </tr>
  133. </table>
  134. ## Installation
  135. **Official sources:** [github.com/raine/workmux](https://github.com/raine/workmux)
  136. and [workmux.dev](https://workmux.dev/). This project is not affiliated
  137. with workmux.com.
  138. ### Bash YOLO
  139. ```bash
  140. curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash
  141. ```
  142. ### Homebrew (macOS/Linux)
  143. ```bash
  144. brew install raine/workmux/workmux
  145. ```
  146. <details>
  147. <summary>Other methods (Cargo, mise, Nix)</summary>
  148. **Cargo** (requires [rustup](https://rustup.rs/)):
  149. ```bash
  150. cargo install workmux
  151. ```
  152. **mise:**
  153. ```bash
  154. mise use -g cargo:raine/workmux
  155. ```
  156. **Nix** ([flake and home-manager setup](https://workmux.dev/guide/nix)):
  157. ```bash
  158. nix profile install github:raine/workmux
  159. ```
  160. </details>
  161. ---
  162. For manual installation, see
  163. [pre-built binaries](https://github.com/raine/workmux/releases/latest).
  164. ## Quick start
  165. <!-- prettier-ignore -->
  166. > [!NOTE]
  167. > workmux requires a terminal multiplexer. Make sure you have
  168. > [tmux](https://github.com/tmux/tmux) (or
  169. > [WezTerm](https://raine.github.io/workmux/guide/wezterm) /
  170. > [Kitty](https://raine.github.io/workmux/guide/kitty) /
  171. > [Zellij](https://raine.github.io/workmux/guide/zellij)) installed and running
  172. > before you start. See [My tmux setup](https://raine.dev/blog/my-tmux-setup/)
  173. > if you need a starting point.
  174. 1. **Initialize configuration (optional)**:
  175. ```bash
  176. workmux init
  177. ```
  178. This creates a `.workmux.yaml` file to customize your workflow (pane layouts,
  179. setup commands, file operations, etc.). workmux works out of the box with
  180. sensible defaults, so this step is optional.
  181. 2. **Create a new worktree and tmux window**:
  182. ```bash
  183. workmux add new-feature
  184. ```
  185. This will:
  186. - Create a git worktree at
  187. `<project_root>/../<project_name>__worktrees/new-feature`
  188. - Copy config files and symlink dependencies (if
  189. [configured](#file-operations))
  190. - Run any [`post_create`](#lifecycle-hooks) setup commands
  191. - Create a tmux window named `wm-new-feature` (the prefix is configurable)
  192. - Set up your configured or the default tmux pane layout
  193. - Automatically switch your tmux client to the new window
  194. 3. **Do your thing**
  195. 4. **Finish and clean up**
  196. **Local merge:** Run `workmux merge` to merge into the base branch and clean
  197. up in one step.
  198. **PR workflow:** Push and open a PR. After it's merged, run `workmux remove`
  199. to clean up.
  200. ## Configuration
  201. workmux uses a two-level configuration system:
  202. - **Global** (`~/.config/workmux/config.yaml`): Personal defaults for all
  203. projects
  204. - **Project** (`.workmux.yaml`): Project-specific overrides
  205. Project settings override global settings. When you run workmux from a
  206. subdirectory, it walks upward to find the nearest `.workmux.yaml`, allowing
  207. nested configs for monorepos. See the
  208. [Monorepos guide](https://workmux.dev/guide/monorepos#nested-configuration)
  209. for details. For hook lists (`post_create`, `pre_merge`, `pre_remove`) and file
  210. operation lists (`files.copy`, `files.symlink`), you can use `"<global>"` to
  211. include global values alongside project-specific ones. Other settings like
  212. `panes` are replaced entirely when defined in the project config.
  213. ### Global configuration example
  214. `~/.config/workmux/config.yaml`:
  215. ```yaml
  216. nerdfont: true # Enable nerdfont icons (prompted on first run)
  217. merge_strategy: rebase # Make workmux merge do rebase by default
  218. merge_keep: true # Keep worktree, window, and branch after merge by default
  219. confirm_unmerged_removal: false # Remove unmerged branches without confirmation
  220. agent: claude
  221. panes:
  222. - command: <agent> # Start the configured agent (e.g., claude)
  223. focus: true
  224. - split: horizontal # Second pane with default shell
  225. ```
  226. ### Project configuration example
  227. `.workmux.yaml`:
  228. ```yaml
  229. post_create:
  230. - '<global>'
  231. - mise use
  232. files:
  233. symlink:
  234. - '<global>' # Include global symlinks (node_modules)
  235. - .pnpm-store # Add project-specific symlink
  236. panes:
  237. - command: pnpm install
  238. focus: true
  239. - command: <agent>
  240. split: horizontal
  241. - command: pnpm run dev
  242. split: vertical
  243. ```
  244. For a real-world example, see
  245. [workmux's own `.workmux.yaml`](https://github.com/raine/workmux/blob/main/.workmux.yaml).
  246. ### Configuration options
  247. Most options have sensible defaults. You only need to configure what you want to
  248. customize.
  249. #### Basic options
  250. | Option | Description | Default |
  251. | ---------------- | ----------------------------------------------------------------------------------------------------- | --------------------------- |
  252. | `main_branch` | Branch to merge into | Auto-detected |
  253. | `base_branch` | Default base ref for new worktrees, or `auto` for the effective main branch | Current branch |
  254. | `worktree_dir` | Directory for worktrees (absolute or relative). Supports `~` and `{project}`. | `<project>__worktrees/` |
  255. | `window_prefix` | Prefix for tmux window/session names. Supports `{project}`. | `wm-` |
  256. | `mode` | Tmux mode (`window` or `session`) | `window` |
  257. | `default_session` | Session to return to when a workmux session closes (session mode) | Previous session |
  258. | `window_placement` | New tmux window placement (`after_current` or `rightmost`) | `after_current` |
  259. | `agent` | Default agent for `<agent>` placeholder | `claude` |
  260. | `agents` | Named agent commands ([docs](https://workmux.dev/guide/agents#named-agents), global-only) | `{}` |
  261. | `merge_strategy` | Default merge strategy (`merge`, `rebase`, `squash`) | `merge` |
  262. | `merge_keep` | Keep resources after `workmux merge` by default | `false` |
  263. | `confirm_unmerged_removal` | Confirm before deleting branches with commits not merged into their base | `true` |
  264. | `theme` | Dashboard color scheme ([custom colors](https://workmux.dev/guide/configuration#custom-colors)) | `default` (auto dark/light) |
  265. Set `base_branch: auto` to create independent work streams from each repository's
  266. effective main branch. Workmux uses configured `main_branch`, then the local
  267. `origin/HEAD`, `main`, or `master`. Detection uses local Git state and does not
  268. fetch. Omitting `base_branch` continues to create branches from the checked-out
  269. branch.
  270. #### Naming options
  271. | Option | Description | Default |
  272. | ----------------- | ------------------------------------------- | ------- |
  273. | `worktree_naming` | How to derive names from branches | `full` |
  274. | `worktree_prefix` | Prefix for worktree directories and windows | none |
  275. `worktree_naming` strategies:
  276. - `full`: Use the full branch name (slashes become dashes)
  277. - `basename`: Use only the part after the last `/` (e.g., `prj-123/feature` →
  278. `feature`)
  279. #### Panes
  280. Define your multiplexer pane layout with the `panes` array. For multiple windows in
  281. session mode, use [`windows`](#multiple-windows-per-session) instead (they are
  282. mutually exclusive).
  283. ```yaml
  284. panes:
  285. - command: <agent>
  286. name: agent
  287. focus: true
  288. - command: npm run dev
  289. name: dev
  290. split: horizontal
  291. size: 15
  292. ```
  293. Each pane supports:
  294. | Option | Description | Default |
  295. | ------------ | ---------------------------------------------------------------------------- | ---------------- |
  296. | `name` | Pane display name (currently applied by the Zellij backend) | --- |
  297. | `command` | Command to run (see [agent placeholders](#agent-placeholders)) | Shell |
  298. | `focus` | Whether this pane receives focus | `false` |
  299. | `zoom` | Zoom pane to fullscreen (implies `focus: true`) | `false` |
  300. | `split` | Split direction (`horizontal` or `vertical`) | --- |
  301. | `size` | Absolute size in lines/cells | 50% |
  302. | `percentage` | Size as percentage (1-100) | 50% |
  303. | `target` | 0-based pane index to split from; defaults to most recent pane | most recent pane |
  304. Use `target` when you want to split something other than the pane that was just
  305. created. The target must reference an earlier pane in the same layout.
  306. ```yaml
  307. panes:
  308. - command: nvim
  309. focus: true
  310. - command: pnpm install && pnpm run dev
  311. split: vertical
  312. size: 15
  313. - command: <agent>
  314. split: horizontal
  315. target: 0
  316. ```
  317. This creates three panes: `nvim` is at the top left, the agent is to its right,
  318. and the dev server spans the bottom.
  319. ##### Agent placeholders
  320. - `<agent>`: resolves to the configured agent (from `agent` config or `--agent`
  321. flag)
  322. Built-in agents (`claude`, `gemini`, `agy`, `codex`, `copilot`, `opencode`, `kiro-cli`,
  323. `vibe`, `pi`, `omp`, `grok`) are auto-detected when used as literal commands and receive prompt
  324. injection automatically, without needing the `<agent>` placeholder or a matching
  325. `agent` config:
  326. ```yaml
  327. panes:
  328. - command: 'claude --dangerously-skip-permissions'
  329. focus: true
  330. - command: 'codex --yolo'
  331. split: vertical
  332. ```
  333. Each agent receives the prompt (via `-p`/`-P`/`-e`) using the correct format for
  334. that agent. Auto-detection matches the executable name regardless of flags or
  335. path.
  336. Antigravity CLI support covers command detection, prompt injection, and status
  337. tracking via lifecycle hooks installed by `workmux setup`.
  338. #### Named layouts
  339. Define reusable pane arrangements in the `layouts` map and select one at
  340. add-time with `-l/--layout`:
  341. ```yaml
  342. layouts:
  343. design:
  344. panes:
  345. - command: <agent>
  346. focus: true
  347. - command: <agent:codex>
  348. split: vertical
  349. review:
  350. panes:
  351. - command: <agent>
  352. ```
  353. ```bash
  354. workmux add my-feature -l design
  355. ```
  356. When `-l` is used, the layout's `panes` replace the top-level `panes` for that
  357. worktree. All other config (hooks, files, agent, etc.) comes from the top-level
  358. as usual. The `-l` flag cannot be combined with `--agent`.
  359. #### File operations
  360. New worktrees are clean checkouts with no gitignored files (`.env`,
  361. `node_modules`, etc.). Use `files` to automatically copy or symlink what each
  362. worktree needs:
  363. ```yaml
  364. files:
  365. copy:
  366. - .env
  367. symlink:
  368. - .next/cache # Share build cache across worktrees
  369. ```
  370. Both `copy` and `symlink` accept glob patterns.
  371. To re-apply file operations to an existing worktree (e.g., after updating the
  372. config), run `workmux sync-files` from inside the worktree. Use `--all` to sync
  373. all worktrees at once.
  374. #### Lifecycle hooks
  375. Run commands at specific points in the worktree lifecycle, such as installing
  376. dependencies or running database migrations. All hooks run with the **worktree
  377. directory** as the working directory (or the nested config directory for
  378. [nested configs](https://workmux.dev/guide/monorepos#nested-configuration))
  379. and receive environment variables: `WM_HANDLE`, `WM_WORKTREE_PATH`,
  380. `WM_PROJECT_ROOT`, `WM_CONFIG_DIR`.
  381. `hook_shell` is an argv list containing the executable followed by its
  382. arguments. Workmux appends each hook command as the final argument. It defaults
  383. to `["bash", "-c"]` for compatibility. Machine-specific paths belong in global
  384. configuration:
  385. ```yaml
  386. hook_shell: ["/opt/homebrew/bin/bash", "-c"]
  387. ```
  388. A project can override the complete argv, or inherit the global value by
  389. omitting `hook_shell`. The argv must contain a non-empty executable. Shell flags
  390. and error handling apply only when included explicitly.
  391. `WM_PROJECT_ROOT` points to the repository's main worktree, regardless of where
  392. the selected config is stored. `WM_CONFIG_DIR` points to the corresponding
  393. config directory in the new worktree, which may differ from `WM_WORKTREE_PATH`
  394. when using nested configs.
  395. | Hook | When it runs | Additional env vars |
  396. | ------------- | ------------------------------------------------- | ------------------------------------ |
  397. | `post_create` | After worktree creation, before tmux window opens | — |
  398. | `pre_merge` | Before merging (aborts on failure) | `WM_BRANCH_NAME`, `WM_TARGET_BRANCH` |
  399. | `pre_remove` | Before worktree removal (aborts on failure) | — |
  400. Example:
  401. ```yaml
  402. post_create:
  403. - direnv allow
  404. pre_merge:
  405. - just check
  406. ```
  407. In Node.js projects, `pre_remove` defaults to a fast `node_modules` cleanup, and
  408. defining your own commands replaces that default. Use
  409. `"<cleanup-node-modules>"` to keep it:
  410. ```yaml
  411. pre_remove:
  412. - cp -r test-results/ "$WM_PROJECT_ROOT/artifacts/$WM_HANDLE/"
  413. - "<cleanup-node-modules>"
  414. ```
  415. #### Agent status icons
  416. Customize the icons shown in tmux window names:
  417. ```yaml
  418. status_icons:
  419. working: '🤖' # Agent is processing
  420. waiting: '💬' # Agent needs input (auto-clears on focus)
  421. done: '✅' # Agent finished (auto-clears on focus)
  422. ```
  423. Agents in "working" status that produce no pane output for 10 seconds are
  424. automatically detected as interrupted.
  425. Set `status_format: false` to disable automatic tmux format modification
  426. #### Default behavior
  427. - Worktrees are created in `<project>__worktrees` as a sibling directory to your
  428. project by default
  429. - If no `panes` configuration is defined, workmux provides opinionated defaults:
  430. - For projects with a `CLAUDE.md` file: Opens the configured agent (see
  431. `agent` option) in the first pane, defaulting to `claude` if none is set.
  432. - For all other projects: Opens your default shell.
  433. - Both configurations include a second pane split horizontally
  434. - `post_create` commands are optional and only run if you configure them
  435. ### Automatic setup with panes
  436. Use the `panes` configuration to automate environment setup. Unlike
  437. `post_create` hooks which must finish before the tmux window opens, pane
  438. commands execute immediately _within_ the new window.
  439. This can be used for:
  440. - **Installing dependencies**: Run `npm install` or `cargo build` in a focused
  441. pane to monitor progress.
  442. - **Starting services**: Launch dev servers, database containers, or file
  443. watchers automatically.
  444. - **Running agents**: Initialize AI agents with specific context.
  445. Since these run in standard tmux panes, you can interact with them (check logs,
  446. restart servers) just like a normal terminal session.
  447. Running dependency installation (like `pnpm install`) in a pane command rather
  448. than `post_create` has a key advantage: you get immediate access to the tmux
  449. window while installation runs in the background. With `post_create`, you'd have
  450. to wait for the install to complete before the window even opens. This also
  451. means AI agents can start working immediately in their pane while dependencies
  452. install in parallel.
  453. ```yaml
  454. panes:
  455. # Pane 1: Install dependencies, then start dev server
  456. - command: pnpm install && pnpm run dev
  457. # Pane 2: AI agent
  458. - command: <agent>
  459. split: horizontal
  460. focus: true
  461. ```
  462. ### Directory structure
  463. Here's how workmux organizes your worktrees by default:
  464. ```
  465. ~/projects/
  466. ├── my-project/ <-- Main project directory
  467. │ ├── src/
  468. │ ├── package.json
  469. │ └── .workmux.yaml
  470. │
  471. └── my-project__worktrees/ <-- Worktrees created by workmux
  472. ├── feature-A/ <-- Isolated workspace for 'feature-A' branch
  473. │ ├── src/
  474. │ └── package.json
  475. │
  476. └── bugfix-B/ <-- Isolated workspace for 'bugfix-B' branch
  477. ├── src/
  478. └── package.json
  479. ```
  480. Each worktree is a separate working directory for a different branch, all
  481. sharing the same git repository. This allows you to work on multiple branches
  482. simultaneously without conflicts.
  483. You can customize the worktree directory location using the `worktree_dir`
  484. configuration option (see [Configuration options](#configuration-options)).
  485. The value supports `~` for the home directory and a `{project}` placeholder
  486. that resolves to the main worktree's directory name. This lets a single
  487. global config namespace every repo's worktrees under one root, e.g.
  488. `worktree_dir: ~/.workmux/{project}`.
  489. ### Shell alias (recommended)
  490. For faster typing, alias `workmux` to `wm`:
  491. ```bash
  492. alias wm='workmux'
  493. ```
  494. ## Commands
  495. - [`add`](#workmux-add-branch-name) - Create a new worktree and tmux window
  496. - [`merge`](#workmux-merge-branch-name) - Merge a branch and clean up everything
  497. - [`rebase`](#workmux-rebase-name) - Rebase a worktree branch onto its base branch
  498. - [`remove`](#workmux-remove-name-alias-rm) - Remove worktrees without merging
  499. - [`list`](#workmux-list) - List all worktrees with status
  500. - [`open`](#workmux-open-name) - Open a tmux window for an existing worktree
  501. - [`close`](#workmux-close-name) - Close a worktree's tmux window (keeps
  502. worktree)
  503. - [`resurrect`](#workmux-resurrect) - Restore worktree windows after a crash
  504. - [`path`](#workmux-path-name) - Get the filesystem path of a worktree
  505. - [`dashboard`](#workmux-dashboard) - Show TUI dashboard of all active agents
  506. - [`sidebar`](#workmux-sidebar) - Toggle a compact agent status sidebar in tmux, Zellij or Rex
  507. - [`reap-agents`](#workmux-reap-agents) - Exit tracked agent processes older than a threshold
  508. - [`config edit`](#workmux-config-edit) - Edit the global configuration file
  509. - [`init`](#workmux-init) - Generate configuration file
  510. - [`sandbox`](#workmux-sandbox) - Manage sandbox backends (container/Lima)
  511. - [`claude prune`](#workmux-claude-prune) - Clean up stale Claude Code entries
  512. - [`completions`](#workmux-completions-shell) - Generate shell completions
  513. - [`docs`](#workmux-docs) - Show detailed documentation
  514. ### `workmux add <branch-name>`
  515. Creates a new git worktree with a matching tmux window and switches you to it
  516. immediately. If the branch doesn't exist, it will be created automatically.
  517. - `<branch-name>`: Name of the branch to create or switch to, a remote branch
  518. reference (e.g., `origin/feature-branch`), or a GitHub fork reference (e.g.,
  519. `user:branch`). Remote and fork references are automatically fetched and
  520. create a local branch with the derived name. Fork references derive the local
  521. branch as `user-branch` (e.g., `someuser:feature` creates local branch
  522. `someuser-feature`). Optional when using `--pr`.
  523. #### Options
  524. - `--base <branch|commit|tag>`: Specify a base branch, commit, or tag to branch
  525. from when creating a new branch. Overrides `base_branch` config. The config
  526. value `auto` uses the effective main branch. Without either setting, workmux
  527. uses the currently checked out branch.
  528. - `--pr <number|url>`: Checkout a GitHub pull request by its number or full URL
  529. into a new worktree.
  530. - Requires the `gh` command-line tool to be installed and authenticated.
  531. - URLs use the form `https://github.com/<owner>/<repository>/pull/<number>`.
  532. - The local branch name defaults to the PR's head branch name, but can be
  533. overridden (e.g., `workmux add custom-name --pr 123`).
  534. - If that local branch already exists and has no worktree, it is reused.
  535. - `-A, --auto-name`: Generate branch name from prompt using LLM. See
  536. [Automatic branch name generation](#automatic-branch-name-generation).
  537. - `--name <name>`: Override the worktree directory and tmux window name. By
  538. default, these are derived from the branch name (slugified). Cannot be used
  539. with multi-worktree generation (`--count`, `--foreach`, or multiple
  540. `--agent`).
  541. - `-b, --background`: Create the tmux window in the background without switching
  542. to it. Useful with `--prompt-editor`.
  543. - `--remote [<name>]`: Create the workspace on a
  544. [remote server](https://workmux.dev/guide/remote/). The name is
  545. optional when `placement` names a remote or only one is configured. Put the
  546. branch name first: `workmux add my-branch --remote`.
  547. - `--local`: Create the workspace locally even when `placement` names a remote.
  548. - `-w, --with-changes`: Move uncommitted changes from the current worktree to
  549. the new worktree, then reset the original worktree to a clean state. Useful
  550. when you've started working on main and want to move your branches to a new
  551. worktree.
  552. - `--patch`: Interactively select which changes to move (requires
  553. `--with-changes`). Opens an interactive prompt for selecting hunks to stash.
  554. - `-u, --include-untracked`: Also move untracked files (requires
  555. `--with-changes`). By default, only staged and modified tracked files are
  556. moved.
  557. - `-p, --prompt <text>`: Provide an inline prompt that will be automatically
  558. passed to AI agent panes.
  559. - `-P, --prompt-file <path>`: Provide a path to a file whose contents will be
  560. used as the prompt.
  561. - `-e, --prompt-editor`: Open your `$EDITOR` (or `$VISUAL`) to write the prompt
  562. interactively.
  563. - `--prompt-file-only`: Write the prompt file to the worktree without injecting
  564. it into agent commands. No agent pane is required. Useful when your editor has
  565. an embedded agent that reads `.workmux/PROMPT-*.md` directly.
  566. - `-l, --layout <name>`: Use a named pane layout from config instead of the
  567. default panes. Cannot be combined with `--agent`.
  568. - `-a, --agent <name>`: The agent(s) to use for the worktree(s). Can be
  569. specified multiple times to generate a worktree for each agent. Overrides the
  570. `agent` from your config file.
  571. - `-W, --wait`: Block until the created tmux window is closed. Useful for
  572. scripting when you want to wait for an agent to complete its work. The agent
  573. can signal completion by running `workmux remove --keep-branch`.
  574. - `-o, --open-if-exists`: If a worktree for the branch already exists, open it
  575. instead of failing. Similar to `tmux new-session -A`. Useful when you don't
  576. know or care whether the worktree already exists.
  577. - `-s, --session`: Create a tmux session instead of a window. See
  578. [Session mode](#session-mode) for details.
  579. - `--dry-run`: Print the resolved worktree path, branch, base, multiplexer
  580. target, file operations, and post-create hooks without creating or modifying
  581. anything.
  582. - `--headless`: Create the worktree, apply file operations, and run
  583. `post_create` hooks without requiring or creating a multiplexer target.
  584. - `--json`: Emit a versioned provisioning receipt on stdout. Requires
  585. `--headless`. Hook output and diagnostics use stderr.
  586. - `--config <path>`: Use an alternate config file for this invocation. Still
  587. merges with global config.
  588. - `--fork`: Fork the last conversation from the current worktree into the new
  589. one. The agent resumes with the forked conversation context. Use
  590. `--fork=<session-id>` to fork a specific session (prefix matching supported).
  591. Supports Claude Code and Codex.
  592. #### Skip options
  593. These options allow you to skip expensive setup steps when they're not needed
  594. (e.g., for documentation-only changes):
  595. - `-H, --no-hooks`: Skip running `post_create` commands
  596. - `-F, --no-file-ops`: Skip file copy/symlink operations (e.g., skip linking
  597. `node_modules`)
  598. - `-C, --no-pane-cmds`: Skip executing pane commands (panes open with plain
  599. shells instead)
  600. #### What happens
  601. 1. Determines the **handle** for the worktree by slugifying the branch name
  602. (e.g., `feature/auth` becomes `feature-auth`). This can be overridden with
  603. the `--name` flag.
  604. 2. Creates a git worktree at `<worktree_dir>/<handle>` (the `worktree_dir` is
  605. configurable and defaults to a sibling directory of your project)
  606. 3. Runs any configured file operations (copy/symlink)
  607. 4. Executes `post_create` commands if defined (runs before the tmux window
  608. opens, so keep them fast)
  609. 5. Creates a new tmux window named `<window_prefix><handle>` (e.g.,
  610. `wm-feature-auth` with `window_prefix: wm-`)
  611. 6. Sets up your configured tmux pane layout
  612. 7. Automatically switches your tmux client to the new window
  613. In tmux window mode without `--parent-session`, `$TMUX_PANE` identifies the
  614. calling pane and its parent session. When `$TMUX_PANE` is absent or stale,
  615. workmux uses live pane working directories when their closest matches identify
  616. one session. A tmux server with one session is the final fallback. Remaining
  617. ambiguity requires `--parent-session <name>`. The working directory selects the
  618. Git repository and only provides conservative evidence for tmux placement.
  619. #### Headless provisioning
  620. Automation can provision a fully configured worktree without asking workmux to
  621. manage its terminal process:
  622. ```bash
  623. workmux add suba-parser-a1b2c3d4 \
  624. --name suba-parser-a1b2c3d4 \
  625. --headless \
  626. --json
  627. ```
  628. The command creates or checks out the local branch, applies configured file
  629. operations, and runs `post_create` hooks. It does not inspect or create mux
  630. sessions, windows, panes, layouts, or pane commands. The JSON receipt includes
  631. `schema_version`, `handle`, `branch`, absolute `worktree_path`, absolute
  632. `working_directory`, `base_branch`, and `post_create_hooks_run`.
  633. Headless worktrees persist until removed with `workmux remove <handle>`. A later
  634. `workmux open <handle>` attaches a workmux-managed multiplexer target. Headless
  635. branch arguments are local branch names; remote branch syntax is rejected.
  636. Prompt, rescue, multi-worktree, sandbox, wait, dry-run, and mux-specific options
  637. are not accepted with `--headless`.
  638. #### Examples
  639. ##### Basic usage
  640. ```bash
  641. # Create a new branch and worktree
  642. workmux add user-auth
  643. # Use an existing branch
  644. workmux add existing-work
  645. # Create a new branch from a specific base
  646. workmux add hotfix --base production
  647. # Create a worktree from a remote branch (creates local branch "user-auth-pr")
  648. workmux add origin/user-auth-pr
  649. # Remote branches with slashes work too (creates local branch "feature/foo")
  650. workmux add origin/feature/foo
  651. # Preview the resolved plan without creating anything
  652. workmux add feature/parallel-task --dry-run
  653. # Create a worktree in the background without switching to it
  654. workmux add feature/parallel-task --background
  655. # Use a custom name for the worktree directory and tmux window
  656. workmux add feature/long-descriptive-branch-name --name short
  657. # Open existing worktree if it exists, create if it doesn't (idempotent)
  658. workmux add my-feature -o
  659. ```
  660. ##### Checking out pull requests and fork branches
  661. ```bash
  662. # Checkout PR #123. The local branch will be named after the PR's branch.
  663. workmux add --pr 123
  664. # Checkout a pull request from its full GitHub URL with a custom local branch
  665. workmux add --pr https://github.com/raine/workmux/pull/456 fix/api-bug
  666. # Checkout a fork branch using GitHub's owner:branch format (copy from GitHub UI)
  667. # Creates local branch "someuser-feature-branch" tracking the fork
  668. workmux add someuser:feature-branch
  669. ```
  670. ##### Moving changes to a new worktree
  671. ```bash
  672. # Move uncommitted changes to a new worktree (including untracked files)
  673. workmux add feature/new-thing --with-changes -u
  674. # Move only staged/modified files (not untracked files)
  675. workmux add fix/bug --with-changes
  676. # Interactively select which changes to move
  677. workmux add feature/partial --with-changes --patch
  678. ```
  679. ##### AI agent prompts
  680. ```bash
  681. # Create a worktree with an inline prompt for AI agents
  682. workmux add feature/ai --prompt "Implement user authentication with OAuth"
  683. # Override the default agent for a specific worktree
  684. workmux add feature/testing -a gemini
  685. # Create a worktree with a prompt from a file
  686. workmux add feature/refactor --prompt-file task-description.md
  687. # Open your editor to write a prompt interactively
  688. workmux add feature/new-api --prompt-editor
  689. # Write prompt file only (for editors with embedded agents like neovim)
  690. workmux add feature/task -P task.md --prompt-file-only
  691. ```
  692. ##### Skipping setup steps
  693. ```bash
  694. # Skip expensive setup for documentation-only changes
  695. workmux add docs-update --no-hooks --no-file-ops --no-pane-cmds
  696. # Skip just the file operations (e.g., you don't need node_modules)
  697. workmux add quick-fix --no-file-ops
  698. ```
  699. ##### Scripting with --wait
  700. ```bash
  701. # Block until the agent completes and closes the window
  702. workmux add feature/api --wait -p "Implement the REST API, then run: workmux remove --keep-branch"
  703. # Use in a script to run sequential agent tasks
  704. for task in task1.md task2.md task3.md; do
  705. workmux add "task-$(basename $task .md)" --wait -P "$task"
  706. done
  707. ```
  708. #### AI agent integration
  709. When you provide a prompt via `--prompt`, `--prompt-file`, or `--prompt-editor`,
  710. workmux automatically injects the prompt into panes running the configured agent
  711. command (e.g., `claude`, `codex`, `copilot`, `opencode`, `gemini`, `agy`, `kiro-cli`, `vibe`,
  712. `pi`, `omp`, `grok`, or whatever you've set via the `agent` config or `--agent` flag) without
  713. requiring any `.workmux.yaml` changes:
  714. - Panes with a command matching the configured agent are automatically started
  715. with the given prompt.
  716. - You can keep your `.workmux.yaml` pane configuration simple (e.g.,
  717. `panes: [{ command: "<agent>" }]`) and let workmux handle prompt injection at
  718. runtime.
  719. This means you can launch AI agents with task-specific prompts without modifying
  720. your project configuration for each task.
  721. If your editor has an embedded agent (e.g., neovim with an agent plugin), use
  722. `--prompt-file-only` to write the prompt to `.workmux/PROMPT-<branch>.md`
  723. without requiring an agent pane. Your editor can then detect and consume the
  724. file on startup. This can also be set permanently in config with
  725. `prompt_file_only: true`.
  726. #### Automatic branch name generation
  727. The `--auto-name` (`-A`) flag generates a branch name from your prompt using an
  728. LLM. The tool used depends on your configuration:
  729. 1. `auto_name.command` is set: uses that command as-is
  730. 2. `config.agent` is a known agent (`claude`, `gemini`, `agy`, `codex`, `opencode`,
  731. `kiro-cli`, `vibe`, `pi`, `omp`): uses the agent's CLI with a fast/cheap model
  732. 3. Neither: falls back to the [`llm`](https://llm.datasette.io/) CLI tool
  733. ##### Usage
  734. ```bash
  735. # Opens editor for prompt, generates branch name
  736. workmux add -A
  737. # With inline prompt
  738. workmux add -A -p "Add OAuth authentication"
  739. # With prompt file
  740. workmux add -A -P task-spec.md
  741. ```
  742. ##### Requirements
  743. When `agent` is configured (e.g., `agent: claude`), workmux automatically uses
  744. that agent's CLI for branch naming. No additional setup is required beyond
  745. having the agent installed.
  746. If no agent is configured and no `auto_name.command` is set, workmux uses the
  747. `llm` CLI tool:
  748. ```bash
  749. pipx install llm
  750. ```
  751. Configure a model (e.g., OpenAI):
  752. ```bash
  753. llm keys set openai
  754. # Or use a local model
  755. llm install llm-ollama
  756. ```
  757. If you set `auto_name.command`, `llm` is not required.
  758. ##### Agent profile defaults
  759. When an agent is configured, these commands are used automatically:
  760. | Agent | Auto-name command |
  761. | ---------- | ---------------------------------------------------------------------------- |
  762. | `claude` | `claude --model haiku --no-session-persistence -p` |
  763. | `gemini` | `gemini -m gemini-2.5-flash-lite -p` |
  764. | `codex` | `codex exec --ephemeral --config model_reasoning_effort="low" -m gpt-6-luna` |
  765. | `opencode` | `opencode run` |
  766. | `kiro-cli` | `kiro-cli chat --no-interactive` |
  767. | `pi` | `pi --no-session -p` |
  768. | `omp` | `omp --no-session -p` |
  769. To override back to `llm` when an agent is configured, set
  770. `auto_name.command: "llm"`.
  771. ##### Configuration
  772. Optionally configure auto-name behavior in `.workmux.yaml`:
  773. ```yaml
  774. auto_name:
  775. model: 'gemini-2.5-flash-lite'
  776. background: true # Always run in background when using --auto-name
  777. system_prompt: |
  778. Generate a concise git branch name based on the task description.
  779. Rules:
  780. - Use kebab-case (lowercase with hyphens)
  781. - Keep it short: 1-3 words, max 4 if necessary
  782. - Focus on the core task/feature, not implementation details
  783. - No prefixes like feat/, fix/, chore/
  784. Examples of good branch names:
  785. - "Add dark mode toggle" → dark-mode
  786. - "Fix the search results not showing" → fix-search
  787. - "Refactor the authentication module" → auth-refactor
  788. - "Add CSV export to reports" → export-csv
  789. - "Shell completion is broken" → shell-completion
  790. Output ONLY the branch name, nothing else.
  791. ```
  792. To use a specific tool, set `auto_name.command`. The command string is split
  793. into program and arguments, and the composed prompt is piped via stdin. Valid
  794. Git branch names are preserved, including slash-separated prefixes such as
  795. `fix/issue-123`.
  796. ```yaml
  797. auto_name:
  798. command: 'claude -p'
  799. # Force llm even when an agent is configured
  800. auto_name:
  801. command: 'llm'
  802. ```
  803. | Option | Description | Default |
  804. | --------------- | ---------------------------------------------------------------- | -------------------------- |
  805. | `command` | Command for branch name generation (overrides agent profile) | Agent profile or `llm` CLI |
  806. | `model` | LLM model to use with the `llm` CLI (ignored when `command` set) | `llm`'s default |
  807. | `background` | Always run in background when using `--auto-name` | `false` |
  808. | `system_prompt` | Custom system prompt for branch name generation | Built-in prompt |
  809. Recommended models for fast, cheap branch name generation (with `llm`):
  810. - `gemini-2.5-flash-lite` (recommended)
  811. - `gpt-5-nano`
  812. #### Parallel workflows & multi-worktree generation
  813. workmux can generate multiple worktrees from a single `add` command, which is
  814. ideal for running parallel experiments or delegating tasks to multiple AI
  815. agents. This is controlled by four mutually exclusive modes:
  816. - (`-a`, `--agent`): Create a worktree for each specified agent.
  817. - (`-n`, `--count`): Create a specific number of worktrees.
  818. - (`--foreach`): Create worktrees based on a matrix of variables.
  819. - **stdin**: Pipe input lines to create worktrees with templated prompts.
  820. When using any of these modes, branch names are generated from a template, and
  821. prompts are templated with variables. Single-worktree prompts are passed through
  822. literally, so common syntax like GitHub Actions `${{ ... }}` does not need to be
  823. escaped.
  824. ##### Multi-worktree options
  825. - `-a, --agent <name>`: When used multiple times, creates one worktree for each
  826. agent.
  827. - `-n, --count <number>`: Creates `<number>` worktree instances. Can be combined
  828. with a single `--agent` flag to apply that agent to all instances.
  829. - `--foreach <matrix>`: Creates worktrees from a variable matrix string. The
  830. format is `"var1:valA,valB;var2:valX,valY"`. All value lists must have the
  831. same length. Values are paired by index position (zip, not Cartesian product):
  832. the first value of each variable goes together, the second with the second,
  833. etc.
  834. - `--branch-template <template>`: A
  835. [MiniJinja](https://docs.rs/minijinja/latest/minijinja/) (Jinja2-compatible)
  836. template for generating branch names.
  837. - Available variables: `{{ base_name }}`, `{{ agent }}`, `{{ num }}`,
  838. `{{ index }}`, `{{ input }}` (stdin), and any variables from `--foreach`.
  839. - Default:
  840. `{{ base_name }}{% if agent %}-{{ agent | slugify }}{% endif %}{% for key, value in foreach_vars %}-{{ value | slugify }}{% endfor %}{% if num %}-{{ num }}{% endif %}`
  841. - `--max-concurrent <number>`: Limits how many worktrees run simultaneously.
  842. When set, workmux creates up to `<number>` worktrees, then waits for any
  843. window to close before starting the next. Requires agents to close windows
  844. when done (e.g., via prompt instruction to run
  845. `workmux remove --keep-branch`).
  846. ##### Prompt templating
  847. When generating multiple worktrees, any prompt provided via `-p`, `-P`, or `-e`
  848. is treated as a MiniJinja template. You can use variables from your generation
  849. mode to create unique prompts for each agent or instance. For ordinary
  850. single-worktree `add` commands, prompt text is not templated.
  851. ##### Variable matrices in prompt files
  852. Instead of passing `--foreach` on the command line, you can specify the variable
  853. matrix directly in your prompt file using YAML frontmatter. This is more
  854. convenient for complex matrices and keeps the variables close to the prompt that
  855. uses them.
  856. **Format:**
  857. Create a prompt file with YAML frontmatter at the top, separated by `---`:
  858. **Example 1:** `mobile-task.md`
  859. ```markdown
  860. ---
  861. foreach:
  862. platform: [iOS, Android]
  863. lang: [swift, kotlin]
  864. ---
  865. Build a {{ platform }} app using {{ lang }}. Implement user authentication and
  866. data persistence.
  867. ```
  868. ```bash
  869. workmux add mobile-app --prompt-file mobile-task.md
  870. # Generates worktrees: mobile-app-ios-swift, mobile-app-android-kotlin
  871. ```
  872. **Example 2:** `agent-task.md` (using `agent` as a foreach variable)
  873. ```markdown
  874. ---
  875. foreach:
  876. agent: [claude, gemini]
  877. ---
  878. Implement the dashboard refactor using your preferred approach.
  879. ```
  880. ```bash
  881. workmux add refactor --prompt-file agent-task.md
  882. # Generates worktrees: refactor-claude, refactor-gemini
  883. ```
  884. **Behavior:**
  885. - Variables from the frontmatter are available in both the prompt template and
  886. the branch name template
  887. - All value lists must have the same length, and values are paired by index
  888. position (same zip behavior as `--foreach`)
  889. - CLI `--foreach` overrides frontmatter with a warning if both are present
  890. - Works with both `--prompt-file` and `--prompt-editor`
  891. ##### Stdin input
  892. You can pipe input lines to `workmux add` to create multiple worktrees. Each
  893. line becomes available as the `{{ input }}` template variable in your prompt.
  894. This is useful for batch-processing tasks from external sources.
  895. **Plain text:** Each line becomes `{{ input }}`
  896. ```bash
  897. echo -e "api\nauth\ndatabase" | workmux add refactor -P task.md
  898. # {{ input }} = "api", "auth", "database"
  899. ```
  900. **JSON lines:** Each key becomes a template variable
  901. ```bash
  902. gh repo list --json url,name --jq -c '.[]' | workmux add analyze \
  903. --branch-template '{{ base_name }}-{{ name }}' \
  904. -P prompt.md
  905. # Line: {"url":"https://github.com/raine/workmux","name":"workmux"}
  906. # Variables: {{ url }}, {{ name }}, {{ input }} (raw JSON line)
  907. ```
  908. This lets you structure data upstream with `jq` and use meaningful branch names
  909. while keeping the full URL available in your prompt.
  910. **Behavior:**
  911. - Empty lines and whitespace-only lines are filtered out
  912. - Stdin input cannot be combined with `--foreach` (mutually exclusive)
  913. - JSON objects (lines starting with `{`) are parsed and each key becomes a
  914. variable
  915. - `{{ input }}` always contains the raw line
  916. - If JSON contains an `input` key, it overwrites the raw line value
  917. ##### Examples
  918. ```bash
  919. # Create one worktree for claude and one for gemini with a focused prompt
  920. workmux add my-feature -a claude -a gemini -p "Implement the new search API integration"
  921. # Generates worktrees: my-feature-claude, my-feature-gemini
  922. # Create 2 instances of the default agent
  923. workmux add my-feature -n 2 -p "Implement task #{{ num }} in TASKS.md"
  924. # Generates worktrees: my-feature-1, my-feature-2
  925. # Create worktrees from a variable matrix
  926. workmux add my-feature --foreach "platform:iOS,Android" -p "Build for {{ platform }}"
  927. # Generates worktrees: my-feature-ios, my-feature-android
  928. # Create agent-specific worktrees via --foreach
  929. workmux add my-feature --foreach "agent:claude,gemini" -p "Implement the dashboard refactor"
  930. # Generates worktrees: my-feature-claude, my-feature-gemini
  931. # Use frontmatter in a prompt file for cleaner syntax
  932. # task.md contains:
  933. # ---
  934. # foreach:
  935. # env: [staging, production]
  936. # task: [smoke-tests, integration-tests]
  937. # ---
  938. # Run {{ task }} against the {{ env }} environment
  939. workmux add testing --prompt-file task.md
  940. # Generates worktrees: testing-staging-smoke-tests, testing-production-integration-tests
  941. # Pipe input from stdin to create worktrees
  942. # review.md contains: Review the {{ input }} module for security issues.
  943. echo -e "auth\npayments\napi" | workmux add review -A -P review.md
  944. # Generates worktrees with LLM-generated branch names for each module
  945. ```
  946. ##### Recipe: Batch processing with worker pools
  947. Combine stdin input, prompt templating, and concurrency limits to create a
  948. worker pool that processes items from an external command.
  949. **Example: Generate test scaffolding for untested files**
  950. ```bash
  951. # generate-tests.md contains:
  952. # Read the file at {{ input }} and generate a test suite covering
  953. # the exported functions. Focus on happy path and edge cases.
  954. # When done, run: workmux remove --keep-branch
  955. find src/utils -name "*.ts" ! -name "*.test.ts" | \
  956. workmux add add-tests \
  957. --branch-template '{{ base_name }}-{{ index }}' \
  958. --prompt-file generate-tests.md \
  959. --max-concurrent 3 \
  960. --background
  961. ```
  962. - `find ...` lists files without tests (one per line) piped to stdin
  963. - `--branch-template` uses `{{ index }}` for unique branch names
  964. - `--prompt-file` uses `{{ input }}` to pass each file path to the agent
  965. - `--max-concurrent 3` limits parallel agents to avoid rate limits
  966. - `--background` runs without switching focus
  967. ---
  968. ### `workmux merge [branch-name]`
  969. Merges a branch into a target branch (main by default) and automatically cleans
  970. up all associated resources (worktree, tmux window, and local branch).
  971. <!-- prettier-ignore -->
  972. > [!TIP]
  973. > **`merge` vs `remove`**: Use `merge` when you want to merge directly
  974. > without a pull request. If your workflow uses pull requests, use
  975. > [`remove`](#workmux-remove-name-alias-rm) to clean up after your PR is merged
  976. > on the remote.
  977. - `[branch-name]`: Optional name of the branch to merge. If omitted,
  978. automatically detects the current branch from the worktree you're in.
  979. #### Options
  980. - `--into <branch>`: Merge into the specified branch instead of the main branch.
  981. Useful for stacked PRs, git-flow workflows, or merging subtasks into a parent
  982. feature branch. If the target branch has its own worktree, the merge happens
  983. there; otherwise, the main worktree is used.
  984. - `--ignore-uncommitted`: Commit any staged changes before merging without
  985. opening an editor
  986. - `--keep`, `-k`: Keep the worktree, window, and branch after merging (skip
  987. cleanup). Useful when you want to verify the merge before cleaning up.
  988. - `--cleanup`: Clean up after merging, overriding `merge_keep: true`.
  989. - `--notification`: Show a system notification on successful merge. Useful when
  990. delegating merge to an AI agent and you want to be notified when it completes.
  991. #### Merge strategies
  992. By default, `workmux merge` performs a standard merge commit (configurable via
  993. `merge_strategy`). You can override the configured behavior with these mutually
  994. exclusive flags:
  995. - `--rebase`: Rebase the feature branch onto the target before merging (creates
  996. a linear history via fast-forward merge). If conflicts occur, you'll need to
  997. resolve them manually in the worktree and run `git rebase --continue`.
  998. - `--squash`: Squash all commits from the feature branch into a single commit on
  999. the target. You'll be prompted to provide a commit message in your editor.
  1000. If you don't want to have merge commits in your main branch, use the `rebase`
  1001. merge strategy, which does `--rebase` by default.
  1002. ```yaml
  1003. # ~/.config/workmux/config.yaml
  1004. merge_strategy: rebase
  1005. ```
  1006. To keep the worktree, window, and branch after every merge unless overridden,
  1007. set:
  1008. ```yaml
  1009. merge_keep: true
  1010. ```
  1011. Use `workmux merge --cleanup` to clean up for a single merge when this default is
  1012. enabled.
  1013. #### What happens
  1014. 1. Determines which branch to merge (specified branch or current branch if
  1015. omitted)
  1016. 2. Determines the target branch (`--into` or main branch from config)
  1017. 3. Checks for uncommitted changes (errors if found, unless
  1018. `--ignore-uncommitted` is used)
  1019. 4. Commits staged changes if present (unless `--ignore-uncommitted` is used)
  1020. 5. Merges your branch into the target using the selected strategy (default:
  1021. merge commit)
  1022. 6. Deletes the tmux window unless keep behavior is enabled via `--keep` or
  1023. `merge_keep: true`
  1024. 7. Removes the worktree unless keep behavior is enabled via `--keep` or
  1025. `merge_keep: true`
  1026. 8. Deletes the local branch unless keep behavior is enabled via `--keep` or
  1027. `merge_keep: true`
  1028. #### Typical workflow
  1029. When you're done working in a worktree, simply run `workmux merge` from within
  1030. that worktree's tmux window. The command will automatically detect which branch
  1031. you're on, merge it into main, and close the current window as part of cleanup.
  1032. #### Examples
  1033. ```bash
  1034. # Merge branch into main (default: merge commit)
  1035. workmux merge user-auth
  1036. # Merge the current worktree you're in
  1037. # (run this from within the worktree's tmux window)
  1038. workmux merge
  1039. # Rebase onto main before merging for a linear history
  1040. workmux merge user-auth --rebase
  1041. # Squash all commits into a single commit
  1042. workmux merge user-auth --squash
  1043. # Merge but keep the worktree/window/branch to verify before cleanup
  1044. workmux merge user-auth --keep
  1045. # ... verify the merge in main ...
  1046. workmux remove user-auth # clean up later when ready
  1047. # Merge into a different branch (stacked PRs)
  1048. workmux merge feature/subtask --into feature/parent
  1049. ```
  1050. ---
  1051. ### `workmux rebase [name]`
  1052. Rebases a worktree branch onto its saved base branch. If the branch does not have
  1053. a saved local base branch, workmux rebases onto the configured main branch.
  1054. - `[name]`: Optional worktree name or branch. If omitted, workmux detects the
  1055. current worktree from the current directory.
  1056. #### What happens
  1057. 1. Determines which worktree branch to rebase
  1058. 2. Reads the saved base branch recorded when the worktree was created
  1059. 3. Falls back to the configured main branch when the saved base is not a local branch
  1060. 4. Runs `git rebase <base>` inside the worktree
  1061. 5. Leaves the worktree, window, and branch in place
  1062. #### Examples
  1063. ```bash
  1064. workmux rebase user-auth
  1065. workmux rebase
  1066. ```
  1067. ---
  1068. ### `workmux remove [name]...` (alias: `rm`)
  1069. Removes worktrees, tmux windows, and branches without merging (unless you keep
  1070. the branches). Useful for abandoning work or cleaning up experimental branches.
  1071. Supports removing multiple worktrees in a single command.
  1072. - `[name]...`: One or more worktree names (the directory names). Defaults to
  1073. current directory name if omitted.
  1074. #### Options
  1075. - `--all`: Remove all worktrees at once (except the main worktree). Prompts for
  1076. confirmation unless `--force` is used. Safely skips worktrees with uncommitted
  1077. changes or unmerged commits.
  1078. - `--gone`: Remove worktrees whose upstream remote branch has been deleted
  1079. (e.g., after a PR is merged on GitHub). Automatically runs `git fetch --prune`
  1080. first.
  1081. - `--force`, `-f`: Skip confirmation prompt and ignore uncommitted changes
  1082. - `--keep-branch`, `-k`: Remove only the worktree and tmux window while keeping
  1083. the local branch
  1084. Set `confirm_unmerged_removal: false` to remove branches with unmerged commits
  1085. without an extra confirmation. Worktrees with uncommitted changes remain
  1086. protected and still require `--force`.
  1087. #### Examples
  1088. ```bash
  1089. # Remove the current worktree (run from within the worktree)
  1090. workmux remove
  1091. # Remove a specific worktree with confirmation if unmerged
  1092. workmux remove experiment
  1093. # Remove multiple worktrees at once
  1094. workmux rm feature-a feature-b feature-c
  1095. # Remove multiple worktrees with force (no confirmation)
  1096. workmux rm -f old-work stale-branch
  1097. # Use the alias
  1098. workmux rm old-work
  1099. # Remove worktree/window but keep the branch
  1100. workmux remove --keep-branch experiment
  1101. # Force remove without prompts
  1102. workmux rm -f experiment
  1103. # Remove worktrees whose remote branches were deleted (e.g., after PR merge)
  1104. workmux rm --gone
  1105. # Force remove all gone worktrees (no confirmation)
  1106. workmux rm --gone -f
  1107. # Remove all worktrees at once
  1108. workmux rm --all
  1109. ```
  1110. ---
  1111. ### `workmux rename [old-name] <new-name>`
  1112. Renames a worktree's directory, its tmux window or session, and the per-worktree
  1113. workmux metadata. Optionally also renames the underlying git branch.
  1114. - `[old-name]`: Optional current worktree name. Defaults to the current worktree
  1115. when run from inside one.
  1116. - `<new-name>`: The new handle (directory name and tmux window/session base name).
  1117. #### Options
  1118. - `--branch`, `-b`: Also rename the underlying git branch to match `<new-name>`.
  1119. Fails if the worktree is on a detached HEAD.
  1120. #### Examples
  1121. ```bash
  1122. # Rename a worktree from inside it
  1123. workmux rename feature-new
  1124. # Rename a specific worktree by name
  1125. workmux rename feature-old feature-new
  1126. # Also rename the branch to match
  1127. workmux rename feature-old feature-new --branch
  1128. ```
  1129. Rename is non-destructive: uncommitted changes and untracked files are
  1130. preserved. The main worktree cannot be renamed. Collisions (existing target
  1131. path, existing tmux target, or existing branch) are rejected before any changes
  1132. are made.
  1133. ---
  1134. ### `workmux list` (alias: `ls`)
  1135. Lists git worktrees with their agent status, multiplexer window status, and
  1136. merge status. Supports filtering by worktree handle or branch name.
  1137. #### Arguments
  1138. - `[worktree-or-branch...]`: Filter by worktree handle (directory name) or
  1139. branch name. Accepts multiple values. When omitted, shows all worktrees.
  1140. #### Options
  1141. - `--pr`: Show GitHub PR status for each worktree. Requires the `gh` CLI to be
  1142. installed and authenticated. Note that it shows pull requests' statuses with
  1143. [Nerd Font](https://www.nerdfonts.com/) icons, which requires Nerd Font
  1144. compatible font installed.
  1145. - `--all`: Include worktrees from every repository represented by a tracked
  1146. agent in the current multiplexer instance. Repositories without tracked agents
  1147. cannot be discovered.
  1148. - `--json`: Output as JSON. Produces a JSON array of objects with fields:
  1149. `project`, `project_path`, `handle`, `branch`, `path`, `is_main`, `mode`,
  1150. `has_uncommitted_changes`, `is_open`, `agent_statuses`, `created_at`.
  1151. #### Examples
  1152. ```bash
  1153. # List all worktrees
  1154. workmux list
  1155. # List with PR status
  1156. workmux list --pr
  1157. # Output as JSON for scripting
  1158. workmux list --json
  1159. # List tracked projects in one JSON response
  1160. workmux list --all --json
  1161. # Filter to specific worktrees
  1162. workmux list my-feature
  1163. workmux list feature-auth feature-api
  1164. ```
  1165. #### Example output
  1166. ```
  1167. BRANCH AGE AGENT MUX UNMERGED PATH
  1168. main - - - - ~/project
  1169. user-auth 2h 🤖 ✓ - ~/project__worktrees/user-auth
  1170. bug-fix 3d ✅ ✓ ● ~/project__worktrees/bug-fix
  1171. api-work 1w - ✓ - ~/project__worktrees/api-work
  1172. ```
  1173. #### Key
  1174. - AGE shows how old the worktree is (e.g., `2h`, `3d`, `1w`, `2mo`)
  1175. - AGENT shows the current agent status (see
  1176. [status tracking](https://workmux.dev/guide/status-tracking/)):
  1177. - `🤖` = working, `💬` = waiting for input, `✅` = finished
  1178. - Multiple agents per worktree show a count (e.g., `2🤖 1✅`)
  1179. - `✓` in MUX column = multiplexer window exists for this worktree
  1180. - `●` in UNMERGED column = branch has commits not merged into main
  1181. - `-` = not applicable
  1182. ---
  1183. ### `workmux status [worktree...]`
  1184. Queries tracked agents in the current repository or in explicitly requested
  1185. worktrees. Use `project:handle` to target a worktree in another project.
  1186. - `--all`: Include tracked agents across every repository in the current
  1187. multiplexer instance. This option conflicts with explicit worktree targets.
  1188. - `--json`: Emit an observation object containing the selected multiplexer
  1189. context, repository and target scope, state-file counts, the reconciled agent
  1190. count before scope filtering, and the scoped `agents` array. Agent entries
  1191. include `project` and `project_path` when their Git repository can be resolved.
  1192. - `--git`: Include staged, unstaged, and unmerged commit information.
  1193. Automation must check the command exit status before interpreting an empty
  1194. `agents` array. See the
  1195. [`status` command reference](https://workmux.dev/reference/commands/status/) for
  1196. the JSON contract and fail-closed rules.
  1197. ---
  1198. ### `workmux config edit`
  1199. Opens the global configuration file (`~/.config/workmux/config.yaml`) in your
  1200. preferred editor. Uses `$VISUAL`, `$EDITOR`, or falls back to `vi`. Creates the
  1201. file with commented-out defaults if it doesn't exist yet.
  1202. ---
  1203. ### `workmux config path`
  1204. Prints the path to the global configuration file. Useful for scripting.
  1205. ---
  1206. ### `workmux config reference`
  1207. Prints the default configuration file with all options documented. Useful for
  1208. discovering available options or piping to an AI agent for context.
  1209. ---
  1210. ### `workmux init`
  1211. Generates `.workmux.yaml` with example configuration and `"<global>"`
  1212. placeholder usage.
  1213. ---
  1214. ### `workmux open [name...]`
  1215. Opens or switches to a tmux window for a pre-existing git worktree. If the
  1216. window already exists, switches to it. If not, creates a new window with the
  1217. configured pane layout and environment. Accepts multiple names to open several
  1218. worktrees at once.
  1219. - `[name...]`: One or more worktree names (the directory name, which is also the
  1220. tmux window name without the prefix). Optional with `--new` when run from
  1221. inside a worktree.
  1222. #### Options
  1223. - `-n, --new`: Force opening in a new window even if one already exists. Creates
  1224. a duplicate window with a suffix (e.g., `-2`, `-3`). Useful for having
  1225. multiple terminal views into the same worktree. In tmux, the duplicate appears
  1226. immediately to the right of the window identified by `$TMUX_PANE`.
  1227. - `-s, --session`: Open in session mode, overriding the stored mode. Persists
  1228. the mode change for subsequent opens. Cannot be combined with `--new`. Only
  1229. supported with tmux.
  1230. - `--config <path>`: Use an alternate config file for this invocation. Still
  1231. merges with global config.
  1232. - `--run-hooks`: Re-runs the `post_create` commands (these block window
  1233. creation).
  1234. - `--force-files`: Re-applies file copy/symlink operations. Useful for restoring
  1235. a deleted `.env` file.
  1236. - `-p, --prompt <text>`: Provide an inline prompt for AI agent panes.
  1237. - `-P, --prompt-file <path>`: Provide a path to a file containing the prompt.
  1238. - `-c, --continue`: Resume the agent's most recent conversation in this
  1239. worktree. Injects the appropriate flag for the configured agent (e.g.,
  1240. `--continue` for Claude, `--resume` for Gemini).
  1241. - `-e, --prompt-editor`: Open your editor to write the prompt interactively.
  1242. - `--prompt-file-only`: Write the prompt file without injecting it into agent
  1243. commands.
  1244. #### What happens
  1245. 1. Verifies that a worktree with `<name>` exists.
  1246. 2. If a tmux window exists and `--new` is not set, switches to it.
  1247. 3. Otherwise, creates a new tmux window (with suffix if duplicating). In tmux,
  1248. duplicate windows appear immediately to the right of the window where the
  1249. command runs.
  1250. 4. (If specified) Runs file operations and `post_create` hooks.
  1251. 5. Sets up your configured tmux pane layout.
  1252. 6. Automatically switches your tmux client to the new window.
  1253. #### Examples
  1254. ```bash
  1255. # Open or switch to a window for an existing worktree
  1256. workmux open user-auth
  1257. # Force open a second window for the same worktree (creates user-auth-2)
  1258. workmux open user-auth --new
  1259. # Open a new window for the current worktree (run from within the worktree)
  1260. workmux open --new
  1261. # Open in session mode (converts from window mode if needed)
  1262. workmux open user-auth --session
  1263. # Resume the agent's last conversation
  1264. workmux open user-auth --continue
  1265. # Resume and send a follow-up prompt
  1266. workmux open user-auth --continue -p "Continue implementing the login flow"
  1267. # Open and re-run dependency installation
  1268. workmux open user-auth --run-hooks
  1269. # Open and restore configuration files
  1270. workmux open user-auth --force-files
  1271. # Open multiple worktrees at once
  1272. workmux open user-auth api-refactor bugfix-login
  1273. ```
  1274. ---
  1275. ### `workmux close [name]`
  1276. Closes the tmux window for a worktree without removing the worktree or branch.
  1277. This is useful when you want to temporarily close a window to reduce clutter or
  1278. free resources, but plan to return to the work later.
  1279. - `[name]`: Optional worktree name (the directory name). Defaults to current
  1280. directory if omitted.
  1281. #### Examples
  1282. ```bash
  1283. # Close the window for a specific worktree
  1284. workmux close user-auth
  1285. # Close the current worktree's window (run from within the worktree)
  1286. workmux close
  1287. ```
  1288. To reopen the window later, use [`workmux open`](#workmux-open-name).
  1289. **Tip**: You can also use tmux's native kill-window command (default:
  1290. `prefix + &`) to close a worktree's window with the same effect.
  1291. ---
  1292. ### `workmux resurrect`
  1293. Restores worktree windows after a tmux or computer crash. Uses persisted agent
  1294. state files to detect which worktrees had active agents before the crash, then
  1295. reopens them with `--continue` to resume agent conversations.
  1296. #### Options
  1297. - `--dry-run`: Show what would be restored without doing it.
  1298. #### Examples
  1299. ```bash
  1300. # See what would be restored after a crash
  1301. workmux resurrect --dry-run
  1302. # Restore all worktrees that had agents running
  1303. workmux resurrect
  1304. ```
  1305. #### How it works
  1306. 1. Reads agent state files from `~/.local/state/workmux/agents/`
  1307. 2. Matches each state file's working directory to a git worktree in the current
  1308. repo
  1309. 3. Skips worktrees that are already open or no longer exist
  1310. 4. Opens each matched worktree with `--continue` to resume the agent
  1311. Agent state from known earlier multiplexer boots is compacted to one recovery
  1312. candidate per exact working directory. This keeps repeated server restarts from
  1313. accumulating duplicate recovery history while retaining unrestored worktrees
  1314. across any number of restarts. Current-boot records, records without a reliable
  1315. boot identity, malformed files, and state owned by another multiplexer instance
  1316. or backend are preserved. Each instance compacts its own history when workmux
  1317. observes that instance with a reliable boot identity.
  1318. ---
  1319. ### `workmux sync-files`
  1320. Re-applies file operations (copy and symlink from `files` config) to existing
  1321. worktrees. Useful when you add new entries to the `files` config or a symlink
  1322. was accidentally deleted.
  1323. #### Options
  1324. - `--all`: Sync all worktrees instead of just the current one.
  1325. #### Examples
  1326. ```bash
  1327. # Sync files to the current worktree
  1328. workmux sync-files
  1329. # Sync files to all worktrees
  1330. workmux sync-files --all
  1331. ```
  1332. ---
  1333. ### `workmux path <name>`
  1334. Prints the filesystem path of an existing worktree. Useful for scripting or
  1335. quickly navigating to a worktree directory.
  1336. - `<name>`: Worktree name (the directory name).
  1337. #### Examples
  1338. ```bash
  1339. # Get the path of a worktree
  1340. workmux path user-auth
  1341. # Output: /Users/you/project__worktrees/user-auth
  1342. # Use in scripts or with cd
  1343. cd "$(workmux path user-auth)"
  1344. # Copy a file to a worktree
  1345. cp config.json "$(workmux path feature-branch)/"
  1346. ```
  1347. ---
  1348. ### `workmux dashboard`
  1349. Opens a TUI dashboard showing all active AI agents across all tmux sessions.
  1350. Useful for monitoring multiple parallel agents and quickly jumping between them.
  1351. #### Options
  1352. - `-d, --diff`: Open the diff view directly for the current worktree. Useful
  1353. when you want to quickly review uncommitted changes without navigating through
  1354. the agent list.
  1355. - `-P, --preview-size <10-90>`: Set preview pane size as percentage (larger =
  1356. more preview, less table). Default: 60.
  1357. - `-s, --session`: Filter to only show agents in the current session. Useful for
  1358. session-per-project workflows where each session maps to a different
  1359. repository.
  1360. - `-t, --tab <agents|worktrees>`: Open directly on the specified tab.
  1361. <!-- prettier-ignore -->
  1362. > [!IMPORTANT]
  1363. > This feature requires [agent status tracking](#agent-status-tracking) to be
  1364. > configured. Without it, no agents will appear in the dashboard.
  1365. ![workmux dashboard](https://raw.githubusercontent.com/raine/workmux/refs/heads/main/meta/dashboard.webp)
  1366. #### Keybindings
  1367. | Key | Action |
  1368. | --------- | --------------------------------------- |
  1369. | `1`-`9` | Quick jump to agent (closes dashboard) |
  1370. | `Tab` | Toggle between current and last agent |
  1371. | `d` | View diff (opens WIP view) |
  1372. | `o` | Open PR in browser |
  1373. | `p` | Peek at agent (dashboard stays open) |
  1374. | `s` | Cycle sort mode |
  1375. | `/` | Filter agents by name |
  1376. | `F` | Toggle session filter |
  1377. | `f` | Toggle stale filter (show/hide stale) |
  1378. | `i` | Enter input mode (type to agent) |
  1379. | `Ctrl+u` | Scroll preview up |
  1380. | `Ctrl+d` | Scroll preview down |
  1381. | `+`/`-` | Resize preview pane |
  1382. | `Enter` | Go to selected agent (closes dashboard) |
  1383. | `j`/`k` | Navigate up/down |
  1384. | `:` | Open command palette |
  1385. | `q` | Quit |
  1386. #### Mouse controls
  1387. The dashboard captures mouse input while it is open. Click the **Agents** and
  1388. **Worktrees** tabs to switch views, click a table row to select it, and
  1389. double-click a row to jump to its agent or worktree. Right-click a row to open
  1390. its action menu, then click an action or use `j`/`k` and `Enter`. Click a footer
  1391. command to run it. Use the mouse wheel over a table to change the selection
  1392. without wrapping, or over the live preview to scroll its output.
  1393. In diff view, use the wheel to scroll and click a file in the sidebar to jump to
  1394. its diff. Visible diff and patch footer commands are clickable. Mouse capture is
  1395. released when the dashboard exits.
  1396. #### Live preview
  1397. The bottom half shows a live preview of the selected agent's terminal output.
  1398. The preview auto-scrolls to show the latest output, but you can scroll through
  1399. history with `Ctrl+u`/`Ctrl+d`. Press `i` to enter input mode and type directly
  1400. to the agent without leaving the dashboard.
  1401. #### Columns
  1402. - **#**: Quick jump key (1-9)
  1403. - **Project**: Project name (from `__worktrees` path or directory name)
  1404. - **Agent**: Worktree/window name
  1405. - **Git**: Diff stats showing branch changes (dim) and uncommitted changes
  1406. (bright). Shows a rebase icon when a rebase is in progress.
  1407. - **Status**: Agent status icon (🤖 working, 💬 waiting, ✅ done, or "stale")
  1408. - **Time**: Time since last status change
  1409. - **Title**: Claude Code session title (auto-generated summary)
  1410. #### Sort modes
  1411. Press `s` to cycle through sort modes:
  1412. - **Priority** (default): Waiting > Done > Working > Stale
  1413. - **Project**: Group by project name, then by priority within each project
  1414. - **Recency**: Most recently updated first
  1415. - **Natural**: Original tmux order (by pane creation)
  1416. Your sort preference persists in the tmux session.
  1417. #### Session filter
  1418. Press `F` to toggle the session filter. When active, only agents in the current
  1419. session are shown. This is useful for session-per-project workflows where each
  1420. session maps to a repository. You can also start the dashboard with `--session`
  1421. to default to session filtering. The preference persists across sessions.
  1422. #### Name filter
  1423. Press `/` to activate the name filter. Type to filter the agent list by project
  1424. or worktree name (case-insensitive). Press `Enter` to accept the filter and
  1425. return to normal navigation, or `Esc` to clear the filter. When a filter is
  1426. active, it is shown in the footer bar.
  1427. #### Stale filter
  1428. Press `f` to toggle between showing all agents or hiding stale ones. The filter
  1429. state persists across dashboard sessions within the same tmux server.
  1430. #### Diff view
  1431. Press `d` to view the diff for the selected agent. The diff view has two modes:
  1432. - **WIP** - Shows uncommitted changes (`git diff HEAD`)
  1433. - **review** - Shows all changes on the branch vs main (`git diff main...HEAD`)
  1434. Press `Tab` to toggle between modes. The footer displays which mode is active
  1435. along with diff statistics showing lines added (+) and removed (-).
  1436. | Key | Action |
  1437. | --------- | -------------------------------- |
  1438. | `Tab` | Toggle WIP / review |
  1439. | `a` | Enter patch mode (WIP only) |
  1440. | `j`/`k` | Scroll down/up |
  1441. | `Ctrl+d` | Page down |
  1442. | `Ctrl+u` | Page up |
  1443. | `c` | Send commit command to agent |
  1444. | `m` | Trigger merge and exit dashboard |
  1445. | `:` | Open command palette |
  1446. | `q`/`Esc` | Close diff view |
  1447. #### Patch mode
  1448. Patch mode (`a` from WIP diff) allows staging individual hunks like
  1449. `git add -p`. This is useful for selectively staging parts of an agent's work.
  1450. When [delta](https://github.com/dandavison/delta) is installed, hunks are
  1451. rendered with syntax highlighting for better readability.
  1452. | Key | Action |
  1453. | --------- | -------------------------------- |
  1454. | `y` | Stage current hunk |
  1455. | `n` | Skip current hunk |
  1456. | `u` | Undo last staged hunk |
  1457. | `s` | Split hunk (if splittable) |
  1458. | `o` | Comment on hunk (sends to agent) |
  1459. | `j`/`k` | Navigate to next/previous hunk |
  1460. | `:` | Open command palette |
  1461. | `q`/`Esc` | Exit patch mode |
  1462. Press `y` to stage the current hunk and advance to the next. Press `n` to skip
  1463. without staging. The counter in the header shows your progress (e.g., `[3/10]`).
  1464. Press `s` to split the current hunk into smaller pieces when there are context
  1465. lines between separate changes. Press `u` to undo the last staged hunk.
  1466. Press `o` to comment on the current hunk. This sends a message to the agent
  1467. including the file path, line number, the diff hunk as context, and your
  1468. comment. Useful for giving feedback like "This function should handle the error
  1469. case".
  1470. #### Example tmux binding
  1471. Add to your `~/.tmux.conf` for quick access:
  1472. ```bash
  1473. bind C-s display-popup -h 30 -w 100 -E "workmux dashboard"
  1474. # Open directly on Worktrees tab
  1475. bind C-w display-popup -h 30 -w 100 -E "workmux dashboard --tab worktrees"
  1476. ```
  1477. Then press `prefix + Ctrl-s` to open the dashboard as a tmux popup.
  1478. ---
  1479. ### `workmux sidebar`
  1480. Toggles a live agent status sidebar on the left or top edge of tmux windows or
  1481. Zellij tabs. tmux can show agents across sessions; Zellij is scoped to the
  1482. current session. The sidebar provides an always-visible overview without taking
  1483. over the full screen like the dashboard.
  1484. ```bash
  1485. workmux sidebar # Toggle sidebar on/off (all sessions)
  1486. workmux sidebar on # Ensure the global sidebar is running
  1487. workmux sidebar off # Ensure the global sidebar is stopped
  1488. workmux sidebar --session on # Ensure it is running in this session
  1489. workmux sidebar --session off # Ensure it is stopped in this session
  1490. workmux sidebar on --position top # Enable with a top sidebar
  1491. ```
  1492. The sidebar displays:
  1493. - Status icon (working/waiting/done with spinner animation)
  1494. - Project and worktree name (e.g. `myproject/fix-bug`)
  1495. - Elapsed time since last status change
  1496. | Key | Action |
  1497. | ------- | ---------------------- |
  1498. | `j`/`k` | Navigate up/down |
  1499. | `Enter` | Run configured action |
  1500. | `o` | Focus the agent pane |
  1501. | `g`/`G` | Jump to first/last |
  1502. | `v` | Toggle layout mode |
  1503. | `f` | Toggle session filter |
  1504. | `q` | Open quit confirmation |
  1505. With tmux mouse mode enabled (`set -g mouse on`), click an agent row or top-bar
  1506. chip to jump to its pane, or scroll to navigate the list.
  1507. When the global sidebar is active, `workmux sidebar --session` hides it in the
  1508. current tmux session only. Run the same command again to show it in that session
  1509. again while keeping the global sidebar active elsewhere.
  1510. Configure placement, width, and layout in `.workmux.yaml`:
  1511. ```yaml
  1512. sidebar:
  1513. position: left # "left" (default) or "top"
  1514. width: 40 # left width in columns, or "15%" for percentage
  1515. layout: tiles # left only: "compact" or "tiles" (default)
  1516. enter_action: focus # "focus" (default) or "select"
  1517. ```
  1518. Set `enter_action: select` to show an agent's window while keeping focus in its
  1519. sidebar. Press `o` to focus the selected agent pane.
  1520. The left sidebar defaults to 10% of terminal width, clamped between 25 and 50
  1521. columns. Widths above 80 columns use the default width so tmux pane expansion
  1522. recovers automatically.
  1523. Use `workmux sidebar on --position top` or `--position left` to override the
  1524. configured placement when enabling the sidebar. The `on` action also accepts
  1525. `--width` and `--height`. The `off` action rejects appearance flags because they
  1526. have no effect while stopping the sidebar.
  1527. #### Example tmux binding
  1528. ```bash

Lines 2,001–2,963 are not shown. The link to the file on GitHub has every line.

docs/src/components/landing/data.ts · Bundled script · 135 lines · 1 finding marked
  1. import { getEntry } from "astro:content";
  2. import { getGitHubStars } from "./stars";
  3. export const starsPromise = getGitHubStars();
  4. // The release pill reads CHANGELOG.md (the docs changelog page). A release can
  5. // name its headline feature with a `<!-- highlight: ... -->` comment under its
  6. // heading; the pill shows the newest release that has one, or the newest
  7. // release with a generic label when none does.
  8. async function latestRelease() {
  9. const body = (await getEntry("docs", "changelog"))?.body ?? "";
  10. const releases = body
  11. .split(/^## /m)
  12. .slice(1)
  13. .map((s) => ({
  14. version: s.match(/^v[\d.]+/)?.[0],
  15. highlight: s.match(/<!--\s*highlight:\s*(.+?)\s*-->/)?.[1],
  16. }))
  17. .filter(
  18. (r): r is { version: string; highlight: string | undefined } =>
  19. !!r.version,
  20. );
  21. const featured = releases.find((r) => r.highlight);
  22. return featured
  23. ? { version: featured.version, latest: featured.highlight! }
  24. : { version: releases[0]?.version ?? "", latest: "What’s new" };
  25. }
  26. export const { version, latest } = await latestRelease();
  27. export const install = [
  28. {
  29. id: "curl",
  30. label: "curl",
  31. cmd: "curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 35 on GitHub
  32. },
  33. { id: "brew", label: "Homebrew", cmd: "brew install raine/workmux/workmux" },
  34. { id: "cargo", label: "Cargo", cmd: "cargo install workmux" },
  35. ];
  36. export const testimonials = [
  37. {
  38. quote:
  39. "It's become my daily driver - the perfect level of abstraction over tmux + git, without getting in the way or obscuring the underlying tooling.",
  40. author: "@cisaacstern",
  41. source: "GitHub",
  42. href: "https://github.com/raine/workmux/issues/33",
  43. },
  44. {
  45. quote:
  46. "workmux is fantastic. nothing too fancy, solves a real problem and stays in TMUX ❤️",
  47. author: "@devopstoolbox",
  48. source: "X",
  49. href: "https://x.com/devopstoolbox/status/2094442083717390547",
  50. },
  51. {
  52. quote:
  53. "I have to mention workmux at every opportunity because it's the perfect glue between worktrees, agents and tmux windows.",
  54. author: "@dedbrizz",
  55. source: "Threads",
  56. href: "https://www.threads.com/@dedbrizz/post/DVt1DtLkr_l",
  57. },
  58. {
  59. quote:
  60. "Since I discovered workmux I'm cooking. Amazing parallel-agent driver if you like tmux and want to keep your config.",
  61. author: "@MatijaSosic",
  62. source: "X",
  63. href: "https://x.com/MatijaSosic/status/2080022087281127659",
  64. },
  65. {
  66. quote:
  67. "Thank you so much for your work with workmux! It's a tool I've been wanting to exist for a long time.",
  68. author: "@rstacruz",
  69. source: "GitHub",
  70. href: "https://github.com/raine/workmux/issues/2",
  71. },
  72. {
  73. quote:
  74. "I've been using (and loving) workmux which brings together tmux, git worktrees, and CLI agents into an opinionated workflow.",
  75. author: "@Coolin96",
  76. source: "Hacker News",
  77. href: "https://news.ycombinator.com/item?id=46029809",
  78. },
  79. ];
  80. export const workflows = [
  81. {
  82. id: "solo",
  83. name: "Solo",
  84. command: 'workmux add -A -p "Add cursor-based pagination to /api/users"',
  85. href: "/reference/commands/add/",
  86. link: "workmux add",
  87. kind: "Command",
  88. prompt: "$",
  89. body: "One command creates a branch, worktree, and starts an agent with your prompt in a new window.",
  90. },
  91. {
  92. id: "delegated",
  93. name: "Delegated",
  94. command: "/worktree Implement the caching layer",
  95. href: "/guide/skills/#worktree",
  96. link: "/worktree",
  97. kind: "Skill",
  98. prompt: "❯",
  99. body: "From inside an agent, spin off a subtask to a new worktree with full context.",
  100. },
  101. {
  102. id: "coordinated",
  103. name: "Coordinated",
  104. command: "/coordinator Break down the auth refactor into parallel tasks",
  105. href: "/guide/skills/#coordinator",
  106. link: "/coordinator",
  107. kind: "Skill",
  108. prompt: "❯",
  109. body: "One agent spawns, monitors, and merges multiple worktree agents.",
  110. },
  111. ];
  112. export const videos = [
  113. {
  114. title: "Tmux is Still Better Than Herdr (Here’s Why)",
  115. author: "Sam Natale",
  116. href: "https://www.youtube.com/watch?v=ww1wykxJps8",
  117. },
  118. {
  119. title: "I Don’t Want a New Terminal. I Want THIS for Tmux.",
  120. author: "DevOps Toolbox",
  121. href: "https://www.youtube.com/watch?v=7uumknh43rM",
  122. },
  123. {
  124. title: "Tmux Didn’t Need a Replacement, It Needed Workmux",
  125. author: "Seth Phaeno",
  126. href: "https://www.youtube.com/watch?v=0RGyt3EDP-E",
  127. },
  128. ];
scripts/install.sh · Bundled script · 360 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. #
  3. # workmux installation script
  4. # Usage: curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 4 on GitHub
  5. #
  6. # Environment variables:
  7. # WORKMUX_VERSION - Pin a specific version (e.g., v0.1.96)
  8. # WORKMUX_INSTALL_DIR - Override install directory (default: /usr/local/bin or ~/.local/bin)
  9. #
  10. # Examples:
  11. # WORKMUX_VERSION=v0.1.96 bash install.sh
  12. # WORKMUX_INSTALL_DIR=/opt/bin bash install.sh
  13. #
  14. # ⚠️ IMPORTANT: This script must be EXECUTED, never SOURCED
  15. # ❌ WRONG: source install.sh (will exit your shell on errors)
  16. # ✅ CORRECT: bash install.sh
  17. # ✅ CORRECT: curl -fsSL ... | bash
  18. #
  19. set -e
  20. # Colors
  21. RED='\033[0;31m'
  22. GREEN='\033[0;32m'
  23. YELLOW='\033[1;33m'
  24. BLUE='\033[0;34m'
  25. NC='\033[0m' # No Color
  26. log_info() {
  27. echo -e "${BLUE}==>${NC} $1"
  28. }
  29. log_success() {
  30. echo -e "${GREEN}==>${NC} $1"
  31. }
  32. log_warning() {
  33. echo -e "${YELLOW}==>${NC} $1"
  34. }
  35. log_error() {
  36. echo -e "${RED}Error:${NC} $1" >&2
  37. }
  38. # Detect OS and architecture
  39. detect_platform() {
  40. local os arch
  41. case "$(uname -s)" in
  42. Darwin)
  43. os="darwin"
  44. ;;
  45. Linux)
  46. os="linux"
  47. ;;
  48. *)
  49. log_error "Unsupported operating system: $(uname -s)"
  50. echo ""
  51. echo "workmux supports macOS and Linux."
  52. echo "For other platforms, try building from source with Cargo:"
  53. echo " cargo install workmux"
  54. echo ""
  55. exit 1
  56. ;;
  57. esac
  58. case "$(uname -m)" in
  59. x86_64 | amd64)
  60. arch="amd64"
  61. ;;
  62. aarch64 | arm64)
  63. arch="arm64"
  64. ;;
  65. *)
  66. log_error "Unsupported architecture: $(uname -m)"
  67. echo ""
  68. echo "workmux prebuilt binaries are available for amd64 and arm64."
  69. echo "For other architectures, try building from source with Cargo:"
  70. echo " cargo install workmux"
  71. echo ""
  72. exit 1
  73. ;;
  74. esac
  75. echo "${os}-${arch}"
  76. }
  77. # Check required dependencies
  78. check_dependencies() {
  79. local missing=()
  80. if ! command -v git &>/dev/null; then
  81. missing+=("git")
  82. fi
  83. if ! command -v tmux &>/dev/null; then
  84. missing+=("tmux")
  85. fi
  86. if [ ${#missing[@]} -gt 0 ]; then
  87. log_warning "Missing required dependencies: ${missing[*]}"
  88. echo ""
  89. echo "workmux requires git and tmux to function."
  90. echo "Please install them first:"
  91. echo " - macOS: brew install git tmux"
  92. echo " - Ubuntu/Debian: sudo apt install git tmux"
  93. echo " - Other Linux: Use your distro's package manager"
  94. echo ""
  95. echo "Installation will continue, but workmux won't work until dependencies are installed."
  96. echo ""
  97. fi
  98. }
  99. # Download and install from GitHub releases
  100. install_from_release() {
  101. log_info "Installing workmux from GitHub releases..."
  102. local platform=$1
  103. local tmp_dir
  104. tmp_dir=$(mktemp -d)
  105. trap 'rm -rf "$tmp_dir"' EXIT
  106. # Get latest release version (or use override)
  107. local version="${WORKMUX_VERSION:-}"
  108. if [ -z "$version" ]; then
  109. log_info "Fetching latest release..."
  110. local latest_url="https://api.github.com/repos/raine/workmux/releases/latest"
  111. local release_json
  112. if command -v curl &>/dev/null; then
  113. release_json=$(curl -fsSL --retry 3 --retry-connrefused --connect-timeout 10 --max-time 30 "$latest_url")
  114. elif command -v wget &>/dev/null; then
  115. release_json=$(wget --tries=3 --timeout=30 -qO- "$latest_url")
  116. else
  117. log_error "Neither curl nor wget found. Please install one of them."
  118. exit 1
  119. fi
  120. version=$(echo "$release_json" | grep '"tag_name"' | sed -E 's/.*"tag_name": "([^"]+)".*/\1/')
  121. if [ -z "$version" ]; then
  122. log_error "Failed to fetch latest version"
  123. echo ""
  124. echo "This might be due to network issues or GitHub API rate limits."
  125. echo "You can specify a version manually:"
  126. echo " WORKMUX_VERSION=v0.1.96 bash install.sh"
  127. echo ""
  128. exit 1
  129. fi
  130. fi
  131. log_info "Installing version: $version"
  132. # Download URL
  133. local archive_name="workmux-${platform}.tar.gz"
  134. local download_url="https://github.com/raine/workmux/releases/download/${version}/${archive_name}"
  135. log_info "Downloading $archive_name..."
  136. cd "$tmp_dir"
  137. if command -v curl &>/dev/null; then
  138. if ! curl -fsSL --retry 3 --retry-connrefused --connect-timeout 10 --max-time 120 -o "$archive_name" "$download_url"; then
  139. log_error "Download failed"
  140. echo ""
  141. echo "The release may not have a prebuilt binary for your platform."
  142. echo "Try installing with Cargo instead:"
  143. echo " cargo install workmux"
  144. echo ""
  145. cd - >/dev/null || cd "$HOME"
  146. exit 1
  147. fi
  148. elif command -v wget &>/dev/null; then
  149. if ! wget --tries=3 --timeout=120 -q -O "$archive_name" "$download_url"; then
  150. log_error "Download failed"
  151. echo ""
  152. echo "The release may not have a prebuilt binary for your platform."
  153. echo "Try installing with Cargo instead:"
  154. echo " cargo install workmux"
  155. echo ""
  156. cd - >/dev/null || cd "$HOME"
  157. exit 1
  158. fi
  159. fi
  160. # Download and verify checksum
  161. log_info "Verifying checksum..."
  162. local checksum_file="${archive_name%.tar.gz}.sha256"
  163. local checksum_url="https://github.com/raine/workmux/releases/download/${version}/${checksum_file}"
  164. if command -v curl &>/dev/null; then
  165. if ! curl -fsSL --retry 3 --retry-connrefused --connect-timeout 10 --max-time 30 -o "$checksum_file" "$checksum_url"; then
  166. log_error "Failed to download checksum file"
  167. cd - >/dev/null || cd "$HOME"
  168. exit 1
  169. fi
  170. elif command -v wget &>/dev/null; then
  171. if ! wget --tries=3 --timeout=30 -q -O "$checksum_file" "$checksum_url"; then
  172. log_error "Failed to download checksum file"
  173. cd - >/dev/null || cd "$HOME"
  174. exit 1
  175. fi
  176. fi
  177. # Verify checksum using sha256sum (Linux) or shasum (macOS)
  178. if command -v sha256sum &>/dev/null; then
  179. if ! sha256sum -c "$checksum_file" &>/dev/null; then
  180. log_error "Checksum verification failed"
  181. echo ""
  182. echo "The downloaded file may be corrupted or tampered with."
  183. echo "Please try again or report this issue."
  184. echo ""
  185. cd - >/dev/null || cd "$HOME"
  186. exit 1
  187. fi
  188. elif command -v shasum &>/dev/null; then
  189. if ! shasum -a 256 -c "$checksum_file" &>/dev/null; then
  190. log_error "Checksum verification failed"
  191. echo ""
  192. echo "The downloaded file may be corrupted or tampered with."
  193. echo "Please try again or report this issue."
  194. echo ""
  195. cd - >/dev/null || cd "$HOME"
  196. exit 1
  197. fi
  198. else
  199. log_warning "Neither sha256sum nor shasum found, skipping checksum verification"
  200. fi
  201. log_success "Checksum verified"
  202. # Extract archive
  203. log_info "Extracting archive..."
  204. if ! tar -xzf "$archive_name"; then
  205. log_error "Failed to extract archive"
  206. exit 1
  207. fi
  208. # Determine install location (with override support)
  209. local install_dir="${WORKMUX_INSTALL_DIR:-}"
  210. if [ -z "$install_dir" ]; then
  211. if [[ -w /usr/local/bin ]]; then
  212. install_dir="/usr/local/bin"
  213. else
  214. install_dir="$HOME/.local/bin"
  215. mkdir -p "$install_dir"
  216. fi
  217. fi
  218. # Check for existing installation
  219. if [ -f "$install_dir/workmux" ]; then
  220. local existing_version
  221. existing_version=$("$install_dir/workmux" --version 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
  222. log_info "Existing installation found: $existing_version"
  223. log_info "Upgrading to: $version"
  224. fi
  225. # Install binary atomically
  226. log_info "Installing to $install_dir..."
  227. local tmp_binary="$install_dir/workmux.tmp.$$"
  228. if [[ -w "$install_dir" ]]; then
  229. cp workmux "$tmp_binary"
  230. chmod +x "$tmp_binary"
  231. mv -f "$tmp_binary" "$install_dir/workmux"
  232. else
  233. if ! sudo cp workmux "$tmp_binary"; then
  234. log_error "Failed to install to $install_dir (sudo required)"
  235. exit 1
  236. fi
  237. sudo chmod +x "$tmp_binary"
  238. sudo mv -f "$tmp_binary" "$install_dir/workmux"
  239. fi
  240. # Remove macOS quarantine attribute if present
  241. if [[ "$(uname -s)" == "Darwin" ]] && command -v xattr &>/dev/null; then
  242. xattr -d com.apple.quarantine "$install_dir/workmux" 2>/dev/null || true
  243. fi
  244. log_success "workmux installed to $install_dir/workmux"
  245. # Check if install_dir is in PATH
  246. if [[ ":$PATH:" != *":$install_dir:"* ]]; then
  247. log_warning "$install_dir is not in your PATH"
  248. echo ""
  249. echo "Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.):"
  250. echo " export PATH=\"\$PATH:$install_dir\""
  251. echo ""
  252. fi
  253. cd - >/dev/null || cd "$HOME"
  254. # Return the install directory via a global variable
  255. INSTALL_DIR="$install_dir"
  256. }
  257. # Verify installation
  258. verify_installation() {
  259. local install_dir="$1"
  260. # Verify the binary exists and is executable
  261. if [ ! -x "$install_dir/workmux" ]; then
  262. log_error "workmux binary not found or not executable at $install_dir/workmux"
  263. exit 1
  264. fi
  265. # Test the binary works
  266. if ! "$install_dir/workmux" --version &>/dev/null; then
  267. log_error "workmux binary exists but failed to run"
  268. exit 1
  269. fi
  270. log_success "workmux is installed and ready!"
  271. echo ""
  272. "$install_dir/workmux" --version
  273. echo ""
  274. # Check if install_dir is in PATH
  275. if ! command -v workmux &>/dev/null; then
  276. log_warning "$install_dir is not in your PATH"
  277. echo ""
  278. echo "Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.):"
  279. echo " export PATH=\"\$PATH:$install_dir\""
  280. echo ""
  281. fi
  282. echo "Get started:"
  283. echo " cd your-project"
  284. echo " workmux init # (optional) create .workmux.yaml config"
  285. echo " workmux add feature # create a worktree and tmux window"
  286. echo ""
  287. echo "Recommended:"
  288. echo " alias wm='workmux' # add to your shell profile for faster typing"
  289. echo ""
  290. echo "Documentation: https://workmux.dev"
  291. echo ""
  292. }
  293. # Main installation flow
  294. main() {
  295. echo ""
  296. echo "🚀 workmux installer"
  297. echo ""
  298. log_info "Detecting platform..."
  299. local platform
  300. platform=$(detect_platform)
  301. log_info "Platform: $platform"
  302. # Check dependencies (warn but don't fail)
  303. check_dependencies
  304. # Download and install
  305. install_from_release "$platform"
  306. # Verify
  307. verify_installation "$INSTALL_DIR"
  308. }
  309. main "$@"
scripts/uninstall.sh · Bundled script · 97 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. #
  3. # workmux uninstall script
  4. #
  5. # Removes workmux binary, status tracking hooks, skills, and data
  6. # directories. Handles all install methods.
  7. #
  8. # Usage: curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/uninstall.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 8 on GitHub
  9. #
  10. # IMPORTANT: This script must be EXECUTED, never SOURCED.
  11. set -euo pipefail
  12. RED='\033[0;31m'
  13. GREEN='\033[0;32m'
  14. YELLOW='\033[1;33m'
  15. BLUE='\033[0;34m'
  16. NC='\033[0m'
  17. log_info() { echo -e "${BLUE}==>${NC} $1"; }
  18. log_success() { echo -e "${GREEN}==>${NC} $1"; }
  19. log_warning() { echo -e "${YELLOW}==>${NC} $1"; }
  20. log_error() { echo -e "${RED}Error:${NC} $1" >&2; }
  21. echo ""
  22. echo " workmux uninstall"
  23. echo ""
  24. # 1. Detect install method and delegate to package manager if applicable
  25. brew_path=""
  26. if command -v brew &>/dev/null; then
  27. brew_path=$(brew --prefix workmux 2>/dev/null || true)
  28. fi
  29. cargo_bin="$HOME/.cargo/bin/workmux"
  30. local_bin="$HOME/.local/bin/workmux"
  31. usr_bin="/usr/local/bin/workmux"
  32. workmux_path="$(command -v workmux 2>/dev/null || true)"
  33. if [ -n "$brew_path" ]; then
  34. log_info "Detected Homebrew installation."
  35. log_info "Run these commands to finish uninstalling:"
  36. echo " brew uninstall workmux"
  37. echo " brew untap raine/workmux"
  38. echo ""
  39. log_info "You can also run the remaining cleanup steps:"
  40. fi
  41. if [ "$workmux_path" = "$cargo_bin" ] || [ -f "$cargo_bin" ]; then
  42. log_info "Detected Cargo installation."
  43. log_info "Run this command to finish uninstalling:"
  44. echo " cargo uninstall workmux"
  45. echo ""
  46. log_info "You can also run the remaining cleanup steps:"
  47. fi
  48. # 2. If workmux binary is available, run binary uninstall first
  49. if [ -n "$workmux_path" ]; then
  50. log_info "Removing status tracking hooks and skills..."
  51. if ! workmux uninstall 2>&1 | sed 's/^/ /'; then
  52. log_warning "workmux uninstall encountered issues (see above)"
  53. fi
  54. echo ""
  55. fi
  56. # 3. Remove binary from known locations
  57. log_info "Removing workmux binary..."
  58. for path in "$usr_bin" "$local_bin" "$cargo_bin"; do
  59. if [ -f "$path" ]; then
  60. if [ -w "$(dirname "$path")" ]; then
  61. rm -f "$path"
  62. log_success "Removed $path"
  63. else
  64. log_info "Removing $path requires sudo..."
  65. sudo rm -f "$path"
  66. log_success "Removed $path"
  67. fi
  68. fi
  69. done
  70. echo ""
  71. # 4. Manual cleanup guidance
  72. log_info "Manual cleanup (check your shell config):"
  73. echo " - Remove 'eval \"\$(workmux completions bash)\"' or similar from"
  74. echo " ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish"
  75. echo " - Remove 'alias wm=workmux' from your shell config"
  76. echo ""
  77. log_info "Configuration preserved at ~/.config/workmux/"
  78. echo " Remove manually with: rm -rf ~/.config/workmux"
  79. echo ""
  80. log_info "Worktrees remain on disk:"
  81. echo " Clean up with: git worktree list && git worktree remove <path>"
  82. echo ""
  83. log_success "workmux has been uninstalled."

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.