Make workmux "Mux" agnostic, AKA support Wezterm

[JeremyBYU]

So I did something crazy: https://github.com/JeremyBYU/workmux/tree/jc/wezterm

The basic idea: make workmux backend-agnostic so it can work with tmux or WezTerm (or potentially other multiplexers in the future).

What I did:

• Created a Multiplexer trait that abstracts all the window/pane management, status display, and shell integration
• Ported the existing tmux code to implement this trait
• Added a WezTerm backend implementation

Some interesting challenges with WezTerm:

• No server-side state like tmux has, so I use tab_title as a stable identifier across mux contexts, and a local JSON registry for status tracking from claude code hooks.
• No wait-for mechanism - tmux has a nice channel-based wait-for that blocks until a shell is ready. WezTerm doesn't, so I had to use named pipes (FIFOs) with libc::poll() to synchronize shell startup

Bonus feature: The dashboard now supports --all flag to view agents across all WezTerm workspaces (tmux sessions) at once, with a workspace column to show where each agent lives.

Also updated all tests to be backend-agnostic with a --backend pytest flag.

The WezTerm support is definitely alpha! Not everything is fully supported yet. But the core workflow works! Figured I'd put it out there in case anyone's interested or the maintainer(s) want to explore this direction.

[raine]

Thanks for exploring this - looks great. If workmux were to be multiplexer agnostic, this is probably the way to do it.

I would still probably keep tmux as the "main" backend with the documentation and examples mainly focusing it, but would not mind introducing best-effort support for other multiplexers, I think. Alternative backends could have their own page in the documentation.

Might start cherry-picking your commits at some point and see how it goes.

No server-side state like tmux has, so I use tab_title as a stable identifier across mux contexts, and a local JSON registry for status tracking from claude code hooks.

What is tab_title? Do you think it would help a lot if even tmux used a local JSON registry (or something) for state?

[JeremyBYU]

I would still probably keep tmux as the "main" backend with the documentation and examples mainly focusing i

Oh yeah, tmux is the "main", this should be seen as more experiment to open up workmux to more users.

Alternative backends could have their own page in the documentation.

yep, that sounds very reasonable.

Might start cherry-picking your commits at some point and see how it goes.

yeah I tried hard to make the commits clear of their intention and the "progression". I would start with the refactor: add Multiplexer trait and port tmux backend and if happy with it and any changes you make then feat: add WezTerm backend implementation to check out wezterm.

I think you will hate feat: add cross-workspace dashboard support (--all flag). It was not a very elegant solution when it came to the gui.... However it is nice to see all the other agents. It can be easily dropped.

test: add multi-backend test infrastructure - this just shows a simple basic test of a multi-backend test infrastrructure. I think you would want that as a minimum if we supprt wezterm.

test: convert all tests to be backend agnostic - this it the more ambitious refactor of tests that converts them all to be backend agnostic. There are some tests which are tmux only and it uses a pytest marker for those.

What is tab_title?

Backend	Identification	Status Storage
tmux	@workmux_pane_status (server-side pane option)	tmux server (same pane option)
WezTerm	tab_title.starts_with("wm-") (client-side)	JSON registry file (~/.local/share/workmux/)

Note that on in wezterm (for my config) tab_title is NOT whats visible. Only title is visible. Here is an example. I only see the pwd in the title of the tab (truncated of course). Often claude code status also overwrite the title (this is irrespective of workmux).

❯ wezterm cli list --format json | jq '.[] | {pane_id, tab_title, workspace, title}'
{
  "pane_id": 6,
  "tab_title": "",
  "workspace": "ridewithgps",
  "title": "~/Documents/workspace/ridewithgps"
}

Do you think it would help a lot if even tmux used a local JSON registry (or something) for state?

NO! I think its a fools game to keep the file up to date. I think there really should be one source of truth and it should live on the "server". I first tried to put all sessions details etc in there thinking it would be awesome to have a persistent file. It was a nightmare. Just consider what happens when a user manually closes panes. Think about two claude session trying to update (possible with file locks but more complexity). I would recommend to skip with trying as hard as you can to put the truth of the sessions on the "server". In fact, I wonder if I can just just port over the status json file as a suffix at the end of tab_title.

[raine]

@JeremyBYU Hey, I cherry-picked your 50b9be6 and started experimenting with using JSON files in $XDG_STATE_HOME (~/.local/state/workmux/) as backend-agnostic storage: main...state

~/.local/state/workmux/
├── settings.json   # sort mode, hide_stale, preview_size
└── agents/
    └── tmux__%2Fprivate%2Ftmp%2Ftmux-501%2Fdefault__%2579.json

