ac-framework 1.9.8 → 1.9.9

package/README.md

@@ -6,7 +6,7 @@ It combines three layers in one CLI:
 - template-based assistant configurations for multiple IDEs and AI CLIs
 - a built-in spec-driven workflow inspired by OpenSpec / spec-driven development
 - a persistent local memory system with MCP integration for supported assistants
-- an optional collaborative multi-agent runtime powered by OpenCode + tmux
+- an optional collaborative multi-agent runtime powered by OpenCode + zellij (tmux fallback)
 
 ## Why AC Framework
 
@@ -26,7 +26,7 @@ The goal is simple: help AI write better code, with more context, more disciplin
 - `Spec-driven workflow` - use `acfm spec` to initialize, create, validate, continue, and archive structured changes.
 - `Persistent memory` - store architectural decisions, bugfixes, refactors, conventions, and context in a local SQLite memory database.
 - `MCP integration` - connect the memory system to supported assistants through MCP so they can recall and save context directly.
-- `Collaborative agents (optional)` - enable SynapseGrid to run planner/critic/coder/reviewer in coordinated tmux panes with shared context.
+- `Collaborative agents (optional)` - enable SynapseGrid to run planner/critic/coder/reviewer in coordinated zellij panes (tmux fallback) with shared context.
 - `GitHub sync` - use `acfm init --latest` or `acfm update` to pull the latest framework content from GitHub.
 - `Legacy compatibility` - `.acfm/` is the new default, but existing `openspec/` directories still work.
 
@@ -57,7 +57,7 @@ The CLI now guides you through:
 2. choose one or more assistants from that template
 3. install the matching root instruction files like `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `copilot-instructions.md`
 4. optionally initialize NexusVault persistent memory and MCP connections
-5. optionally enable SynapseGrid collaborative agents (auto-installs OpenCode + tmux)
+5. optionally enable SynapseGrid collaborative agents (auto-installs OpenCode + zellij/tmux)
 
 If enabled, `acfm init` also auto-installs the optional SynapseGrid MCP server into detected assistants.
 
@@ -130,7 +130,7 @@ Some assistants include bundled companions automatically:
 
 ### Collaborative Agents (Optional)
 
-SynapseGrid is an optional collaborative runtime that coordinates 4 OpenCode-backed roles in tmux panes:
+SynapseGrid is an optional collaborative runtime that coordinates 4 OpenCode-backed roles in multiplexer panes (zellij preferred, tmux fallback):
 - planner
 - critic
 - coder
@@ -140,15 +140,18 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 
 | Command | Description |
 |---|---|
-| `acfm agents setup` | Install optional dependencies (`opencode` and `tmux`) |
-| `acfm agents doctor` | Validate OpenCode/tmux/model preflight before start |
+| `acfm agents setup` | Install optional dependencies (`opencode` and `zellij`/`tmux`) |
+| `acfm agents doctor` | Validate OpenCode/multiplexer/model preflight before start |
 | `acfm agents install-mcps` | Install SynapseGrid MCP server for detected assistants |
 | `acfm agents uninstall-mcps` | Remove SynapseGrid MCP server from assistants |
 | `acfm agents start --task "..." --model-coder provider/model` | Start session with optional per-role models |
+| `acfm agents start --task "..." --mux zellij` | Start session forcing zellij backend (`auto`/`tmux` also supported) |
+| `acfm agents runtime get` | Show configured multiplexer backend (`auto`, `zellij`, `tmux`) |
+| `acfm agents runtime set zellij` | Persist preferred multiplexer backend |
 | `acfm agents resume` | Resume a previous session and recreate workers if needed |
 | `acfm agents list` | List recent SynapseGrid sessions |
-| `acfm agents attach` | Attach directly to the SynapseGrid tmux session |
-| `acfm agents live` | Attach to full live tmux view (all agents) |
+| `acfm agents attach` | Attach directly to the active SynapseGrid multiplexer session |
+| `acfm agents live` | Attach to full live multiplexer view (all agents) |
 | `acfm agents logs` | Show recent worker logs (all roles or one role) |
 | `acfm agents transcript --role all --limit 40` | Show captured cross-agent transcript |
 | `acfm agents summary` | Show generated collaboration meeting summary |
@@ -166,7 +169,7 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 
 When driving SynapseGrid from another agent via MCP, prefer asynchronous run tools over role-by-role stepping:
 
-- `collab_start_session` to initialize session and optional tmux workers
+- `collab_start_session` to initialize session and optional zellij/tmux workers
 - `collab_invoke_team` to launch full 4-role collaboration run
 - `collab_wait_run` to wait for completion/failure with bounded timeout
 - `collab_get_result` to fetch final consolidated output and run diagnostics
@@ -180,7 +183,7 @@ When driving SynapseGrid from another agent via MCP, prefer asynchronous run too
 - Attach to worker panes with `acfm agents live` (or `acfm agents attach`) to see real-time role discussion.
 - Inspect worker errors quickly with `acfm agents logs --role all --lines 120`.
 - Inspect collaborative discussion with `acfm agents transcript` and `acfm agents summary`.
-- MCP starts can now create tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
+- MCP starts can now create zellij/tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
 - Configure role models directly at start (for example `--model-planner`, `--model-coder`) or persist defaults via `acfm agents model choose` / `acfm agents model set`.
 - Default SynapseGrid model fallback is `opencode/mimo-v2-pro-free`.
 - Run `acfm agents doctor` when panes look idle to confirm model/provider preflight health.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-framework",
-  "version": "1.9.8",
+  "version": "1.9.9",
   "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
   "main": "src/index.js",
   "exports": {

package/src/agents/config-store.js

@@ -10,10 +10,13 @@ const CONFIG_PATH = join(ACFM_DIR, 'config.json');
 
 function normalizeConfig(raw) {
   const agents = raw?.agents && typeof raw.agents === 'object' ? raw.agents : {};
+  const configuredMultiplexer = typeof agents.multiplexer === 'string' ? agents.multiplexer.trim().toLowerCase() : '';
+  const multiplexer = ['auto', 'zellij', 'tmux'].includes(configuredMultiplexer) ? configuredMultiplexer : 'auto';
   return {
     agents: {
       defaultModel: normalizeModelId(agents.defaultModel) || DEFAULT_SYNAPSE_MODEL,
       defaultRoleModels: sanitizeRoleModels(agents.defaultRoleModels),
+      multiplexer,
     },
   };
 }

package/src/agents/orchestrator.js

@@ -19,6 +19,20 @@ import {
   withSessionLock,
 } from './state-store.js';
 
+async function finalizeSessionArtifacts(state) {
+  const runState = ensureRunState(state);
+  const summaryMd = buildMeetingSummary(state.messages, runState, runState.sharedContext);
+  await writeMeetingSummary(state.sessionId, summaryMd);
+  const completedRun = {
+    ...runState,
+    finalSummary: extractFinalSummary(state.messages, runState),
+  };
+  return saveSessionState({
+    ...state,
+    run: completedRun,
+  });
+}
+
 function buildRuntimePrompt({ state, role }) {
   const roleContext = ROLE_SYSTEM_PROMPTS[role] || '';
   const collaborativePrompt = buildAgentPrompt({
@@ -63,6 +77,13 @@ function ensureRunState(state) {
     round: state.round || 1,
     events: [],
     finalSummary: null,
+    sharedContext: {
+      decisions: [],
+      openIssues: [],
+      risks: [],
+      actionItems: [],
+      notes: [],
+    },
     lastError: null,
     policy: {
       timeoutPerRoleMs: 180000,
@@ -141,6 +162,7 @@ export async function runTurn(sessionId, options = {}) {
     if (shouldStop(state)) {
       if (state.status === 'running') {
         state = await stopSession(state, 'completed');
+        state = await finalizeSessionArtifacts(state);
       }
       return state;
     }
@@ -178,6 +200,7 @@ export async function runTurn(sessionId, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      state = await finalizeSessionArtifacts(state);
     }
 
     return state;
@@ -244,6 +267,7 @@ export async function executeActiveTurn(sessionId, role, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      state = await finalizeSessionArtifacts(state);
     }
 
     return state;
@@ -332,6 +356,9 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
         events: outputEvents,
       }));
       state = await saveSessionState(applyRoleFailurePolicy(state, role, errorMessage));
+      if (state.status === 'failed') {
+        state = await finalizeSessionArtifacts(state);
+      }
       return state;
     }
 
@@ -360,8 +387,6 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
-      const summaryMd = buildMeetingSummary(state.messages, ensureRunState(state), ensureRunState(state).sharedContext);
-      await writeMeetingSummary(sessionId, summaryMd);
       const finalRun = appendRunEvent({
         ...ensureRunState(state),
         status: 'completed',
@@ -372,6 +397,7 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
         ...state,
         run: finalRun,
       });
+      state = await finalizeSessionArtifacts(state);
     }
 
     return state;

package/src/agents/runtime.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { writeFile } from 'node:fs/promises';
 import { COLLAB_ROLES } from './constants.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -10,7 +11,7 @@ export function roleLogPath(sessionDir, role) {
   return resolve(sessionDir, `${role}.log`);
 }
 
-export function runTmux(command, args, options = {}) {
+function runCommand(command, args, options = {}) {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(command, args, {
       cwd: options.cwd || process.cwd(),
@@ -42,6 +43,14 @@ export function runTmux(command, args, options = {}) {
   });
 }
 
+function workerCommand(sessionId, role, roleLog) {
+  return `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"'`;
+}
+
+export async function runTmux(command, args, options = {}) {
+  return runCommand(command, args, options);
+}
+
 export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
   const role0 = COLLAB_ROLES[0];
   const role0Log = roleLogPath(sessionDir, role0);
