`here` mode: `send_keys` for env vars and shell replacement diverges from teamocil and is unsafe

Open
#1,030 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python, shell
Domain
cli, tooling

Research direction

Start in src/tmuxp/workspace/builder.py around lines 695-727, then compare the referenced teamocil and tmuxinator implementations. Review sub-issues #1031 and #1032 to establish whether the scope is Level 1 or Level 2; done means the selected --here approach avoids unsafe infrastructure send_keys while preserving the stated directory, environment, and shell behavior.

Written by the indexing model from the issue text.

Description

Problem

--here mode in tmuxp uses send_keys to inject infrastructure commands (cd, export, shell replacement) into the active pane. This has three failure modes:

  1. export is not POSIX-universal — it's a syntax error in fish, nu, and other non-bash/zsh shells
  2. Types into foreground programs — if the active pane is running vim, python, htop, etc., the cd/export commands are typed as input, corrupting the user's session
  3. Shell history pollutioncd and export commands appear in the user's shell history
What tmuxp does (3 categories of send_keys)

builder.py:695-727:

# 1. Directory change via send_keys
active_pane.send_keys(f"cd {shlex.quote(start_directory)}", enter=True)

# 2. Environment vars via send_keys (N calls, one per var)
_here_pane.send_keys(f"export {_ekey}={shlex.quote(str(_eval))}", enter=True)

# 3. Shell replacement via send_keys
_here_pane.send_keys(window_shell, enter=True)
What teamocil does (1 category of send_keys)

teamocil's --here only uses send_keys for cd — the one unavoidable case. Everything else uses tmux primitives:

  • Window rename: rename-window — tmux command, not send_keys
  • Directory (cd): send_keys cd "/path" — only send_keys usage
  • Pane splitting: split-window -c '/path' — tmux primitive with -c for directory
  • Environment vars: Not handled at all — no send_keys export
  • Shell replacement: Not handled — teamocil doesn't change the running shell

tmuxinator similarly never uses send_keys for infrastructure — only for user-specified pane commands. Directories use -c on new-window and splitw.

Impact

Categories 2 and 3 (export and window_shell) are tmuxp-specific — neither Ruby tool does this. They are the primary source of the POSIX shell assumption and the "types into vim" failure mode.

Proposed solutions

Two approaches, tracked as sub-issues:

  • Level 1 (#1031): Match teamocil — use session.set_environment() for env vars, respawn-pane for shell replacement, keep send_keys cd only
  • Level 2 (#1032): Eliminate send_keys entirely — use split-window/swap-pane/kill-pane to create a fresh pane with correct dir+env

References

Dominant language
Python
Stars
4.6k
Forks
248
Avg merge
2h 13m
Merged PRs (30d)
1

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from tmux-python/tmuxp

All issues in tmux-python/tmuxp

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.