{
  "pane_key": {
    "backend": "tmux",
    "instance": "/private/tmp/tmux-501/default",
    "pane_id": "%79"
  },
  "workdir": "/Users/raine/code/workmux__worktrees/state",
  "status": "done",
  "status_ts": 1768847345,
  "pane_title": "⠐ Backend-agnostic state",
  "pane_pid": 98659,
  "command": "node",
  "updated_ts": 1768847345
}

There are probably some rough edges and I'll be running this branch to see how the approach works, but seems promising.

If you think it makes sense, might be worth rebasing your wezterm changes on top of this. (I did remove some unused things from the cherry-picked refactor commit that were probably only used in later commits, so you might have to add them again.)

[JeremyBYU]

Thanks for taking a look at this! I've been thinking about it more, and I'm still a bit hesitant about the file-based strategy. Though it is growing on me a bit after reading store.rs.

Moving to individual files per pane definitely helps with race condition concerns! That's a real improvement over a single registry file. But I keep getting stuck on this statement from the design:

Decouple state storage from the multiplexer. Use the filesystem as the source of truth; the multiplexer becomes a view layer only.

I'm not sure this can fully be true in practice. Even with this design, reconciliation is still required on every read:

• Pane no longer exists → delete state file
• PID mismatch → delete state file
• Command changed → delete state file

If the filesystem were truly the source of truth, we wouldn't need to validate it against the multiplexer. But we do and now we're also validating against live process lists. To me, that makes the filesystem more of a cache than a source of truth.

Which raises my main question: what benefit is the cache giving us? If querying the multiplexer directly is already cheap, what do we gain by maintaining a parallel copy that needs reconciliation on every read?

Maybe there's a use case where persistence across restarts matters more than I'm seeing? Or maybe the uniformity across backends (everything uses the same StateStore) is the real win, even if it means tmux/wezterm loses its native options approach?

I think that might be the core tradeoff: unified storage vs best-fit-per-backend? The file approach gives consistency; the native approach lets each backend use what it's good at.

Finally, the code itself looks great. The StateStore encapsulation is very clear, the atomic writes are solid, and the reconciliation logic is nicely isolated. I'm not questioning the implementation, just wondering if the pattern (constant reconciliation) is the right tradeoff. But I could be way off here! And I am starting to come around to it...

[raine]

what benefit is the cache giving us?

As you said it, mainly that the storage mechanism is uniform across backends. I think this should improve maintainability.

I don't really see a big difference, at least currently, on whether tmux uses its own state or json files. It's cache either way.

Main difference is that if you restart your tmux server, that conveniently clears all the variables as well. But the reconciliation is needed anyway because if you close an agent with ctrl-c, in the dashboard we need to be able remove that agent pane from the list.

1. When an agent pane is created, workmux stores the running command in the tmux variable @workmux_pane_command
2. Every refresh, get_all_agent_panes() compares:
   • original_cmd = @workmux_pane_command (stored when agent started)
   • current_cmd = pane_current_command (live from tmux)
