1jehuang / 1jehuang/jcode

Swarm Spawn backend is hardcoded to tmux — does not work with cmux (and likely other non-tmux multiplexers)

Open
#775 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug needs-info priority: medium triage: unclear
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
  1. Open cmux (not tmux).
  2. cd into a repository and start jcode: jcode serve
  3. Use the swarm tool or command to spawn worker agents.
  4. Observe that no new cmux tabs/panels are created for the workers.
  5. 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
  1. Configurable spawn backend: Add a setting like spawn_backend = "tmux" | "cmux" | "custom" in ~/.jcode/config.toml. When set to cmux, jcode would use cmux's native CLI (cmux split, cmux send) instead of tmux commands.
  2. Generic shell spawn mode: Allow jcode to spawn workers via user-defined shell commands rather than hardcoded tmux calls.
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.