workmux

Manages git worktrees paired with tmux windows as isolated development environments.

2|Updated Oct 16, 2021
One-click install
npx skills add https://github.com/pattobrien/dotfiles --skill workmux-pattobrien
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: workmux
Source: https://github.com/pattobrien/dotfiles/tree/main/claude/skills/workmux
Command: npx skills add https://github.com/pattobrien/dotfiles --skill workmux-pattobrien

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Coordinating parallel development work across multiple branches requires juggling git worktrees, tmux windows, and AI agent sessions manually, which becomes error-prone when running several agents at once. ## Core Features & Use Cases - Worktree and Window Management: Create, list, open, close, and remove git worktrees paired with tmux windows using commands like workmux add, workmux list, and workmux remove. - Agent Orchestration: Check agent status, wait for completion, capture terminal output, and send instructions to agents across projects with workmux status, workmux wait, workmux capture, and workmux send. - Merge and Cleanup Workflows: Merge branches with rebase or squash strategies and clean up worktrees, windows, and branches in one step via workmux merge. - Use Case: Dispatch three parallel AI agents to work on separate feature branches, monitor their progress with workmux status, then merge each finished branch back into main. ## Quick Start Ask the assistant to create a new workmux worktree for a branch named feature-login with a prompt describing the task for the agent.

Frequently Asked Questions about workmux

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a git worktree with a tmux window using workmux?▼

Run `workmux add <branch-name>` to create a git worktree, run configured hooks and file operations, and open a tmux window with your pane layout. Use `-b` to create it in the background without switching, or `-P <file>` to pass a prompt file to the agent.

How do I send instructions to an agent running in another worktree?▼

Use `workmux send <handle> "message"` to send text to an agent identified by its worktree handle. You can also send from a file with `-f`, send skill commands like `/merge`, or target another project with the `project:handle` syntax.

Which AI agents does workmux support?▼

workmux auto-detects built-in agents including claude, gemini, codex, opencode, kiro-cli, and vibe in pane commands, injecting prompts automatically. The `<agent>` placeholder in configuration resolves to whichever agent you set as the default.

How do I clean up worktrees after a PR is merged remotely?▼

Run `workmux rm --gone` to remove worktrees whose remote branch was deleted, which handles post-PR cleanup. For local merges, `workmux merge` merges the branch, deletes the tmux window, removes the worktree, and deletes the local branch in one step.

Can workmux create worktrees in a different project than the current one?▼

Yes, but `workmux add` operates on the current git repo and tmux session, so you must run it inside the target project's tmux session. Use `tmux new-window -t <session> -c <project-path>` to dispatch the command to the right session.