Survey Report: Tmuxinator as Potential Session Initializer for Miadi/Hermes Navigator

Date: 2026-05-17 Issue: jgwill/Miadi#334 — Tmuxinator/workspace launcher survey Related: jgwill/Miadi#265 — Hermes Navigator v1 focus contract PDE: bcd9a22d-9b1c-4c69-a659-8610b3663769 (branch: copilot/develop-multiverse-context-management) Research tracks synthesized: 4 parallel agents (web survey, hnavig capability scan, branch-mission context, academic landscape)

Executive Summary

Recommendation: Do not adopt Tmuxinator. Extend hnavig scene activate instead.

1. Hermes Navigator already owns named sessions (hnavig session new/attach), workspace scenes (hnavig scene activate/snapshot/resume), and raw subprocess tmux integration — more than Tmuxinator would add.
2. Tmuxinator introduces a Ruby/gem dependency into a Python toolchain and duplicates the session/lifecycle orchestration that hnavig already controls.
3. The Himmelwright article is a plain-shell tutorial, not a Tmuxinator endorsement. Its core pattern (tmux new-session, idempotency guard via list-sessions | grep, send-keys) can be trivially embedded in Python subprocess calls.
4. The real gap is branch-aware declarative workspace profiles (multi-window/pane startup graphs tied to repo branch context) — this is a scene.py extension, not a Tmuxinator integration.
5. Tmuxinator is best treated as an optional export/share format for human-maintained workspace recipes, not as a core runtime dependency.

Part 1: Article Survey — Himmelwright "Scripting Tmux Workspaces" (2019)

Source: https://ryan.himmelwright.net/post/scripting-tmux-workspaces/

Approach

Plain POSIX shell script that imperatively builds a tmux session:

SESSION="Website"
SESSIONEXISTS=$(tmux list-sessions | grep $SESSION)

if [ "$SESSIONEXISTS" = "" ]; then
  tmux new-session -d -s $SESSION
  tmux rename-window -t 0 'Main'
  tmux send-keys -t 'Main' 'zsh' C-m 'clear' C-m
  tmux new-window -t $SESSION:1 -n 'Hugo Server'
  tmux send-keys -t 'Hugo Server' 'hugo serve -D -F' C-m
  tmux new-window -t $SESSION:2 -n 'Writing'
  tmux send-keys -t 'Writing' "nvim" C-m
fi

tmux attach-session -t $SESSION:0

What it solves

• One-command repeatable project workspace
• Named windows grouping editor/server/shell
• Idempotent guard: if [ "$SESSIONEXISTS" = "" ] prevents duplicate windows on rerun

What it does not solve

• No multi-user/cross-machine portability
• No layout profiles, hooks, or startup ordering guarantees
• No branch/worktree context awareness
• Attach target :0 is hardcoded

Tmuxinator mention

Only as a passing footnote: "This post may be moot if I try Tmuxinator later." Not a recommendation — a speculative future. The article's own approach is the recommendation.

Part 2: Hermes Navigator Capability Map

Hermes Navigator (runtime/hermes-navigator/) already provides significant tmux/session infrastructure:

Existing CLI surface

tmux integration depth

• Raw subprocess calls (subprocess.run(["tmux", ...])) — not libtmux
• Commands used: has-session, new-session, attach, switch-client, list-panes, capture-pane, select-pane
• libtmux listed as optional dependency in pyproject.toml but not imported in implementation
• No Tmuxinator code anywhere in the repo

Key files

• hermes_navigator/session_store.py — SQLite-backed named session persistence
• hermes_navigator/tmux_session.py — tmux session plan/create/attach
• hermes_navigator/scene.py — workspace scene storage and launcher (409 lines)
• hermes_navigator/cli.py — full CLI surface (session, scene, focus, operator, daemon)
• hermes_navigator/models.py — NamedSession, Scene, tmux/window models

The actual gap

What hnavig does NOT yet have:

• Branch-aware workspace profiles: scene.py launches generic terminal/editor/browser windows, not repo-branch-aware tmux layouts
• Declarative multi-window/pane startup graph for a specific branch or issue context
• Template/profile system for per-project or per-branch startup recipes
• libtmux-level introspection: panes/windows queried via shell commands, not object model

Part 3: Fit Assessment

Tmuxinator vs. hnavig scene activate

Integration overhead for Tmuxinator

1. Add Ruby/gem to a Python tool's install requirements
2. Generate or translate from hnavig Scene → Tmuxinator YAML (or maintain two separate formats)
3. Reconcile session names, idempotency, attach semantics between two systems
4. Debug path becomes: Python → Tmuxinator → tmux instead of Python → tmux
5. No natural path to Hermes audit logs, approval queue, or daemon context

Verdict

Tmuxinator is not the right fit as a core dependency. It solves a subset of what hnavig scene already does, adds cross-language complexity, and fractures the audit/traceability chain.

The right extension: Add branch/issue-aware YAML or TOML workspace profiles to hnavig scene activate --profile <name> so that per-branch startup recipes can be declared without adopting Tmuxinator's Ruby stack.

Part 4: Recommendation

