Survey Report: Zellij as Terminal Workspace Multiplexer for Miadi / Hermes Navigator

Date: 2026-05-17
Primary issue: jgwill/Miadi#334
Related: jgwill/Miadi#265
PDE: ae6a72fd-7057-43c7-b1fe-e02bfe45c3ca
Research method: local code survey + official documentation fetches + GitHub repository inspection + academic context scan
Decision status: conditional accept as an optional Hermes Navigator scene backend, not as a replacement for Navigator’s SQLite scene model or the broader tmux substrate.

Executive Summary

WIKI-READY

Zellij is materially stronger than Tmuxinator for Hermes Navigator because it already exposes a machine-oriented CLI control surface, headless/background session creation, KDL workspace layouts, structured JSON inspection, and built-in session resurrection. Those capabilities map well onto hnavig scene activate and hnavig scene resume, especially for terminal-first workflows on SSH-accessed hosts such as gaia, as, and eury.

The important boundary is that Zellij should be adopted as a runtime backend for scene launch, not as the new system of record. Hermes Navigator’s SQLite scene model still carries issue_ref, project_id, context_snapshot_id, and Miadi-specific traceability that Zellij does not model. Also, Zellij would only replace a narrow layer first: the repo still has broader tmux coupling in focus.py, terminal_inventory.py, terminal_send.py, approval_queue.py, context_engine.py, and universe_detector.py.

SPEC-CANDIDATE

1. Keep SceneStore / NamedSession SQLite as the control plane.
2. Add zellij as an optional terminal backend for scene activate / scene resume.
3. Treat KDL layouts as Hermes workspace-profile artifacts, analogous to but more capable than Tmuxinator YAML.
4. Keep the multi-host strategy host-local: one Zellij session per machine (gaia, as, eury), not one shared session across separate servers.
5. Defer any full tmux-to-Zellij migration outside the scene-launch layer to a separate issue/spec wave.

1. Zellij Doc Survey

PROVENANCE

The following official sources were fetched and inspected:

Key technical findings

PROVENANCE

1. Rust core / workspace architecture is real and explicit. The upstream Cargo.toml lists zellij-client, zellij-server, zellij-utils, zellij-tile, and multiple default plugins in a single Cargo workspace. This validates a Rust-native architecture rather than a shell-script wrapper around tmux.
2. The plugin model is WebAssembly/WASI-based. Official plugin docs state: “Zellij offers a Webassembly / WASI plugin system,” and note that the built-in UI itself is plugin-driven. This matters because Hermes Navigator can initially ignore plugins, but the plugin surface gives Zellij a real extension story beyond static pane scripting.
3. KDL is the layout/config language. The official layouts docs explicitly say “Zellij uses KDL as its configuration language.” That means workspace profiles can be materialized as KDL files rather than YAML.
4. Layouts are richer than Tmuxinator-style project launchers. The KDL schema supports panes, tabs, floating panes, cwd, command panes, editor panes, templates, named tabs, and remote layout URLs. Tmuxinator YAML is primarily a tmux session initializer; Zellij KDL is a first-class runtime layout language.
5. There is no documented Python API. The strongest official statement comes from the programmatic-control page: “No socket, HTTP API, or library binding is required - all interaction occurs through subprocess invocation, and structured data is available as JSON on stdout.” For Hermes Navigator, that is actually a good fit because current tmux integrations are already subprocess.run(...) based.
6. Zellij has first-class machine control, not just human keyboard UX. Official docs show zellij action list-panes --json, list-tabs --json, dump-screen, subscribe --format json, attach --create-background, and blocking pane primitives. That is materially more automation-friendly than a pure Tmuxinator-style “generate and attach” model.
7. Zellij supports headless/background sessions directly. Official docs show zellij attach --create-background my-session and then zellij --session my-session action .... This is important for gaia, as, and eury, where Hermes Navigator often acts over SSH and may need terminal state without a desktop.
8. Built-in session resurrection is real but local. Official session-resurrection docs say sessions are serialized to the user cache folder, saved every second as human-readable KDL layouts, and can be resurrected after quit/crash. This is useful, but it is still host-local cache state rather than Hermes-managed SQLite provenance.
9. Commands in resurrected or remote layouts are intentionally gated. Docs note that remote layouts suspend commands behind a “Waiting to run” banner, and resurrected commands sit behind a press-ENTER banner unless --force-run-commands is used. This aligns well with Miadi’s HITL discipline.
10. Sessions are machine-scoped. The CLI docs say commands can target any session “running on the machine.” That means the natural operational unit is one host-local Zellij daemon/session space per server, not one magical cross-host shared session spanning gaia, as, and eury.

