| name | foxctl-tmux |
| description | Compatibility alias for the room viewer layer. Prefer `foxctl-room-view` for current tmux, zellij, and GUI guidance. |
Mux Collaboration
foxctl-tmux is now a compatibility name.
Use foxctl-room-view for current viewer and
presentation-layer guidance.
Use foxctl-room-agent for participant
agent behavior inside a room.
Keep using the existing foxctl mux ... commands and bundled
./scripts/tmux-bridge helper where needed. The change is conceptual: rooms are
canonical, mux is presentation.
Important runtime note:
- for Droid,
foxctl mux create --agent droid --mode auto is not equivalent to --mode interactive
--mode auto enables the Droid startup profile in the pane wrapper--mode interactive bypasses that profile and can leave Droid in approval-gated behavior
zellij:<session>:terminal_3. Use --sender only when overriding or when
running outside a mux session.
Restarting an existing zellij session
If you reopened or manually created a zellij session, do not assume the panes
are already room-bound just because they share a session name.
Check first:
printf 'ROOM=%s ACTOR=%s ROLE=%s SESSION=%s PANE=%s\n' \
"$FOXCTL_ROOM_ID" \
"$FOXCTL_PARTICIPANT" \
"$FOXCTL_ROOM_ROLE" \
"$ZELLIJ_SESSION_NAME" \
"$ZELLIJ_PANE_ID"
If ROOM / ACTOR are empty, bind the pane explicitly:
foxctl room join <room-id> --current --role <room-role>
Use that in each zellij pane that should receive room traffic. For zellij,
room membership is pane-bound, not merely session-bound.
If an existing participant moves to a different pane, repair the stored mux
binding instead of pretending it is a new member:
foxctl room rebind <room-id> <actor-id> --backend <tmux|zellij> --session <session> --pane-id <pane>
The intended room policy is:
- top-level panes may join rooms directly
- child panes stay parent-private by default
- parents summarize child work back into the room when needed
Message Format
send prepends a stable header before pressing Enter:
[tmux-bridge from=agent-a pane=%3 reply_to=agent-a] review mailbox retry logic
That keeps replies human-readable and parseable without depending on fragile prose.
ContextWiki Promotion
Promote only derived facts, not raw pane dumps. Good examples:
foxctl mux observe agent-b --lines 80
foxctl mux observe agent-b \
--statement "agent-b is reviewing mailbox ack semantics in internal/runtime/actor/supervisor.go"
If a tmux exchange produced durable repo knowledge, capture it through the existing ContextWiki and Obsidian flow after review.
Reference doc: docs/general/tmux-collaboration.md
