Swarm Spawn backend is hardcoded to tmux — does not work with cmux (and likely other non-tmux multiplexers)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 19.9k
- Forks
- 2.3k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 30
Description
Bug Report
jcode version: (e.g. 0.67.1)
OS: macOS
Terminal: cmux (native macOS terminal, not tmux)
Current Behavior
When running jcode harness with the swarm command inside cmux, worker agents do not open in their own tabs or panels. The same workflow works correctly under tmux, where each worker spawns in a separate tmux pane.
I have also written a custom cmux hook to allow cmux to communicate with jcode (for notification badges), but this does not resolve the missing worker panes.
Steps to Reproduce
- Open cmux (not tmux).
cdinto a repository and start jcode:jcode serve- Use the
swarmtool or command to spawn worker agents. - Observe that no new cmux tabs/panels are created for the workers.
- Repeat the same steps inside tmux — workers spawn correctly in tmux panes.
Expected Behavior
Worker agents should spawn in separate cmux panels/tabs, or there should be a documented/configurable way to integrate with non-tmux terminal multiplexers.
Actual Behavior
- Workers fail to spawn in cmux panels entirely.
- They may spawn as invisible background processes or not at all.
- The swarm orchestration appears to hang or run single-threaded because the worker panes never appear.
Root Cause
jcode's swarm spawn logic shells out to tmux commands directly (e.g., tmux split-window, tmux send-keys, tmux new-window) to create worker panes. This was introduced around v0.54.4 ("tmux spawns in panes").
cmux is not tmux. It is a native macOS terminal with its own CLI and API (cmux new-workspace, cmux split, cmux send, etc.). It does not implement the tmux command protocol, so it cannot interpret jcode's tmux spawn calls. A notification hook only handles post-spawn notifications — it cannot intercept or replace the pane-creation logic.
Workarounds Tried
- cmux hook for jcode notifications: Works for badges/alerts, but does not fix pane spawning.
- Running
jcode serve --workers 4: Flag does not exist; workers must be spawned dynamically. - Running jcode inside tmux, then attaching cmux to tmux: Works but defeats the purpose of using cmux natively.
Proposed Solutions
- Configurable spawn backend: Add a setting like
spawn_backend = "tmux" | "cmux" | "custom"in~/.jcode/config.toml. When set tocmux, jcode would use cmux's native CLI (cmux split,cmux send) instead of tmux commands. - Generic shell spawn mode: Allow jcode to spawn workers via user-defined shell commands rather than hardcoded tmux calls.
- Document tmux-as-backend requirement: If tmux is strictly required for swarm, document this clearly so users know to run jcode inside tmux first.
Additional Context
- cmux supports attaching to remote/local tmux sessions natively, so a temporary workaround is to run jcode inside tmux and then attach cmux to that tmux session. However, native cmux integration would provide a much better UX.
- Happy to test any experimental cmux backend or provide cmux CLI documentation if helpful.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the swarm worker-spawn path used by jcode harness and trace the direct tmux split-window, tmux send-keys, and tmux new-window calls. Run the reported swarm workflow under tmux and cmux to establish the current behavior. Done should mean either a supported configurable non-tmux backend or clear documentation that tmux is required.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, devtools
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100