What this means for Hermes Navigator

WIKI-READY

Zellij is not merely “a prettier tmux.” The official docs show a proper terminal workspace runtime with declarative layouts, observable pane state, headless startup, structured JSON inspection, and built-in session persistence. For Hermes Navigator this matters because the product question is not whether Zellij can replace tmux attach; it is whether it can act as a better terminal workspace substrate for scene activate and scene resume without collapsing Navigator’s own control-plane metadata.

SPEC-CANDIDATE

• Use Zellij’s CLI/JSON surface from Python; do not seek a Python SDK that does not exist.
• Materialize Navigator workspace profiles as generated KDL files.
• Preserve Miadi metadata in SQLite and treat Zellij session restore as runtime convenience, not authoritative persistence.

2. Hermes Navigator Capability Map

PROVENANCE

Local files inspected:

• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/tmux_session.py
• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/scene.py
• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/cli.py (scene commands)
• broader tmux grep across runtime/hermes-navigator/hermes_navigator/

Local capability map

All immediate Zellij integration points in the requested scene path

PROVENANCE

The requested code path reveals four concrete integration points:

1. Named session helper layer — tmux_session.py can be mirrored as zellij_session.py with plan/build/execute helpers.
2. Scene launch dispatch — SceneLauncher.launch() is the narrow point where current desktop terminal spawning can become backend-aware.
3. CLI launch semantics — hnavig scene activate --launch and hnavig scene resume --launch are already the operator-facing verbs; no new top-level command is required.
4. Persistent scene metadata — SceneStore already stores the non-runtime metadata that Zellij does not know about.

Broader tmux substrate note

PROVENANCE

A repo-wide grep showed additional tmux subprocess use outside the requested files, including:

• focus.py (tmux select-pane)
• terminal_inventory.py (list-panes, capture-pane, attach, switch-client)
• terminal_send.py (send-keys)
• approval_queue.py (send-keys)
• context_engine.py (capture-pane, list-panes)
• universe_detector.py (display-message, show-environment, list-panes)

This matters because a Zellij-backed scene feature would be incremental, not a global substrate swap.

WIKI-READY

Hermes Navigator already has the right architectural split for a Zellij experiment: SQLite persistence is separate from launch execution, and the CLI already expresses scene lifecycle clearly. The real engineering question is not whether SceneStore should change very much; it is whether SceneLauncher should learn a terminal backend abstraction.

SPEC-CANDIDATE

• Introduce a terminal_backend choice at launch time.
• Keep SceneStore stable; only extend it with optional runtime metadata if needed.
• Explicitly document that scene-level Zellij adoption does not retire the broader tmux substrate yet.

3. Fit Assessment

Main comparison matrix

Zellij vs current scene.py

PROVENANCE

• scene.py today is explicitly a desktop-window launcher: terminal emulator + GUI editor + browser.
• Zellij is explicitly a terminal workspace runtime with headless/background/session control.

That creates a shape mismatch and a fit opportunity.

Where Zellij is better

WIKI-READY

1. Server / SSH ergonomics: Zellij is better suited than the current desktop-window launcher for hosts where the session should survive disconnects and be reattached later.
2. Profile expressiveness: KDL layouts are a better replacement for Tmuxinator YAML than ad hoc Python window lists because they naturally express tabs, panes, commands, focus, and cwd composition.
3. Automation surface: Zellij exposes actionable JSON and streaming output primitives, which means Hermes Navigator can observe and react to panes instead of just launching them.
4. HITL safety: suspended commands and resurrection banners align with Miadi’s approval-sensitive posture.

Where current hnavig is still better

WIKI-READY

