feat: Add native Zellij terminal multiplexer support

[mrdavidlaing]

Summary

Implements native Zellij terminal multiplexer support alongside tmux, providing users with more flexibility in their terminal setup. This adds a unified abstraction layer that supports both tmux and zellij, with automatic detection and capability-based behavior.

Closes #1153

Key Features

✅ Unified Multiplexer Interface: Capability-based abstraction supporting both tmux and zellij
✅ Auto-detection: Automatically detects which multiplexer is running via environment variables
✅ Configuration: New terminal.provider option (auto, tmux, zellij)
✅ Pane Stacking: Anchor pane system for tab-like behavior in both multiplexers
✅ Auto-close: Panes close instantly when background tasks complete
✅ Backward Compatibility: Existing tmux configurations continue to work
✅ Full Test Coverage: 79 new tests ensuring both adapters work correctly

Changes

New Components

• src/shared/terminal-multiplexer/ - New abstraction layer
  • types.ts - Multiplexer interface and capabilities
  • tmux-adapter.ts - Tmux implementation (wraps existing tmux-utils)
  • zellij-adapter.ts - Zellij implementation with label-based pane tracking
  • detection.ts - Auto-detection logic
  • *.test.ts - 79 comprehensive tests (contract, unit, integration)

Modified Components

• src/features/tmux-subagent/manager.ts - Refactored to use Multiplexer abstraction
• src/hooks/interactive-bash-session/ - Updated for multiplexer type tracking
• src/config/schema.ts - Extended with terminal.provider configuration
• src/index.ts - Integrated detection and multiplexer creation
• Documentation - Updated src/shared/AGENTS.md and src/features/AGENTS.md

Technical Details

Architecture

interface Multiplexer {
  type: "tmux" | "zellij"
  capabilities: {
    manualLayout: boolean      // tmux: true, zellij: false
    persistentLabels: boolean  // tmux: false, zellij: true
  }
  spawnPane(options: SpawnOptions): Promise<PaneHandle>
  closePane(handle: PaneHandle): Promise<void>
  getPanes(): Promise<PaneHandle[]>
  ensureSession(name: string): Promise<void>
  killSession(name: string): Promise<void>
}

Detection Priority

1. $TMUX environment variable → "tmux"
2. $ZELLIJ or $ZELLIJ_SESSION_NAME → "zellij"
3. Binary detection (which tmux / which zellij)
4. Returns null if none found

Key Implementation Details

Zellij Adapter:

• Uses label-based pane tracking (zellij's native -n flag)
• Implements anchor pane system for tab-like stacking
• Auto-close via --close-on-exit flag + pkill -9 for opencode processes
• Pane ID capture via temp files with retry loop (handles race conditions)
• Critical fix: Escaped \$ZELLIJ_PANE_ID to evaluate inside pane, not parent shell

Tmux Adapter:

• Wraps existing tmux-utils for backward compatibility
• Maintains manual layout capabilities
• No breaking changes to existing tmux functionality

Configuration Example

{
  "terminal": {
    "provider": "auto",  // "auto" | "tmux" | "zellij"
    "tmux": {
      "enabled": true,
      "session_prefix": "omo-"
    },
    "zellij": {
      "enabled": true,
      "session_prefix": "omo-"
    }
  }
}

Testing

All 79 terminal-multiplexer tests pass:

• Contract tests (shared behavior)
• Tmux adapter tests
• Zellij adapter tests
• Detection logic tests
• Integration tests

bun test src/shared/terminal-multiplexer/
# 79 pass, 0 fail, 129 expect() calls

Breaking Changes

None. All changes are backward compatible. Existing tmux configurations continue to work without modification.

Verification

Manual testing verified:

• ✅ Pane spawning in both tmux and zellij
• ✅ Pane stacking (tab-like behavior)
• ✅ Auto-close when tasks complete
• ✅ Pane ID capture and tracking
• ✅ Background agent parallel execution
• ✅ Backward compatibility with existing tmux setups

---

Summary by cubic

Adds native Zellij support alongside tmux with a unified terminal multiplexer layer. Auto-detects the active multiplexer and applies consistent pane stacking and auto-close without breaking existing tmux setups.

• New Features

  • Unified multiplexer interface for tmux and zellij with auto-detection (env vars, binary check, cached)
  • New terminal.provider config (auto | tmux | zellij) plus terminal.tmux/zellij sub-config (enabled, session_prefix)
  • Pane stacking via an anchor pane; panes auto-close when tasks finish; Zellij state persists across restarts and is cleaned up on session deletion
  • Integrated into tmux-subagent and interactive-bash-session; session context threaded to adapters; multiplexer-aware state
  • 150+ new tests across adapters, detection, storage, and manager; docs updated

• Bug Fixes

  • Detect zellij in isInsideTmux and getCurrentPaneId
  • Ensure zellij panes auto-close; kill background processes when needed
  • Fix zellij pane ID race with a short retry loop; clear stale anchor state; stabilize test isolation

^{Written for commit 3848e91. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[mrdavidlaing]

I have read the CLA Document and I hereby sign the CLA

[cubic-dev-ai]

3 issues found across 26 files

Confidence score: 4/5

• Mostly test-only concerns with moderate severity, so this looks safe to merge with minimal risk to runtime behavior.
• src/shared/terminal-multiplexer/detection.test.ts and src/shared/tmux/tmux-utils.test.ts can leak TMUX/ZELLIJ env state between tests, which may cause flaky results when running under tmux/zellij.
• src/shared/terminal-multiplexer/tmux-adapter.test.ts leaves real tmux sessions behind, which could pollute subsequent test runs.
• Pay close attention to src/shared/terminal-multiplexer/detection.test.ts, src/shared/tmux/tmux-utils.test.ts, src/shared/terminal-multiplexer/tmux-adapter.test.ts - test isolation and cleanup behavior.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/shared/terminal-multiplexer/detection.test.ts">

<violation number="1" location="src/shared/terminal-multiplexer/detection.test.ts:9">
P2: Test deletes TMUX/ZELLIJ env vars without restoring originals, which can leak state into later tests or code in the same process (e.g., when running tests inside tmux/zellij).</violation>
</file>

<file name="src/shared/tmux/tmux-utils.test.ts">

<violation number="1" location="src/shared/tmux/tmux-utils.test.ts:27">
P2: afterEach restores env vars by assignment even when originally undefined, which can leave `TMUX`/`ZELLIJ` set to a truthy string value and pollute later tests.</violation>
</file>

<file name="src/shared/terminal-multiplexer/tmux-adapter.test.ts">

<violation number="1" location="src/shared/terminal-multiplexer/tmux-adapter.test.ts:156">
P2: Tests create real tmux sessions via ensureSession without any cleanup, leaving orphaned sessions and potentially leaking state across runs.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}