3. If they don't match (agent exited, different command running), it:
   • Calls clear_pane_status(pane_id) to clean up tmux variables
   • Skips the pane with continue (doesn't add to list)

Again to use the agent status tracking as an example, since we can't query the agents directly through some API directly, we push the agent's status through the hooks to the state/cache. For tmux this has been the internal variables, but it might as well be some database or JSON for simplicity. Doesn't really matter, I feel.

[raine]

For clarity:

Pane-level variables (set with -p):

• @workmux_pane_status - Agent status icon (working/waiting/done). Used by dashboard to list active agents and display their state
• @workmux_pane_status_ts - Unix timestamp when status was set. Used for stale detection (>60min = stale), elapsed time display ("5m", "2h"), and sorting by recency
• @workmux_pane_command - Command running when status was set. Compared against live pane_current_command to detect when agent exits (command changed = remove from list)

Window-level variables (set with -w):

• @workmux_status - Status icon displayed in tmux status bar next to window name
• @workmux_status_ts - Timestamp for window status. Unused, apparently

Global/session variables (dashboard settings, persisted across sessions):

• @workmux_hide_stale - Whether to filter out stale agents from dashboard list
• @workmux_preview_size - Preview pane size as percentage (10-90)
• @workmux_sort_mode - Dashboard sort mode: priority (default), project, recency, or natural (by pane ID)

Majority of the state is for the dashboard. @workmux_status is for showing the icon in the window list and the value is literally the emoji.

[JeremyBYU]

I don't really see a big difference, at least currently, on whether tmux uses its own state

Not a big difference, except native @options auto-cleanup when panes die (sessions or manual close), whereas files need explicit pruning. But like I said, the implementation you arrived at handles this cleanly, the reconciliation is nicely isolated.

I think what you have is great and I'll try to rebase off of it later. Thanks again!

[JeremyBYU]

@raine ,

Ready for review: https://github.com/JeremyBYU/workmux/tree/jc/wezterm-new . I can PR if that is preferred, but you mentioned liking to cherry pick.

3 commits:

1. 6ffc543 - WezTerm backend implementation (added some fixes to worktree path for add and close, added wezterm doc)
2. 84addd3 - Backend-agnostic test infrastructure (tested on tmux and wezterm)
3. fac9a5a - Cross-workspace dashboard (--all flag) (you might not want this!)

Built on top of the state branch as discussed. F

[raine]

Hey, thanks for the effort! I've finished cherry-picking the first two commits and doing some changes on top of those.

One of the main ones is that I opted to make the backend auto-detected based on environment. Can't see any reason right now why it wouldn't work and it keeps things simpler. 8354476

I'll use the branch for a while to find any issues and will look into merging to main tomorrow or the day after. It will be interesting, as I've ported some new features from main to it directly as new commits because cherry-picking or rebasing due to conflicts was infeasible.

[raine]

@JeremyBYU As for fac9a5a - Cross-workspace dashboard, is this why you needed it?

• tmux: instance_id() returns the socket path (e.g. /tmp/tmux-501/default). All tmux sessions share the same socket, so they all have the same instance ID. That's why the dashboard already shows agents across all sessions -- they all pass the instance filter.
• WezTerm: instance_id() returns the current workspace name. Each workspace is a different instance ID, so the filter at store.rs:158 excludes agents from other workspaces.

So the --all commit exists specifically because WezTerm workspaces are scoped differently than tmux sessions. In tmux, sessions are subdivisions within one server instance. In WezTerm, workspaces act as separate instances, making the dashboard single-workspace by default

I was confused because dashboard already shows all sessions for tmux, which was the intent when creating it because it then allows an overview of agents across all sessions - something that was lacking with just the statuses in the window bar.

[raine]

I can't easily test this, but perhaps something like this could work. So that tmux and wezterm would share the default behavior of showing all agents across sessions/workspaces.

diff --git i/src/multiplexer/wezterm.rs w/src/multiplexer/wezterm.rs
index f641d1f..24467e1 100644
--- i/src/multiplexer/wezterm.rs
+++ w/src/multiplexer/wezterm.rs
@@ -801,9 +801,11 @@ impl Multiplexer for WezTermBackend {
     // === State Reconciliation ===
 
     fn instance_id(&self) -> String {
-        // Use the current workspace as instance ID, or "default" if not available
-        self.current_workspace()
-            .unwrap_or_else(|| "default".to_string())
+        // Use the unix socket path as instance ID so all workspaces on the same
+        // WezTerm server share one instance — matching tmux behavior where all
+        // sessions on the same server are visible in the dashboard.
+        std::env::var("WEZTERM_UNIX_SOCKET")
+            .unwrap_or_else(|_| "default".to_string())
     }
 
     fn active_pane_id(&self) -> Option<String> {

[JeremyBYU]

Yeah, that makes sense now.

I originally made instance_id correspond to the WezTerm workspace (analogous to a tmux session), because of this comment in the tmux backend:

// Format: /path/to/socket,pid,session_index

That made it look like the intent was to scope instances per session. I just didnt read enough of the code...

Looking closer, though, the tmux implementation only ever uses the socket path, explicitly ignoring both the PID and the session index. So in practice, instance_id identifies the tmux server, not an individual session.

So switching WezTerm to use WEZTERM_UNIX_SOCKET is the correct equivalent. It ensures all workspaces on the same WezTerm mux share a single instance, matching tmux behavior where all sessions on the same server are visible together.

That said, it would still be useful for the dashboard to display which WezTerm workspace (or tmux session) an agent belongs to as contextual metadata. Maybe it already did and I got confused by my bad implementation lol.

[raine]

That said, it would still be useful for the dashboard to display which WezTerm workspace (or tmux session) an agent belongs to as contextual metadata. Maybe it already did and I got confused by my bad implementation lol.

It's the Project column

[JeremyBYU]

One of the main ones is that I opted to make the backend auto-detected based on environment. Can't see any reason right now why it wouldn't work and it keeps things simple

I think thats fair, but I would still allow some type of override for testing if possible. I can test both tmux and wezterm in the same wezterm terminal. However, thats a niche thing! Maybe just a simple environment variable? But leave it up to you!

[raine]

Of course happy to add env var if there's a valid use case

[raine]

@JeremyBYU WezTerm support is now in main and released in v0.1.102. Thanks for the contribution!

I actually tried it briefly and it seemed to work. There was initially some weirdness with a completed agent disappearing from dashboard but I couldn't reproduce it second time.

Feel free to send future improvements as PRs, makes more sense from now on.

[JeremyBYU]

W00t! I will give it a try tomorrow sometime!

[JeremyBYU]

Its working great for me, no issues!

[raine]

Nice!