1. Issue/spec/context metadata: SceneStore already tracks Miadi-owned fields that Zellij does not track.
2. External application launching: opening code, kate, gedit, or browser tabs is simpler in current scene.py than in a pure Zellij world.
3. Repository-native traceability: SQLite scene records can be linked to issue refs, snapshots, and future rispecs; Zellij’s cache cannot.

Why this is different from the Tmuxinator survey

WIKI-READY

The Tmuxinator survey ended in rejection because Tmuxinator would mainly duplicate hnavig behavior while adding a Ruby runtime. Zellij is different: it brings a real runtime surface that Hermes Navigator does not currently have — headless sessions, KDL layouts, JSON inspection, pane subscriptions, and built-in resurrection. That makes Zellij a plausible backend, not merely an optional export format.

Net fit judgment

SPEC-CANDIDATE

• Accept conditionally for terminal-first scenes.
• Reject as a full replacement for SQLite scene persistence.
• Reject for now as a full-system tmux replacement across all Hermes Navigator modules.

4. Extension Contract: Zellij-backed hnavig scene

4.1 What calls in scene.py would change

SPEC-CANDIDATE

Add a backend abstraction at the launcher boundary:

1. SceneLauncher.launch(scene) gains backend: Literal["desktop", "zellij"] or reads from config.
2. _open_terminal() is replaced by _open_terminal_desktop() + _open_terminal_zellij().
3. _open_editor() becomes policy-based:
   • file target -> zellij edit <file> or KDL pane edit="..."
   • directory target / GUI-editor intent -> keep existing external editor path in v1
4. _open_browser() remains external by default (xdg-open) even in Zellij mode, because browser launch is outside Zellij’s core substrate.
5. cli.py scene verbs gain --backend desktop|zellij and possibly --zellij-layout <path> for explicit overrides.
6. Optional schema extension in SceneStore: runtime_backend, runtime_session_name, runtime_layout_path.

4.2 Proposed launch flow

SPEC-CANDIDATE

hnavig scene activate <path> --backend zellij --launch

1. SceneStore.activate_scene(...) persists Miadi metadata as today.
2. A scene-to-KDL renderer materializes a deterministic layout file from the scene window list and profile.
3. Hermes launches a host-local Zellij session:
   • headless: zellij attach --create-background <session> options --default-layout <layout.kdl>
   • interactive: zellij --layout <layout.kdl> --session <session> or zellij attach <session> depending on context
4. If the scene contains browser/reference URLs, Hermes may still call xdg-open outside Zellij.
5. Resume path prefers zellij attach <session> and only regenerates layout if the session is missing.

4.3 Standard Miadi workspace KDL template

SPEC-CANDIDATE

layout {
    tab name="workspace" cwd="/usr/local/src/ironsilk" focus=true {
        pane split_direction="vertical" {
            pane name="shell"
            pane split_direction="horizontal" {
                pane command="git" {
                    cwd "."
                    args "status" "--short"
                    start_suspended true
                }
                pane command="bash" {
                    cwd "."
                    args "-lc" "python -m pytest -q || true"
                    start_suspended true
                }
            }
        }
    }
    tab name="reference" cwd="/usr/local/src/ironsilk" {
        pane command="bash" {
            cwd "."
            args "-lc" "sed -n '1,220p' README.md"
            start_suspended true
        }
        pane command="bash" {
            cwd "."
            args "-lc" "sed -n '1,220p' rispecs/hermes-agent-runtime/00-hermes-agent-runtime-master.spec.md"
            start_suspended true
        }
    }
}

WIKI-READY

This is not meant to replace every desktop affordance. It shows the right contract shape: one reproducible, host-local terminal workspace profile that Hermes can generate from scene metadata, while keeping non-terminal launches optional and explicit.

4.4 Multi-host branch strategy applicability

PROVENANCE

Miadi’s branch discipline already says:

• gaia -> host-local branch
• as -> consolidator
• eury -> host-local branch

Official Zellij docs describe sessions as machine-scoped and controllable on the machine.

SPEC-CANDIDATE

• Do not treat one Zellij session as spanning gaia, as, and eury simultaneously.
• Instead create one session namespace per host, e.g.:
  • miadi-gaia-<scene>
  • miadi-as-<scene>
  • miadi-eury-<scene>
