My workflow

[napisani]

Hi @raine -
I'm a fan of your project and i have been daily driving it for about 2 weeks. I'm relatively new to worktrees, I'm still constantly tweaking my workflow to better optimize for working with agentic assistance. Given that, please take this workflow for what is worth:

This is my workmux.yaml, the project i work in is a typescript + python monorepo. I use a tool, which I wrote called proctmux, which acts as terminal multiplex specifically for dealing with long running processes. I know it sounds odd to have a multiplexer running inside of tmux but proctmux work for me.

main_branch: main
worktree_dir: ../project_name__worktrees
agent: opencode
mode: session

post_create:
  - >
    bash -lc '
    set -euo pipefail;
    ROOT="$(pwd)";
    if [ -f "$ROOT/mise.toml" ]; then
      printf "Trusting mise config: %s\n" "$ROOT/mise.toml";
      mise trust "$ROOT/mise.toml";
    fi;
    while IFS= read -r -d "" file; do
      [ "$file" = "$ROOT/mise.toml" ] && continue;
      printf "Trusting mise config: %s\n" "$file";
      mise trust "$file";
    done < <(find "$ROOT" -type f -name "mise.toml" -print0 | sort -z);
    while IFS= read -r -d "" file; do
      printf "Allowing direnv file: %s\n" "$file";
      direnv allow "$file";
    done < <(find "$ROOT" -type f -name ".envrc" -print0 | sort -z);
    printf "Installing pnpm dependencies\n";
    mise x -- pnpm install --config.confirmModulesPurge=false
    '

files:
  copy:
    - "**/.env"
    - "**/.env.*"
    - "**/.envrc"
    - .gitignore_local
    - .opencode
    - .opencode/**
    - procmux.yaml

panes:
  - command: nvim
    focus: true
  - command: proctmux --unified-toggle
    split: horizontal
    percentage: 40

I use session mode exclusively for workmux and i use this bit of tmux config to constantly switch between sessions. I bind the ctrl+x key combo to a custom script that will remove the workmux worktree, or kill the session if its a regular session.

# prefix + f = fzf session switcher
# enter: switch to session | ctrl-x: kill session (workmux-aware) + refresh list
unbind f
bind f display-popup -E "\
    tmux list-sessions -f '#{?#{||:#{m:_popup_*,#S},#{m:_proctmux*,#S}},0,1}' -F '#S' | \
    fzf --reverse --header 'Switch: enter | Kill: ctrl-x' \
    --bind 'enter:execute(tmux switch-client -t {})+accept' \
    --bind 'ctrl-x:execute-silent(tmux-session-kill.sh {})+reload(tmux list-sessions -f \"#{?#{||:#{m:_popup_*,#S},#{m:_proctmux*,#S}},0,1}\" -F \"#S\")'"

#!/usr/bin/env bash
# tmux-session-kill.sh — Smart session removal with workmux awareness.
#
# Usage: tmux-session-kill.sh <session-name>
#
# Logic:
#   1. Popup session (_popup_*) → kill directly
#   2. Workmux worktree session (nerd font icon prefix) → workmux remove --force
#   3. Regular session → kill its popup companion first, then kill the session
#
# Designed to be called from fzf --bind inside a tmux display-popup.

set -euo pipefail

SESSION="${1:?Usage: tmux-session-kill.sh <session-name>}"

# Nerd font icon used by workmux as session prefix (U+F418, 3-byte UTF-8)
WORKMUX_PREFIX=$'\xef\x90\x98'

# ── Helper: kill a tmux session if it exists ──
kill_session_if_exists() {
	local name="$1"
	if tmux has-session -t "=$name" 2>/dev/null; then
		tmux kill-session -t "=$name"
	fi
}

# ── 1. Popup session → just kill it ──
if [[ "$SESSION" == _popup_* ]]; then
	kill_session_if_exists "$SESSION"
	exit 0
fi

# ── 2. Workmux worktree session (icon-prefixed) ──
if [[ "$SESSION" == "${WORKMUX_PREFIX}"* ]]; then
	# Extract branch name: strip the icon prefix
	BRANCH="${SESSION#"${WORKMUX_PREFIX}"}"
	# Trim any leading whitespace the icon might leave
	BRANCH="${BRANCH#"${BRANCH%%[![:space:]]*}"}"

	# Find the worktree directory from a pane in this session
	PANE_PATH=$(tmux list-panes -t "=$SESSION" -F '#{pane_current_path}' 2>/dev/null | head -1)

	if [ -n "$PANE_PATH" ]; then
		# The pane path is inside the worktree. The main repo is the git
		# common dir's parent (worktree -> __worktrees/branch, main repo is sibling).
		MAIN_REPO=$(git -C "$PANE_PATH" rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/\.git$||')

		if [ -n "$MAIN_REPO" ] && [ -f "$MAIN_REPO/.workmux.yaml" ]; then
			# Kill companion popup first
			kill_session_if_exists "_popup_${SESSION}_scratch"
			# Use workmux remove from the main repo directory
			(cd "$MAIN_REPO" && workmux remove --force "$BRANCH") 2>/dev/null || true
			# Ensure session is gone even if workmux didn't fully clean up
			kill_session_if_exists "$SESSION"
			exit 0
		fi
	fi

	# Fallback: kill popup + session directly if workmux detection failed
	kill_session_if_exists "_popup_${SESSION}_scratch"
	kill_session_if_exists "$SESSION"
	exit 0
fi

# ── 3. Regular session → kill popup companion, then kill session ──
kill_session_if_exists "_popup_${SESSION}_scratch"
kill_session_if_exists "$SESSION"
exit 0

As far as workflow is concerned, I'm probably going against the grain a bit because each worktree for me is a separate Jira ticket / separate initiative. Each worktree I create eventually becomes a PR for my team to review, i never actually merge them back into a common branch before raising PRs. So I always end up just deleting worktrees when I am done with them vs using the workmux merge features. Because of this, I haven't used the dashboard feature that much, I have been preferring my own tmux session switcher so that i can switch between dissimilar worktrees and sessions.

So far i don't find myself reaching for any major features in workmux that don't already exist. I think if i had anything I would wish for, it would be better worktree delete support from the dashboard view so that i could try to replace some of the my custom tmux logic with something more idiomatic.

I hope this helps provide some feedback / guide the project. Don't feel compelled to introduce any new features on my account though.

Also, if you happen to notice something about workflow I described above that you would discourage or do a different way, please let me know.

Thanks for sharing workmux with the open source community,
~Nick