Feature request: native tmux pane spawning for swarm teammates (same-window multi-agent view, like Claude Code)

[rameshbaskaran]

What I want

Native, first-class support for spawning swarm teammates as interactive tmux panes in the same window as the coordinator — the way Claude Code does it. Today swarm spawn works, but the teammate sessions do not appear alongside the coordinator on one screen, so there is no way to watch several agents work at once without manual shell glue.

Why this matters

The value of a swarm is observability while it runs. With headless/inline spawns I get a report at the end; with panes I can see an agent go down a wrong path and correct it immediately. Claude Code's multi-pane view is the single biggest ergonomic difference today.

Current state (v0.67.1) — this is mostly already built

Digging through the binary and testing on tmux 3.7b, almost all the machinery exists:

• The binary already says: "Without a hook, clients inside tmux automatically use a right-side pane."
• [terminal] spawn_hook / focus_hook exist and receive <hook> <jcode-binary> <args...> plus JCODE_SPAWN_SESSION_ID, JCODE_SPAWN_TITLE, JCODE_SPAWN_CWD, JCODE_SPAWN_PROGRAM, JCODE_SPAWN_COMMAND.
• TMUX / TMUX_PANE are already probed alongside Zellij, kitty, WezTerm, Ghostty, herdr.
• The documented example is spawn_hook = "tmux new-window" — a window per agent, not a pane.

Two things block the out-of-the-box experience:

1. [agents] swarm_spawn_mode defaults to "inline" (there is even a one-time migration string swarm_spawn_mode default migration: visible -> inline). Inline is in-process with no window, so no spawn hook ever fires and the tmux auto-pane path is unreachable. This is the actual root cause, and it is not discoverable — you have to know to flip it to "visible" first.
2. Naive tmux split-window -h collapses geometry. Measured in a 200x50 window: pane widths went 100 → 49 → 24 → 12 → 11 columns after 4 agents. Usable tiling needs tmux select-layout tiled after each split.

Working config today (for anyone hitting this)

[agents]
swarm_spawn_mode = "visible"

[terminal]
spawn_hook = "~/bin/jcode-tmux-pane"

#!/bin/sh
# jcode spawn_hook: each spawned session becomes a tiled tmux pane in the CURRENT window.
set -eu
if [ -z "${TMUX:-}" ] && [ -z "${TMUX_PANE:-}" ]; then
  exit 1   # not in tmux -> non-zero lets jcode fall back to its own terminal detection
fi
TARGET="${TMUX_PANE:-}"
CWD="${JCODE_SPAWN_CWD:-$PWD}"
if [ -n "$TARGET" ]; then
  tmux split-window -h -t "$TARGET" -c "$CWD" "$@"
else
  tmux split-window -h -c "$CWD" "$@"
fi
tmux select-layout tiled
[ -n "${JCODE_SPAWN_TITLE:-}" ] && tmux select-pane -T "$JCODE_SPAWN_TITLE" 2>/dev/null || true
exit 0

Verified: 3 simulated spawns produced 4 panes at ~100x24 with pane titles set from JCODE_SPAWN_TITLE; outside tmux the hook exits 1 and jcode correctly falls back to built-in terminal detection.

Proposed

1. swarm_spawn_mode = "tmux" (or make "visible" detect tmux natively) that does split + select-layout tiled + select-pane -T "$JCODE_SPAWN_TITLE" internally, with no user shell script.
2. [agents] tmux_layout = tiled | even-horizontal | even-vertical | main-vertical, so the coordinator can keep a large main pane with teammates tiled beside it.
3. Pane lifecycle tied to session lifecycle — pane closes (or is marked dead, per a tmux_close_on_exit setting) when the teammate reaches ready/stopped/failed, so swarm cleanup doesn't leave orphan panes.
4. Cap and overflow behaviour — respect swarm_max_concurrent_agents (mine is 32, which would be unreadable as panes); beyond tmux_max_panes, spill to new tmux windows rather than shrinking panes to 11 columns.
5. Discoverability — when swarm spawn runs inside tmux while swarm_spawn_mode = "inline", emit a one-time hint that tmux panes are available.

Difficulty

Items 1 and 2 look small: the terminal-detection, hook-invocation, and env-passing paths already exist, so this is mostly a built-in hook implementation plus a config enum. Item 3 (lifecycle) is the one that needs real design, since it touches session teardown and the same cleanup concerns raised in #737 for bg watch sources.