• A human may SSH into gaia and attach to miadi-gaia-*; that is still a host-local session, not a distributed shared session.
• If a later spec wants cross-host synchronized panes or collaboration, that is a separate distributed-systems problem and should not be smuggled into the scene-launch contract.

5. Recommendation

Decision

SPEC-CANDIDATE

Conditional accept. Adopt Zellij as an optional Hermes Navigator scene-launch backend for terminal-first workspaces, while keeping SQLite SceneStore / NamedSession as the authoritative control plane.

Why this is the right boundary

WIKI-READY

This gives Hermes Navigator a better runtime for SSH-friendly, persistent, profile-driven terminal work without losing Miadi-owned metadata, issue traceability, or snapshot semantics. It also avoids the category error of treating Zellij’s host-local cache as if it were a replacement for Navigator’s product-level model.

Implementation gap estimate

Recommendation wording for issue / spec promotion

WIKI-READY

• Accept Zellij as a backend, not as the new source of truth.
• Do not deprecate tmux globally in this wave.
• Do not attempt cross-host shared Zellij sessions in v1.
• Use KDL layouts as workspace-profile materialization for terminal-first scenes.

6. HITL Ambiguities

PROVENANCE

1. Editor policy ambiguity: Should a Zellij-backed scene optimize for terminal editors (vim, helix, nvim) or keep launching GUI editors externally when target is a directory?
2. Browser/reference policy ambiguity: Should URLs stay external via xdg-open, or should Hermes render reference work as terminal command panes instead?
3. Session ownership ambiguity: When both Zellij resurrection and Hermes SQLite know about “the same” scene, which layer wins during conflicts?
4. Backend selection ambiguity: Should zellij be opt-in per command, per scene profile, or a machine default?
5. Broader migration ambiguity: Is the desired work limited to scene activate/resume, or should later waves port focus, inventory, and send-keys semantics away from tmux too?

WIKI-READY

These are implementation-policy questions, not blockers to the survey result. They matter because Zellij is good enough to justify a backend experiment, but not self-explanatory enough to remove human design choices around GUI apps, resurrection precedence, and scope.

7. Academic Context

Relevant fields

WIKI-READY

Relevant authors / works

PROVENANCE

• Programmer tools / developer workflow
  • Brad A. Myers et al., Programmers are Users Too — developer tools as HCI objects.
  • Andrew J. Ko, work on the future of programming in HCI.
  • Martin P. Robillard, software comprehension and API/tool usability.
• Empirical SE / DevOps / configuration
  • Bram Adams, release engineering and software analytics.
  • Foutse Khomh, software quality and trustworthy software systems.
  • Weiyi Shang, log engineering / observability.
• AI agent / runtime control
  • John Yang et al., SWE-agent / Agent-Computer Interfaces.
  • Shunyu Yao et al., ReAct.
• WASM / sandboxing context
  • WebAssembly/WASI literature on safe extension and portable sandboxed execution is directly relevant to Zellij plugin architecture.

Montreal researchers relevant to this survey

PROVENANCE

1. Martin Robillard (McGill) — software comprehension, API use, developer-facing software design. Strong fit for evaluating whether Zellij’s control model reduces workspace friction for humans.
2. Jeremy Cooperstock (McGill) — human-computer interaction and multimodal interfaces. Useful lens for terminal UX and workflow ergonomics.
3. Bettina Kemme (McGill) — distributed information systems. Strong fit for reasoning about machine-scoped sessions, replication boundaries, and multi-host state.
4. Foutse Khomh (Polytechnique Montréal) — software engineering, trustworthy systems, AI/software quality. Relevant to evaluating operational risk in backend substitution.
5. Weiyi Shang (Concordia) — log engineering, performance engineering, AIOps. Relevant because Hermes Navigator already treats terminal state and logs as operational evidence.
6. Joëlle Pineau (McGill / Mila) — AI systems, reproducibility, and experimental rigor. Useful for the agent-runtime and evaluation angle.

Thesis director suggestion

SPEC-CANDIDATE