Immediate (addresses #334 directly)

Do not adopt Tmuxinator as a core dependency.

Extend hnavig scene activate with:

• --profile <name> flag reading from .hermes/profiles/<name>.toml
• Profile format: [[window]] tables with name, command, pane_layout
• Branch-aware auto-profile lookup: .hermes/profiles/<branch-slug>.toml
• Idempotency: existing has-session guard is sufficient

This is a pure Python extension of scene.py (~100-150 lines) with no new runtime dependencies.

If human-editable shared workspace recipes become a product goal

Consider Tmuxinator as an export format only: a hnavig scene export --format tmuxinator command that writes a .tmuxinator/<name>.yml from the current Scene record. This gives teams the option to use Tmuxinator tooling without making it a runtime dependency.

HITL Ambiguities (require human judgment)

1. Report vs. concrete launcher: Is #334's deliverable a survey recommendation (this document) or an implemented hnavig scene extension? The PDE flagged this as the primary ambiguity.
2. Scope boundary: Is Hermes Navigator the only target, or does the workspace initializer need to support other branch hosts (gaia, as, eury)?
3. Profile format choice: YAML vs. TOML vs. Python dict — the choice affects compatibility with Tmuxinator export and user editability.
4. Tmuxinator as optional export: Is this worth the maintenance surface? Or is direct scene management sufficient?

Part 5: Academic Context

This section fulfills the academic research request in AGENTS.md.

Relevant Academic Fields

Key Authors and Works

Programmer Tools HCI

• Brad A. Myers (CMU) — "Programmers are Users Too" (IEEE Computer 2016, 167 citations)
• Andrew J. Ko (UW) — "Past, Present and Future of Programming in HCI" (CHI 2009)
• Xu, Pandey, Klemmer — "An HCI View of Configuration Problems" (arXiv:1601.01747, 2016)
• Sam Lau & Philip Guo (UCSD) — "Design Space of LLM-Based AI Coding Assistants" (VL/HCC 2025)

Empirical SE — DevOps

• Bram Adams (Polytechnique Montréal) — "Modern Release Engineering in a Nutshell" (ICSE 2016, 177 citations)
• Weiyi Shang (Concordia) — "Log Engineering" PhD thesis (2014); "Studying Logging Characteristics and Code Quality" (ESE 2015, 98 citations)
• Sobhani, Haque, Sharma — "It Works (only) on My Machine: Reproducibility Smells in Ansible Scripts" (MSR 2025)

LLM-Based AI Agents

• Shunyu Yao et al. (Princeton) — "ReAct: Synergizing Reasoning and Acting in Language Models" (ICLR 2023)
• John Yang et al. (Princeton NLP) — "SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering" (arXiv:2405.15793, 2024)
• Zhiheng Xi et al. (Fudan) — "Rise and Potential of LLM-Based Agents: A Survey" (arXiv:2309.07864, 2023)
• Chunqiu Xia et al. (UIUC) — "Agentless: Demystifying LLM-based Software Engineering Agents" (arXiv:2407.01489, 2024)

Cognitive Load & DevX

• Meyer, Fritz, Murphy, Zimmermann (MSR) — "Software Developers' Perceptions of Productivity" (FSE 2014, 340 citations)
• Meyer, Barton, Murphy, Zimmermann — "The Work Life of Developers: Activities, Switches and Productivity" (IEEE TSE 2017, 247 citations)
• Greiler, Storey, Noda — "Actionable Framework for Developer Experience" (IEEE TSE 2022, 107 citations)

Research gap: No academic paper uses "tmuxinator" as a research subject. A thesis studying Tmuxinator empirically would be genuinely novel.

Montreal Research Landscape

Polytechnique Montréal — MCIS/SWAT Labs

• Bram Adams — Release engineering, DevOps, CI/CD, build systems, configuration management. Tmuxinator YAML files are IaC artifacts in his lens. Has supervised DevOps4ML theses. Most directly relevant thesis director.
• Foutse Khomh — SWAT Lab, MLOps/LLMOps pipelines, quality in ML/AI systems. Hermes Navigator is a session-level LLMOps primitive. Relevant for AI-engineering angle.

McGill University

• Martin P. Robillard — API documentation, developer comprehension, software knowledge discovery. Methodologically parallel to studying how developers interact with session-initialization tool APIs. Contact: martin@cs.mcgill.ca
• Joëlle Pineau — RL, reproducible AI, dialogue systems (also MILA + Meta FAIR). Champions reproducible AI — maps to the reproducibility-vs-adaptivity tension in #334.

Concordia University

• Weiyi Shang — Log engineering, system observability, DevOps tooling. Hermes Navigator's context/log.ndjson audit log is exactly the artifact his methodology studies. URL: http://users.encs.concordia.ca/home/s/shang/

MILA (Montréal Institute for Learning Algorithms)

• Golnoosh Farnadi (UdeM + MILA) — Responsible AI, governance, fairness. Secondary supervisor path for ethics/HITL governance dimensions.

Defensible Thesis Directions

Thesis 1: "Declarative vs. Intent-Driven Session Initialization: A Comparative Study of YAML-Scripted and Daemon-Observed Workspace Bootstrapping in AI Agent Runtimes"

• Director: Bram Adams (Polytechnique Montréal), co-direction: Martin Robillard (McGill)
• Fields: Empirical SE + Programmer Tools HCI
• Connection to #334: Directly empirically answers the Tmuxinator vs. Navigator question

Thesis 2: "Named Session Continuity as a First-Class Primitive in Multi-Model AI Orchestration Systems"

• Director: Joëlle Pineau (McGill + MILA)
• Fields: LLM-Based AI Agents + Empirical SE
• Connection to #334: Validates or refutes the NamedSession design that emerges from this survey

Thesis 3: "The Terminal as Agent Substrate: Designing Agent-Computer Interfaces for Human-Gated Autonomous Software Engineering"

• Director: UdeM/DIRO or Concordia (verify DIRO faculty page: https://diro.umontreal.ca/departement/professeurs-et-professeures/)
• Fields: HITL AI + Programmer Tools HCI + Empirical SE
• Connection to #334: Evaluates how ACI design (Tmuxinator-initialized static windows vs. daemon-managed dynamic panes) affects agent decision quality and human oversight burden

Sources