@@ -52,7 +61,7 @@ export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
     sessionName,
     '-n',
     role0,
-    `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role0} 2>&1 | tee -a "${role0Log}"'`,
+    workerCommand(sessionId, role0, role0Log),
   ]);
 
   for (let idx = 1; idx < COLLAB_ROLES.length; idx += 1) {
@@ -63,7 +72,7 @@ export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
       '-t',
       sessionName,
       '-v',
-      `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"'`,
+      workerCommand(sessionId, role, roleLog),
     ]);
   }
 
@@ -80,3 +89,66 @@ export async function tmuxSessionExists(sessionName) {
     return false;
   }
 }
+
+async function writeZellijLayout({ layoutPath, sessionId, sessionDir }) {
+  const panes = COLLAB_ROLES.map((role) => {
+    const roleLog = roleLogPath(sessionDir, role);
+    const cmd = workerCommand(sessionId, role, roleLog).replace(/"/g, '\\"');
+    return `                    pane name="${role}" command="bash" args { "-lc" "${cmd}" }`;
+  });
+
+  const content = [
+    'layout {',
+    '    default_tab_template {',
+    '        tab name="SynapseGrid" {',
+    '            pane split_direction="vertical" {',
+    '                pane split_direction="horizontal" {',
+    panes[0],
+    panes[1],
+    '                }',
+    '                pane split_direction="horizontal" {',
+    panes[2],
+    panes[3],
+    '                }',
+    '            }',
+    '        }',
+    '    }',
+    '}',
+    '',
+  ].join('\n');
+
+  await writeFile(layoutPath, content, 'utf8');
+}
+
+export async function spawnZellijSession({ sessionName, sessionDir, sessionId }) {
+  const layoutPath = resolve(sessionDir, 'synapsegrid-layout.kdl');
+  await writeZellijLayout({ layoutPath, sessionId, sessionDir });
+  await runCommand('zellij', ['--session', sessionName, '--layout', layoutPath, '--detach']);
+  return { layoutPath };
+}
+
+export async function zellijSessionExists(sessionName) {
+  try {
+    const result = await runCommand('zellij', ['list-sessions']);
+    const lines = result.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+    return lines.some((line) => line === sessionName || line.startsWith(`${sessionName} `));
+  } catch {
+    return false;
+  }
+}
+
+export async function runZellij(args, options = {}) {
+  return runCommand('zellij', args, options);
+}
+
+export function resolveMultiplexer(preferred = 'auto', hasTmuxCommand = false, hasZellijCommand = false) {
+  if (preferred === 'tmux') {
+    return hasTmuxCommand ? 'tmux' : null;
+  }
+  if (preferred === 'zellij') {
+    return hasZellijCommand ? 'zellij' : null;
+  }
+  if (hasZellijCommand) return 'zellij';
+  if (hasTmuxCommand) return 'tmux';
+  return null;
+}

package/src/agents/state-store.js

@@ -73,6 +73,8 @@ function initialState(task, options = {}) {
     model: options.model || null,
     roleModels: sanitizeRoleModels(options.roleModels),
     opencodeBin: options.opencodeBin || null,
+    multiplexer: options.multiplexer || 'auto',
+    multiplexerSessionName: options.multiplexerSessionName || null,
     tmuxSessionName: options.tmuxSessionName || null,
     run: createRunState(options.runPolicy, Number.isInteger(options.maxRounds) ? options.maxRounds : DEFAULT_MAX_ROUNDS),
     messages: [
@@ -208,6 +210,8 @@ export async function listSessions(limit = 20) {
         round: state.round,
         maxRounds: state.maxRounds,
         tmuxSessionName: state.tmuxSessionName || null,
+        multiplexer: state.multiplexer || 'auto',
+        multiplexerSessionName: state.multiplexerSessionName || null,
         createdAt: state.createdAt,
         updatedAt: state.updatedAt,
         mtime: stateStats.mtimeMs,

package/src/commands/agents.js

@@ -26,8 +26,18 @@ import {
   saveSessionState,
   setCurrentSession,
   stopSession,
+  writeMeetingSummary,
 } from '../agents/state-store.js';
-import { roleLogPath, runTmux, spawnTmuxSession, tmuxSessionExists } from '../agents/runtime.js';
+import {
+  roleLogPath,
+  runTmux,
+  runZellij,
+  spawnTmuxSession,
+  spawnZellijSession,
+  tmuxSessionExists,
+  zellijSessionExists,
+  resolveMultiplexer,
+} from '../agents/runtime.js';
 import { getAgentsConfigPath, loadAgentsConfig, updateAgentsConfig } from '../agents/config-store.js';
 import {
   buildEffectiveRoleModels,
@@ -60,18 +70,53 @@ async function ensureSessionId(required = true) {
 function printStartSummary(state) {
   console.log(chalk.green(`✓ ${COLLAB_SYSTEM_NAME} session started`));
   console.log(chalk.dim(`  Session: ${state.sessionId}`));
-  console.log(chalk.dim(`  tmux: ${state.tmuxSessionName}`));
+  const multiplexer = state.multiplexer || 'auto';
+  const muxSessionName = state.multiplexerSessionName || state.tmuxSessionName || '-';
+  console.log(chalk.dim(`  Multiplexer: ${multiplexer}`));
+  console.log(chalk.dim(`  Session name: ${muxSessionName}`));
   console.log(chalk.dim(`  Task: ${state.task}`));
   console.log(chalk.dim(`  Roles: ${state.roles.join(', ')}`));
   console.log();
   console.log(chalk.cyan('Attach with:'));
-  console.log(chalk.white(`  tmux attach -t ${state.tmuxSessionName}`));
+  if (multiplexer === 'zellij') {
+    console.log(chalk.white(`  zellij attach ${muxSessionName}`));
+  } else {
+    console.log(chalk.white(`  tmux attach -t ${muxSessionName}`));
+  }
   console.log(chalk.white('  acfm agents live'));
   console.log();
   console.log(chalk.cyan('Interact with:'));
   console.log(chalk.white('  acfm agents send "your message"'));
 }
 
+function validateMultiplexer(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!['auto', 'zellij', 'tmux'].includes(normalized)) {
+    throw new Error('--mux must be one of: auto|zellij|tmux');
+  }
+  return normalized;
+}
+
+function sessionMuxName(state) {
+  return state.multiplexerSessionName || state.tmuxSessionName || `acfm-synapse-${state.sessionId.slice(0, 8)}`;
+}
+
+async function sessionExistsForMux(multiplexer, sessionName) {
+  if (multiplexer === 'zellij') return zellijSessionExists(sessionName);
+  return tmuxSessionExists(sessionName);
+}
+
+async function attachToMux(multiplexer, sessionName, readonly = false) {
+  if (multiplexer === 'zellij') {
+    await runZellij(['attach', sessionName], { stdio: 'inherit' });
+    return;
+  }
+  const args = ['attach'];
+  if (readonly) args.push('-r');
+  args.push('-t', sessionName);
+  await runTmux('tmux', args, { stdio: 'inherit' });
+}
+
 function toMarkdownTranscript(state, transcript) {
   const displayedRound = Math.min(state.round, state.maxRounds);
   const lines = [
@@ -181,12 +226,51 @@ export function agentsCommand() {
   const agents = new Command('agents')
     .description(`${COLLAB_SYSTEM_NAME} — collaborative multi-agent system powered by OpenCode`);
 
+  agents.addHelpText('after', `
+Examples:
+  acfm agents start --task "Implement auth flow" --mux auto
+  acfm agents setup
+  acfm agents runtime get
+  acfm agents runtime set zellij
+  acfm agents model choose
+  acfm agents model list
+  acfm agents transcript --role all --limit 40
+  acfm agents summary
+  acfm agents export --format md --out ./session.md
+`);
+
   agents
     .command('setup')
-    .description('Install optional collaboration dependencies (OpenCode + tmux)')
+    .description('Install optional collaboration dependencies (OpenCode + zellij/tmux)')
+    .option('--yes', 'Install dependencies without interactive confirmation', false)
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-      const result = ensureCollabDependencies();
+      let installZellij = true;
+      let installTmux = true;
+
+      if (!opts.yes && !opts.json) {
+        const answers = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'installZellij',
+            message: 'Install zellij (recommended, multiplatform backend)?',
+            default: true,
+          },
+          {
+            type: 'confirm',
+            name: 'installTmux',
+            message: 'Install tmux as fallback backend?',
+            default: true,
+          },
+        ]);
+        installZellij = Boolean(answers.installZellij);
+        installTmux = Boolean(answers.installTmux);
+      }
+
+      const result = ensureCollabDependencies({
+        installZellij,
+        installTmux,
+      });
       let collabMcp = null;
 
       if (result.success) {
@@ -199,7 +283,9 @@ export function agentsCommand() {
       if (!opts.json) {
         const oLabel = result.opencode.success ? chalk.green('ok') : chalk.red('failed');
         const tLabel = result.tmux.success ? chalk.green('ok') : chalk.red('failed');
+        const zLabel = result.zellij.success ? chalk.green('ok') : chalk.red('failed');
         console.log(`OpenCode: ${oLabel} - ${result.opencode.message}`);
+        console.log(`zellij:   ${zLabel} - ${result.zellij.message}`);
         console.log(`tmux:     ${tLabel} - ${result.tmux.message}`);
         if (collabMcp) {
           console.log(`Collab MCP: ${chalk.green('ok')} - installed ${collabMcp.success}/${collabMcp.installed} on detected assistants`);
@@ -286,10 +372,10 @@ export function agentsCommand() {
           }
           console.log(chalk.bold('SynapseGrid Sessions'));
           for (const item of sessions) {
-            console.log(
+          console.log(
               `${chalk.cyan(item.sessionId.slice(0, 8))}  ${item.status.padEnd(10)}  ` +
               `round ${String(item.round).padStart(2)}/${String(item.maxRounds).padEnd(2)}  ` +
-              `${item.tmuxSessionName || '-'}  ${item.task}`
+              `${item.multiplexer || 'auto'}:${item.multiplexerSessionName || item.tmuxSessionName || '-'}  ${item.task}`
             );
           }
         }
@@ -302,15 +388,17 @@ export function agentsCommand() {
 
   agents
     .command('attach')
-    .description('Attach terminal to active SynapseGrid tmux session')
+    .description('Attach terminal to active SynapseGrid multiplexer session')
     .action(async () => {
       try {
         const sessionId = await ensureSessionId(true);
         const state = await loadSessionState(sessionId);
-        if (!state.tmuxSessionName) {
-          throw new Error('No tmux session registered for active collaborative session');
+        const multiplexer = state.multiplexer || 'tmux';
+        const muxSessionName = sessionMuxName(state);
+        if (!muxSessionName) {
+          throw new Error('No multiplexer session registered for active collaborative session');
         }
-        await runTmux('tmux', ['attach', '-t', state.tmuxSessionName], { stdio: 'inherit' });
+        await attachToMux(multiplexer, muxSessionName, false);
       } catch (error) {
         console.error(chalk.red(`Error: ${error.message}`));
         process.exit(1);
@@ -319,23 +407,22 @@ export function agentsCommand() {
 
   agents
     .command('live')
-    .description('Attach to live tmux collaboration view (all agent panes)')
+    .description('Attach to live collaboration view (all agent panes)')
     .option('--readonly', 'Attach in read-only mode', false)
     .action(async (opts) => {
       try {
         const sessionId = await ensureSessionId(true);
         const state = await loadSessionState(sessionId);
-        if (!state.tmuxSessionName) {
-          throw new Error('No tmux session registered for active collaborative session');
+        const multiplexer = state.multiplexer || 'tmux';
+        const muxSessionName = sessionMuxName(state);
+        if (!muxSessionName) {
+          throw new Error('No multiplexer session registered for active collaborative session');
         }
-        const tmuxExists = await tmuxSessionExists(state.tmuxSessionName);
-        if (!tmuxExists) {
-          throw new Error(`tmux session ${state.tmuxSessionName} no longer exists. Run: acfm agents resume`);
+        const sessionExists = await sessionExistsForMux(multiplexer, muxSessionName);
+        if (!sessionExists) {
+          throw new Error(`${multiplexer} session ${muxSessionName} no longer exists. Run: acfm agents resume`);
         }
-        const args = ['attach'];
-        if (opts.readonly) args.push('-r');
-        args.push('-t', state.tmuxSessionName);
-        await runTmux('tmux', args, { stdio: 'inherit' });
+        await attachToMux(multiplexer, muxSessionName, Boolean(opts.readonly));
       } catch (error) {
         console.error(chalk.red(`Error: ${error.message}`));
         process.exit(1);
@@ -344,48 +431,60 @@ export function agentsCommand() {
 
   agents
     .command('resume')
-    .description('Resume a previous session and optionally recreate tmux workers')
+    .description('Resume a previous session and optionally recreate multiplexer workers')
     .option('--session <id>', 'Session ID to resume (defaults to current)')
-    .option('--no-recreate', 'Do not recreate tmux session/workers when missing')
-    .option('--no-attach', 'Do not attach tmux after resume')
+    .option('--no-recreate', 'Do not recreate multiplexer session/workers when missing')
+    .option('--no-attach', 'Do not attach multiplexer after resume')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
       try {
         const sessionId = opts.session || await ensureSessionId(true);
         let state = await loadSessionState(sessionId);
+        const multiplexer = state.multiplexer || 'tmux';
 
-        const tmuxSessionName = state.tmuxSessionName || `acfm-synapse-${state.sessionId.slice(0, 8)}`;
-        const tmuxExists = hasCommand('tmux') ? await tmuxSessionExists(tmuxSessionName) : false;
+        if (multiplexer === 'zellij' && !hasCommand('zellij')) {
+          throw new Error('zellij is not installed. Run: acfm agents setup');
+        }
+        if (multiplexer === 'tmux' && !hasCommand('tmux')) {
+          throw new Error('tmux is not installed. Run: acfm agents setup');
+        }
 
-        if (!tmuxExists && opts.recreate) {
-          if (!hasCommand('tmux')) {
-            throw new Error('tmux is not installed. Run: acfm agents setup');
-          }
+        const muxSessionName = sessionMuxName(state);
+        const muxExists = await sessionExistsForMux(multiplexer, muxSessionName);
+
+        if (!muxExists && opts.recreate) {
           const sessionDir = getSessionDir(state.sessionId);
-          await spawnTmuxSession({ sessionName: tmuxSessionName, sessionDir, sessionId: state.sessionId });
+          if (multiplexer === 'zellij') {
+            await spawnZellijSession({ sessionName: muxSessionName, sessionDir, sessionId: state.sessionId });
+          } else {
+            await spawnTmuxSession({ sessionName: muxSessionName, sessionDir, sessionId: state.sessionId });
+          }
         }
 
         state = await saveSessionState({
           ...state,
           status: 'running',
-          tmuxSessionName,
+          multiplexer,
+          multiplexerSessionName: muxSessionName,
+          tmuxSessionName: multiplexer === 'tmux' ? muxSessionName : (state.tmuxSessionName || null),
         });
         await setCurrentSession(state.sessionId);
 
         output({
           sessionId: state.sessionId,
           status: state.status,
-          tmuxSessionName,
-          recreatedTmux: !tmuxExists && Boolean(opts.recreate),
+          multiplexer,
+          multiplexerSessionName: muxSessionName,
+          recreatedSession: !muxExists && Boolean(opts.recreate),
         }, opts.json);
 
         if (!opts.json) {
           console.log(chalk.green(`✓ Resumed session ${state.sessionId}`));
-          console.log(chalk.dim(`  tmux: ${tmuxSessionName}`));
+          console.log(chalk.dim(`  ${multiplexer}: ${muxSessionName}`));
         }
 
         if (opts.attach) {
-          await runTmux('tmux', ['attach', '-t', tmuxSessionName], { stdio: 'inherit' });
+          await attachToMux(multiplexer, muxSessionName, false);
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -453,6 +552,77 @@ export function agentsCommand() {
     .command('model')
     .description('Manage default SynapseGrid model configuration');
 
+  const runtime = agents
+    .command('runtime')
+    .description('Manage SynapseGrid runtime backend settings');
+
+  runtime
+    .command('get')
+    .description('Show configured multiplexer backend')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const cfg = await loadAgentsConfig();
+        const configured = validateMultiplexer(cfg.agents.multiplexer || 'auto');
+        const resolved = resolveMultiplexer(configured, hasCommand('tmux'), hasCommand('zellij'));
+        const payload = {
+          configPath: getAgentsConfigPath(),
+          multiplexer: configured,
+          resolved,
+          available: {
+            zellij: hasCommand('zellij'),
+            tmux: hasCommand('tmux'),
+          },
+        };
+        output(payload, opts.json);
+        if (!opts.json) {
+          console.log(chalk.bold('SynapseGrid runtime backend'));
+          console.log(chalk.dim(`Config: ${payload.configPath}`));
+          console.log(chalk.dim(`Configured: ${configured}`));
+          console.log(chalk.dim(`Resolved: ${resolved || 'none'}`));
+          console.log(chalk.dim(`zellij=${payload.available.zellij} tmux=${payload.available.tmux}`));
+        }
+      } catch (error) {
+        output({ error: error.message }, opts.json);
+        if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
+  runtime
+    .command('set <mux>')
+    .description('Set multiplexer backend: auto|zellij|tmux')
+    .option('--json', 'Output as JSON')
+    .action(async (mux, opts) => {
+      try {
+        const selected = validateMultiplexer(mux);
+        const updated = await updateAgentsConfig((current) => ({
+          agents: {
+            defaultModel: current.agents.defaultModel,
+            defaultRoleModels: { ...current.agents.defaultRoleModels },
+            multiplexer: selected,
+          },
+        }));
+        const resolved = resolveMultiplexer(updated.agents.multiplexer, hasCommand('tmux'), hasCommand('zellij'));
+        const payload = {
+          success: true,
+          configPath: getAgentsConfigPath(),
+          multiplexer: updated.agents.multiplexer,
+          resolved,
+        };
+        output(payload, opts.json);
+        if (!opts.json) {
+          console.log(chalk.green('✓ SynapseGrid runtime backend updated'));
+          console.log(chalk.dim(`  Configured: ${payload.multiplexer}`));
+          console.log(chalk.dim(`  Resolved: ${payload.resolved || 'none'}`));
+        }
+      } catch (error) {
+        output({ error: error.message }, opts.json);
+        if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
   model
     .command('list')
     .description('List available OpenCode models grouped by provider')
@@ -510,6 +680,7 @@ export function agentsCommand() {
           configPath: getAgentsConfigPath(),
           defaultModel: config.agents.defaultModel,
           defaultRoleModels: config.agents.defaultRoleModels,
+          multiplexer: config.agents.multiplexer,
         };
         output(payload, opts.json);
         if (!opts.json) {
@@ -519,6 +690,7 @@ export function agentsCommand() {
           for (const role of COLLAB_ROLES) {
             console.log(chalk.dim(`- ${role}: ${payload.defaultRoleModels[role] || '(none)'}`));
           }
+          console.log(chalk.dim(`Multiplexer: ${payload.multiplexer || 'auto'}`));
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -594,6 +766,7 @@ export function agentsCommand() {
             agents: {
               defaultModel: current.agents.defaultModel,
               defaultRoleModels: { ...current.agents.defaultRoleModels },
+              multiplexer: current.agents.multiplexer || 'auto',
             },
           };
 
@@ -654,6 +827,7 @@ export function agentsCommand() {
             agents: {
               defaultModel: current.agents.defaultModel,
               defaultRoleModels: { ...current.agents.defaultRoleModels },
+              multiplexer: current.agents.multiplexer || 'auto',
             },
           };
           if (role === 'all') {
@@ -702,6 +876,7 @@ export function agentsCommand() {
             agents: {
               defaultModel: current.agents.defaultModel,
               defaultRoleModels: { ...current.agents.defaultRoleModels },
+              multiplexer: current.agents.multiplexer || 'auto',
             },
           };
           if (role === 'all') {
@@ -865,17 +1040,15 @@ export function agentsCommand() {
     .option('--model-critic <id>', 'Model for critic role (provider/model)')
     .option('--model-coder <id>', 'Model for coder role (provider/model)')
     .option('--model-reviewer <id>', 'Model for reviewer role (provider/model)')
+    .option('--mux <name>', 'Multiplexer backend: auto|zellij|tmux')
     .option('--cwd <path>', 'Working directory for agents', process.cwd())
-    .option('--attach', 'Attach tmux immediately after start', false)
+    .option('--attach', 'Attach multiplexer immediately after start', false)
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
       try {
         if (!hasCommand('opencode')) {
           throw new Error('OpenCode is not installed. Run: acfm agents setup');
         }
-        if (!hasCommand('tmux')) {
-          throw new Error('tmux is not installed. Run: acfm agents setup');
-        }
         const opencodeBin = resolveCommandPath('opencode');
         if (!opencodeBin) {
           throw new Error('OpenCode binary not found. Run: acfm agents setup');
@@ -888,6 +1061,11 @@ export function agentsCommand() {
         }
 
         const config = await loadAgentsConfig();
+        const configuredMux = validateMultiplexer(opts.mux || config.agents.multiplexer || 'auto');
+        const selectedMux = resolveMultiplexer(configuredMux, hasCommand('tmux'), hasCommand('zellij'));
+        if (!selectedMux) {
+          throw new Error('No multiplexer found. Install zellij or tmux with: acfm agents setup');
+        }
         const cliModel = assertValidModelIdOrNull('--model', opts.model || null);
         const cliRoleModels = parseRoleModelOptions(opts);
         for (const [role, model] of Object.entries(cliRoleModels)) {
@@ -922,30 +1100,47 @@ export function agentsCommand() {
           maxRounds,
           model: globalModel,
           roleModels,
+          multiplexer: selectedMux,
           workingDirectory: resolve(opts.cwd),
           opencodeBin,
         });
-        const tmuxSessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
+        const muxSessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
         const sessionDir = getSessionDir(state.sessionId);
+
+        if (selectedMux === 'zellij') {
+          await spawnZellijSession({
+            sessionName: muxSessionName,
+            sessionDir,
+            sessionId: state.sessionId,
+          });
+        } else {
+          await spawnTmuxSession({
+            sessionName: muxSessionName,
+            sessionDir,
+            sessionId: state.sessionId,
+          });
+        }
+
         const updated = await saveSessionState({
           ...state,
-          tmuxSessionName,
-        });
-
-        await spawnTmuxSession({
-          sessionName: tmuxSessionName,
-          sessionDir,
-          sessionId: state.sessionId,
+          multiplexer: selectedMux,
+          multiplexerSessionName: muxSessionName,
+          tmuxSessionName: selectedMux === 'tmux' ? muxSessionName : null,
         });
 
-        output({ sessionId: updated.sessionId, tmuxSessionName, status: updated.status }, opts.json);
+        output({
+          sessionId: updated.sessionId,
+          multiplexer: selectedMux,
+          multiplexerSessionName: muxSessionName,
+          status: updated.status,
+        }, opts.json);
         if (!opts.json) {
           printStartSummary(updated);
           printModelConfig(updated);
         }
 
         if (opts.attach) {
-          await runTmux('tmux', ['attach', '-t', tmuxSessionName], { stdio: 'inherit' });
+          await attachToMux(selectedMux, muxSessionName, false);
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -996,14 +1191,16 @@ export function agentsCommand() {
             console.log(chalk.dim(`Run error: ${summary.lastError.message}`));
           }
           console.log(chalk.dim(`Global model: ${state.model || '(opencode default)'}`));
+          console.log(chalk.dim(`Multiplexer: ${state.multiplexer || 'auto'} (${sessionMuxName(state)})`));
           for (const role of COLLAB_ROLES) {
             const configured = state.roleModels?.[role] || '-';
             const effective = effectiveRoleModels[role] || '(opencode default)';
             console.log(chalk.dim(`  ${role.padEnd(8)} configured=${configured} effective=${effective}`));
           }
-          if (state.tmuxSessionName) {
-            console.log(chalk.dim(`tmux: ${state.tmuxSessionName}`));
-          }
+          const meetingLogPath = resolve(getSessionDir(state.sessionId), 'meeting-log.md');
+          const meetingSummaryPath = resolve(getSessionDir(state.sessionId), 'meeting-summary.md');
+          console.log(chalk.dim(`meeting-log: ${existsSync(meetingLogPath) ? meetingLogPath : 'not generated yet'}`));
+          console.log(chalk.dim(`meeting-summary: ${existsSync(meetingSummaryPath) ? meetingSummaryPath : 'not generated yet'}`));
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -1020,6 +1217,7 @@ export function agentsCommand() {
       try {
         const sessionId = await ensureSessionId(true);
         let state = await loadSessionState(sessionId);
+        const meetingSummaryPath = resolve(getSessionDir(state.sessionId), 'meeting-summary.md');
         state = await stopSession(state, 'stopped');
         if (state.run && state.run.status === 'running') {
           state = await saveSessionState({
@@ -1036,15 +1234,51 @@ export function agentsCommand() {
             },
           });
         }
-        if (state.tmuxSessionName && hasCommand('tmux')) {
+
+        if (!existsSync(meetingSummaryPath)) {
+          const fallbackSummary = [
+            '# SynapseGrid Meeting Summary',
+            '',
+            `Session: ${state.sessionId}`,
+            `Status: ${state.status}`,
+            '',
+            'This summary was auto-generated at stop time because the run did not complete normally.',
+            '',
+            '## Last message',
+            state.messages?.[state.messages.length - 1]?.content || '(none)',
+            '',
+          ].join('\n');
+          await writeMeetingSummary(state.sessionId, fallbackSummary);
+          if (state.run && !state.run.finalSummary) {
+            state = await saveSessionState({
+              ...state,
+              run: {
+                ...state.run,
+                finalSummary: fallbackSummary,
+              },
+            });
+          }
+        }
+
+        const multiplexer = state.multiplexer || 'tmux';
+        const muxSessionName = sessionMuxName(state);
+        if (multiplexer === 'zellij' && muxSessionName && hasCommand('zellij')) {
           try {
-            await runTmux('tmux', ['kill-session', '-t', state.tmuxSessionName]);
+            await runZellij(['delete-session', muxSessionName]);
+          } catch {
+            // ignore if already closed
+          }
+        }
+        if (multiplexer === 'tmux' && muxSessionName && hasCommand('tmux')) {
+          try {
+            await runTmux('tmux', ['kill-session', '-t', muxSessionName]);
           } catch {
             // ignore if already closed
           }
         }
         output({ sessionId: state.sessionId, status: state.status }, opts.json);
         if (!opts.json) console.log(chalk.green('✓ Collaborative session stopped'));
+
       } catch (error) {
         output({ error: error.message }, opts.json);
         if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
@@ -1142,11 +1376,17 @@ export function agentsCommand() {
       try {
         const opencodeBin = resolveCommandPath('opencode');
         const tmuxInstalled = hasCommand('tmux');
+        const zellijInstalled = hasCommand('zellij');
         const cfg = await loadAgentsConfig();
         const defaultModel = cfg.agents.defaultModel || DEFAULT_SYNAPSE_MODEL;
+        const configuredMux = validateMultiplexer(cfg.agents.multiplexer || 'auto');
+        const resolvedMux = resolveMultiplexer(configuredMux, tmuxInstalled, zellijInstalled);
         const result = {
           opencodeBin,
           tmuxInstalled,
+          zellijInstalled,
+          configuredMultiplexer: configuredMux,
+          resolvedMultiplexer: resolvedMux,
           defaultModel,
           defaultRoleModels: cfg.agents.defaultRoleModels,
           preflight: null,
@@ -1166,12 +1406,14 @@ export function agentsCommand() {
         if (!opts.json) {
           console.log(chalk.bold('SynapseGrid doctor'));
           console.log(chalk.dim(`opencode: ${opencodeBin || 'not found'}`));
+          console.log(chalk.dim(`zellij: ${zellijInstalled ? 'installed' : 'not installed'}`));
           console.log(chalk.dim(`tmux: ${tmuxInstalled ? 'installed' : 'not installed'}`));
+          console.log(chalk.dim(`multiplexer: configured=${configuredMux} resolved=${resolvedMux || 'none'}`));
           console.log(chalk.dim(`default model: ${defaultModel}`));
           console.log(chalk.dim(`preflight: ${result.preflight?.ok ? 'ok' : `failed - ${result.preflight?.error || 'unknown error'}`}`));
         }
 
-        if (!result.preflight?.ok) process.exit(1);
+        if (!result.preflight?.ok || !result.resolvedMultiplexer) process.exit(1);
       } catch (error) {
         output({ error: error.message }, opts.json);
         if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));

package/src/commands/init.js

@@ -156,7 +156,8 @@ async function setupPersistentMemory() {
 async function setupCollaborativeSystem() {
   const hasOpenCode = hasCommand('opencode');
   const hasTmux = hasCommand('tmux');
-  const alreadyReady = hasOpenCode && hasTmux;
+  const hasZellij = hasCommand('zellij');
+  const alreadyReady = hasOpenCode && (hasZellij || hasTmux);
 
   console.log();
   await animatedSeparator(60);
@@ -168,10 +169,10 @@ async function setupCollaborativeSystem() {
   console.log(
     chalk.hex('#636E72')(
       `  ${COLLAB_SYSTEM_NAME} launches a real-time collaborative agent war-room with\n` +
-      '  4 coordinated roles (planner, critic, coder, reviewer) in tmux panes.\n\n' +
+      '  4 coordinated roles (planner, critic, coder, reviewer) in multiplexer panes.\n\n' +
       '  Each round is turn-based with shared incremental context, so every\n' +
       '  contribution from one agent is fed to the next, not isolated fan-out.\n\n' +
-      `  Dependencies: ${chalk.hex('#DFE6E9')('OpenCode')} + ${chalk.hex('#DFE6E9')('tmux')}`
+      `  Dependencies: ${chalk.hex('#DFE6E9')('OpenCode')} + ${chalk.hex('#DFE6E9')('zellij')} (${chalk.hex('#DFE6E9')('tmux')} fallback)`
     )
   );
   console.log();
@@ -223,7 +224,8 @@ async function setupCollaborativeSystem() {
 
   if (alreadyReady) {
     console.log();
-    console.log(chalk.hex('#00B894')('  ◆ OpenCode and tmux are already available.'));
+    const mux = hasZellij ? 'zellij' : 'tmux';
+    console.log(chalk.hex('#00B894')(`  ◆ OpenCode and ${mux} are already available.`));
     await installCollabMcpConnections();
     console.log(chalk.hex('#636E72')('  Run `acfm agents start --task "..."` to launch collaboration.'));
     console.log();
@@ -234,11 +236,13 @@ async function setupCollaborativeSystem() {
   console.log(chalk.hex('#B2BEC3')(`  Installing ${COLLAB_SYSTEM_NAME} dependencies...`));
   console.log();
 
-  const result = ensureCollabDependencies();
+  const result = ensureCollabDependencies({ installZellij: true, installTmux: true });
 
   const oColor = result.opencode.success ? chalk.hex('#00B894') : chalk.hex('#D63031');
+  const zColor = result.zellij.success ? chalk.hex('#00B894') : chalk.hex('#D63031');
   const tColor = result.tmux.success ? chalk.hex('#00B894') : chalk.hex('#D63031');
   console.log(oColor(`  ◆ OpenCode: ${result.opencode.message}`));
+  console.log(zColor(`  ◆ zellij: ${result.zellij.message}`));
   console.log(tColor(`  ◆ tmux: ${result.tmux.message}`));
   console.log();
 

package/src/mcp/collab-server.js

@@ -17,7 +17,13 @@ import { COLLAB_ROLES } from '../agents/constants.js';
 import { buildEffectiveRoleModels, sanitizeRoleModels } from '../agents/model-selection.js';
 import { runWorkerIteration } from '../agents/orchestrator.js';
 import { getSessionDir } from '../agents/state-store.js';
-import { spawnTmuxSession, tmuxSessionExists } from '../agents/runtime.js';
+import {
+  spawnTmuxSession,
+  spawnZellijSession,
+  tmuxSessionExists,
+  zellijSessionExists,
+  resolveMultiplexer,
+} from '../agents/runtime.js';
 import {
   addUserMessage,
   createSession,
@@ -29,6 +35,7 @@ import {
   stopSession,
 } from '../agents/state-store.js';
 import { hasCommand, resolveCommandPath } from '../services/dependency-installer.js';
+import { loadAgentsConfig } from '../agents/config-store.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const runnerPath = resolve(__dirname, '../../bin/acfm.js');
@@ -67,6 +74,11 @@ function launchAutopilot(sessionId) {
   child.unref();
 }
 
+async function muxExists(multiplexer, sessionName) {
+  if (multiplexer === 'zellij') return zellijSessionExists(sessionName);
+  return tmuxSessionExists(sessionName);
+}
+
 class MCPCollabServer {
   constructor() {
     this.server = new McpServer({
@@ -92,7 +104,7 @@ class MCPCollabServer {
           reviewer: z.string().optional(),
         }).partial().optional().describe('Optional per-role models (provider/model)'),
         cwd: z.string().optional().describe('Working directory for agents'),
-        spawnWorkers: z.boolean().default(true).describe('Create tmux workers and panes'),
+        spawnWorkers: z.boolean().default(true).describe('Create multiplexer workers and panes'),
         runPolicy: z.object({
           timeoutPerRoleMs: z.number().int().positive().optional(),
           retryOnTimeout: z.number().int().min(0).optional(),
@@ -107,8 +119,11 @@ class MCPCollabServer {
             throw new Error('OpenCode binary not found in PATH. Run: acfm agents setup');
           }
 
-          if (spawnWorkers && !hasCommand('tmux')) {
-            throw new Error('tmux is not installed. Run: acfm agents setup');
+          const config = await loadAgentsConfig();
+          const configuredMux = config.agents.multiplexer || 'auto';
+          const multiplexer = resolveMultiplexer(configuredMux, hasCommand('tmux'), hasCommand('zellij'));
+          if (spawnWorkers && !multiplexer) {
+            throw new Error('No multiplexer found (zellij/tmux). Run: acfm agents setup');
           }
 
           const state = await createSession(task, {
@@ -119,18 +134,31 @@ class MCPCollabServer {
             workingDirectory,
             opencodeBin,
             runPolicy,
+            multiplexer: multiplexer || configuredMux,
           });
           let updated = state;
           if (spawnWorkers) {
-            const tmuxSessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
+            const sessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
             const sessionDir = getSessionDir(state.sessionId);
-            await spawnTmuxSession({ sessionName: tmuxSessionName, sessionDir, sessionId: state.sessionId });
-            updated = await saveSessionState({ ...state, tmuxSessionName });
+            if (multiplexer === 'zellij') {
+              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId });
+            } else {
+              await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });
+            }
+            updated = await saveSessionState({
+              ...state,
+              multiplexer,
+              multiplexerSessionName: sessionName,
+              tmuxSessionName: multiplexer === 'tmux' ? sessionName : null,
+            });
           }
           await setCurrentSession(state.sessionId);
 
-          const tmuxSessionName = updated.tmuxSessionName || null;
-          const attachCommand = tmuxSessionName ? `tmux attach -t ${tmuxSessionName}` : null;
+          const mux = updated.multiplexer || null;
+          const muxSessionName = updated.multiplexerSessionName || updated.tmuxSessionName || null;
+          const attachCommand = muxSessionName
+            ? (mux === 'zellij' ? `zellij attach ${muxSessionName}` : `tmux attach -t ${muxSessionName}`)
+            : null;
           return {
             content: [{
               type: 'text',
@@ -142,7 +170,8 @@ class MCPCollabServer {
                 roleModels: updated.roleModels || {},
                 effectiveRoleModels: buildEffectiveRoleModels(updated, updated.model || null),
                 run: summarizeRun(updated),
-                tmuxSessionName,
+                multiplexer: mux,
+                multiplexerSessionName: muxSessionName,
                 attachCommand,
               }, null, 2),
             }],
@@ -169,7 +198,7 @@ class MCPCollabServer {
             throw new Error(`Session is ${state.status}. Resume/start before invoking.`);
           }
 
-          if (!state.tmuxSessionName) {
+          if (!state.multiplexerSessionName && !state.tmuxSessionName) {
             launchAutopilot(state.sessionId);
           }
 
@@ -193,8 +222,13 @@ class MCPCollabServer {
                 status: state.status,
                 run: summarizeRun(state),
                 latestEvent: latestRunEvent(state),
-                tmuxSessionName: state.tmuxSessionName || null,
-                attachCommand: state.tmuxSessionName ? `tmux attach -t ${state.tmuxSessionName}` : null,
+                multiplexer: state.multiplexer || null,
+                multiplexerSessionName: state.multiplexerSessionName || state.tmuxSessionName || null,
+                attachCommand: state.multiplexerSessionName
+                  ? (state.multiplexer === 'zellij'
+                    ? `zellij attach ${state.multiplexerSessionName}`
+                    : `tmux attach -t ${state.multiplexerSessionName}`)
+                  : (state.tmuxSessionName ? `tmux attach -t ${state.tmuxSessionName}` : null),
               }, null, 2),
             }],
           };
@@ -408,10 +442,10 @@ class MCPCollabServer {
 
     this.server.tool(
       'collab_resume_session',
-      'Resume session and recreate tmux workers if needed',
+      'Resume session and recreate workers if needed',
       {
         sessionId: z.string().optional().describe('Session ID (defaults to current session)'),
-        recreateWorkers: z.boolean().default(true).describe('Recreate tmux session when missing'),
+        recreateWorkers: z.boolean().default(true).describe('Recreate multiplexer session when missing'),
       },
       async ({ sessionId, recreateWorkers }) => {
         try {
@@ -419,24 +453,37 @@ class MCPCollabServer {
           if (!id) throw new Error('No active session found');
           let state = await loadSessionState(id);
 
-          const tmuxSessionName = state.tmuxSessionName || `acfm-synapse-${state.sessionId.slice(0, 8)}`;
-          const tmuxExists = hasCommand('tmux') ? await tmuxSessionExists(tmuxSessionName) : false;
+          const multiplexer = state.multiplexer || resolveMultiplexer('auto', hasCommand('tmux'), hasCommand('zellij'));
+          if (!multiplexer) {
+            throw new Error('No multiplexer found (zellij/tmux). Run: acfm agents setup');
+          }
+          const sessionName = state.multiplexerSessionName || state.tmuxSessionName || `acfm-synapse-${state.sessionId.slice(0, 8)}`;
+          const sessionExists = await muxExists(multiplexer, sessionName);
 
-          if (!tmuxExists && recreateWorkers) {
-            if (!hasCommand('tmux')) {
-              throw new Error('tmux is not installed. Run: acfm agents setup');
-            }
+          if (!sessionExists && recreateWorkers) {
             const sessionDir = getSessionDir(state.sessionId);
-            await spawnTmuxSession({ sessionName: tmuxSessionName, sessionDir, sessionId: state.sessionId });
+            if (multiplexer === 'zellij') {
+              if (!hasCommand('zellij')) throw new Error('zellij is not installed. Run: acfm agents setup');
+              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId });
+            } else {
+              if (!hasCommand('tmux')) throw new Error('tmux is not installed. Run: acfm agents setup');
+              await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });
+            }
           }
 
           state = await saveSessionState({
             ...state,
             status: 'running',
-            tmuxSessionName,
+            multiplexer,
+            multiplexerSessionName: sessionName,
+            tmuxSessionName: multiplexer === 'tmux' ? sessionName : state.tmuxSessionName || null,
           });
           await setCurrentSession(state.sessionId);
 
+          const attachCommand = multiplexer === 'zellij'
+            ? `zellij attach ${sessionName}`
+            : `tmux attach -t ${sessionName}`;
+
           return {
             content: [{
               type: 'text',
@@ -444,8 +491,10 @@ class MCPCollabServer {
                 success: true,
                 sessionId: state.sessionId,
                 status: state.status,
-                tmuxSessionName,
-                recreatedWorkers: !tmuxExists && recreateWorkers,
+                multiplexer,
+                multiplexerSessionName: sessionName,
+                recreatedWorkers: !sessionExists && recreateWorkers,
+                attachCommand,
               }, null, 2),
             }],
           };

package/src/services/dependency-installer.js

@@ -17,6 +17,13 @@ function run(command, args, options = {}) {
   });
 }
 
+function runInstallCommand(command) {
+  if (platform() === 'win32') {
+    return run('cmd.exe', ['/c', command], { stdio: 'inherit' });
+  }
+  return run('bash', ['-lc', command], { stdio: 'inherit' });
+}
+
 export function hasCommand(command) {
   return Boolean(resolveCommandPath(command));
 }
@@ -78,6 +85,29 @@ function resolveTmuxInstallCommand() {
   return null;
 }
 
+function resolveZellijInstallCommand() {
+  if (platform() === 'darwin') {
+    if (hasCommand('brew')) return 'brew install zellij';
+    return null;
+  }
+
+  if (platform() === 'linux') {
+    if (hasCommand('apt-get')) return 'sudo apt-get update && sudo apt-get install -y zellij';
+    if (hasCommand('dnf')) return 'sudo dnf install -y zellij';
+    if (hasCommand('yum')) return 'sudo yum install -y zellij';
+    if (hasCommand('pacman')) return 'sudo pacman -S --noconfirm zellij';
+    if (hasCommand('zypper')) return 'sudo zypper --non-interactive install zellij';
+  }
+
+  if (platform() === 'win32') {
+    if (hasCommand('winget')) return 'winget install --id zellij-org.zellij -e';
+    if (hasCommand('choco')) return 'choco install zellij -y';
+    if (hasCommand('scoop')) return 'scoop install zellij';
+  }
+
+  return null;
+}
+
 export function installTmux() {
   if (hasCommand('tmux')) {
     return { success: true, installed: false, message: 'tmux already installed' };
@@ -92,7 +122,7 @@ export function installTmux() {
     };
   }
 
-  const result = run('bash', ['-lc', installCommand], { stdio: 'inherit' });
+  const result = runInstallCommand(installCommand);
   if (result.status !== 0) {
     return { success: false, installed: false, message: 'tmux installation command failed' };
   }
@@ -106,12 +136,50 @@ export function installTmux() {
   };
 }
 
-export function ensureCollabDependencies() {
+export function installZellij() {
+  if (hasCommand('zellij')) {
+    return { success: true, installed: false, message: 'zellij already installed' };
+  }
+
+  const installCommand = resolveZellijInstallCommand();
+  if (!installCommand) {
+    return {
+      success: false,
+      installed: false,
+      message: 'No supported package manager detected for automatic zellij installation',
+    };
+  }
+
+  const result = runInstallCommand(installCommand);
+  if (result.status !== 0) {
+    return { success: false, installed: false, message: 'zellij installation command failed' };
+  }
+
+  return {
+    success: hasCommand('zellij'),
+    installed: true,
+    message: hasCommand('zellij')
+      ? 'zellij installed successfully'
+      : 'zellij installer finished but binary is not available in PATH yet',
+  };
+}
+
+export function ensureCollabDependencies(options = {}) {
+  const installTmuxEnabled = options.installTmux ?? true;
+  const installZellijEnabled = options.installZellij ?? true;
   const opencode = installOpenCode();
-  const tmux = installTmux();
+  const tmux = installTmuxEnabled
+    ? installTmux()
+    : { success: hasCommand('tmux'), installed: false, message: hasCommand('tmux') ? 'tmux already installed' : 'tmux installation skipped' };
+  const zellij = installZellijEnabled
+    ? installZellij()
+    : { success: hasCommand('zellij'), installed: false, message: hasCommand('zellij') ? 'zellij already installed' : 'zellij installation skipped' };
+
+  const hasMultiplexer = tmux.success || zellij.success;
   return {
     opencode,
     tmux,
-    success: opencode.success && tmux.success,
+    zellij,
+    success: opencode.success && hasMultiplexer,
   };
 }