Primary thesis director suggestion: Martin Robillard (McGill), with Bettina Kemme (McGill) or Foutse Khomh (Polytechnique Montréal) as an ideal co-supervision direction depending on emphasis.

• Choose Robillard if the thesis emphasis is developer-tool UX, workspace comprehension, and API/control-surface design.
• Choose Kemme if the emphasis shifts toward machine locality, host/session coordination, and distributed state.
• Choose Khomh if the emphasis is reproducibility, runtime engineering quality, and AI/software operations.

Researchable thesis framing

WIKI-READY

A defensible thesis topic here would be: “Terminal Workspace Runtimes as Agent-Computer Interfaces: Comparing declarative layout systems, host-local persistence, and orchestration metadata in multi-host software engineering workflows.” Zellij gives the systems/WASM/runtime side; Hermes Navigator gives the orchestration, traceability, and HITL side.

8. Promotion Map

SPEC-promotable (ready or nearly ready for rispecs/hermes-navigator/)

SPEC-CANDIDATE

• Hermes Navigator should treat terminal runtime selection as a backend concern, not as scene identity.
• Zellij can be added as an optional backend for scene activate / scene resume.
• SQLite SceneStore / NamedSession remains authoritative for Miadi metadata.
• Multi-host strategy remains host-local: one session namespace per machine.
• KDL layouts are the right profile materialization format for a Zellij-backed scene.

Keep as provenance

PROVENANCE

• Exact fetched doc URLs, quoted wording, and current upstream implementation details.
• Broader grep evidence of tmux usage across other Hermes Navigator modules.
• Current upstream Zellij version/workspace structure as observed in fetched Cargo.toml and repo listing.
• The specific LOC/day estimate, which should be revalidated before implementation.

Promote to wiki prose

WIKI-READY

• Zellij is a good optional backend because it combines headless sessions, KDL layouts, JSON inspection, and session resurrection.
• Zellij does not replace Hermes Navigator’s scene database.
• A single Zellij session should not be treated as spanning gaia, as, and eury; use per-host sessions.

9. Sources

Local code / repo sources

• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/tmux_session.py
• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/scene.py
• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/cli.py
• /usr/local/src/ironsilk/runtime/hermes-navigator/hermes_navigator/models.py
• https://github.com/jgwill/Miadi/issues/334
• https://github.com/jgwill/Miadi/issues/265

Official Zellij sources

• https://zellij.dev/documentation/
• https://zellij.dev/documentation/layouts.html
• https://zellij.dev/documentation/creating-a-layout.html
• https://zellij.dev/documentation/plugins.html
• https://zellij.dev/documentation/plugin-dev-env
• https://zellij.dev/documentation/controlling-zellij-through-cli.html
• https://zellij.dev/documentation/programmatic-control.html
• https://zellij.dev/documentation/zellij-run-and-edit.html
• https://zellij.dev/documentation/cli-recipes.html
• https://zellij.dev/documentation/session-resurrection.html
• https://zellij.dev/tutorials/layouts/
• https://github.com/zellij-org/zellij
• https://github.com/zellij-org/zellij/blob/main/docs/ARCHITECTURE.md

Academic / researcher sources

• https://www.cs.mcgill.ca/~martin/
• https://www.mcgill.ca/ece/jeremy-cooperstock
• https://www.cs.mcgill.ca/~kemme/
• https://www.polymtl.ca/expertises/en/khomh-foutse
• https://www.concordia.ca/faculty/weiyi-shang.html
• https://mila.quebec/en/directory/joelle-pineau
• https://www.cs.mcgill.ca/~prakash/
• https://ieeexplore.ieee.org/abstract/document/7503516/
• https://doi.org/10.48550/arXiv.2405.15793
• https://doi.org/10.48550/arXiv.2210.03629

Final survey verdict

SPEC-CANDIDATE

Zellij is the first surveyed tool that is strong enough to justify a real Hermes Navigator integration path. The correct move is not “replace Navigator with Zellij” and not “replace tmux everywhere immediately”; it is to add Zellij as an optional scene backend that preserves SQLite provenance, embraces KDL workspace profiles, and stays host-local across gaia, as, and eury.