Environment

jcode v0.67.1 (88a19f3), macOS aarch64, tmux 3.7b.

[rameshbaskaran]

Closing for now — I have not yet verified the swarm_spawn_mode=visible + tmux spawn_hook path end-to-end from inside a real tmux session. Will retest and reopen with evidence if the built-in behaviour is insufficient.

[rameshbaskaran]

Reopening — with a reproducible bug, not just an ergonomics request

I closed this to test the existing config path first. It turns out the workaround config actively breaks swarm spawning, so this is now a bug report rather than a feature request.

Bug: swarm_spawn_mode = "visible" and "auto" hang every spawn at "startup queued" when no terminal is available

Repro (jcode v0.67.1, macOS aarch64, session NOT running inside tmux):

1. Set in ~/.jcode/config.toml:

   [agents]
   swarm_spawn_mode = "visible"
   [terminal]
   spawn_hook = "~/bin/jcode-tmux-pane"   # exits 1 when TMUX/TMUX_PANE unset

2. swarm spawn any agent.
3. Agent sits at Status: running — startup queued indefinitely. It never runs, never fails, never times out. swarm stop is the only exit.

Three data points from one session, same prompt, same machine, back to back:

swarm_spawn_mode	Result
inline	Works — 6 workers spawned and completed normally
visible	Hangs at "startup queued" (agent otter, killed after ~90s)
auto	Hangs at "startup queued" (agent panda, killed after ~30s)
inline (reverted)	Works again immediately (agent peacock)

Expected: when the spawn hook exits non-zero, or no terminal can be attached, jcode should fall back to headless/inline and run the agent, or fail fast with a clear error. Silently queueing forever is the worst option — the coordinator's await_members wait also never resolves, so a whole swarm can stall on this.

Notably "auto" failing the same way is the more serious half: auto is supposed to be the safe "pick something that works" setting, and it picks something that doesn't.

The hook itself is fine

To be clear the tmux side works. Driving the same hook manually with simulated JCODE_SPAWN_* env in a 220x50 tmux window:

%0 109x24 title=brmacair
%1 110x25 title=coder
%2 109x25 title=reviewer
%3 110x24 title=tester

Correct 2x2 tiling, titles from JCODE_SPAWN_TITLE, no geometry collapse. So the pane machinery is all present and working — what's missing is (a) a safe fallback when there is no terminal, and (b) native support so users don't need the shell script at all.

Original request still stands (see below)

Everything in the original body remains valid: swarm_spawn_mode defaults to inline, so no hook ever fires and the built-in "right-side pane inside tmux" path is unreachable; the documented example gives a window per agent rather than a pane; and bare tmux split-window -h collapses to 11 columns by the 4th agent without select-layout tiled.

Proposed, in priority order now:

1. Fix the hang — non-zero hook exit or no available terminal must fall back (to inline/headless) or error out, never queue forever. Also applies to auto.
2. swarm_spawn_mode = "tmux" built in (split + select-layout tiled + select-pane -T), no user shell script.
3. [agents] tmux_layout = tiled | even-horizontal | even-vertical | main-vertical.
4. Pane lifecycle tied to session lifecycle, so swarm cleanup doesn't orphan panes.
5. Cap/overflow: respect swarm_max_concurrent_agents (mine is 32 — unreadable as panes); past tmux_max_panes, spill to new windows.
6. Discoverability hint when spawning inside tmux while inline.

Environment: jcode v0.67.1 (88a19f3), macOS aarch64, tmux 3.7b.

[1jehuang]

The startup hang should be treated separately from native tmux feature work. A missing hook or terminal must fail fast or fall back instead of remaining startup-queued. Pane layout, lifecycle, and overflow behavior then need a separate product design.

--- — Jcode agent (automated triage), on behalf of @1jehuang

[1jehuang]

The indefinite startup-queued bug is fixed in PR #820. Spawn hooks now get a short startup observation window: an immediate non-zero exit is treated as launch rejection, so built-in terminal detection runs and visible/auto swarm spawning can then fall back to headless execution instead of registering a phantom visible worker. Long-running hooks remain supported and are reaped asynchronously.

Focused hook and visible-session lifecycle tests pass against a clean base. This addresses the hang only; the broader native tmux layout/lifecycle feature remains separate design work.

--- — Jcode agent (automated triage), on behalf of @1jehuang