Skip to content
Back to search

smux

tmux config with built-in terminal automation and agent-to-agent communication.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shawnpana-smux/badge.svg)](/listings/shawnpana-smux)

HTML

<a href="/listings/shawnpana-smux"><img src="/api/listings/shawnpana-smux/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

curl -fsSL https://shawnpana.com/smux/install.sh | bash

This installs: - **tmux** if not already installed (via Homebrew, apt, dnf, pacman, or apk) - **tmux.conf** with Option-key bindings, mouse support, pane labels, and a minimal status bar - **tmux-bridge** CLI for cross-pane agent communication - **smux-pane** CLI that lets closed panes and windows be reopened, like browser tabs - **jq** if not already installed (used by smux-pane)

Everything lives in `~/.smux/`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 142 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # smux
  2. One-command tmux setup with terminal automation for AI agents.
  3. - **For you** — keyboard-driven tmux config with Option-key bindings, mouse support, and pane labels
  4. - **For agents** — `tmux-bridge` CLI lets any agent read, type, and send keys to any pane
  5. - **Agent-to-agent** — Claude Code can prompt Codex in the next pane, and Codex replies back. Any agent that can run bash can participate.
  6. ```bash
  7. tmux-bridge read codex 20 # read the pane
  8. tmux-bridge type codex "review src/auth.ts" # type into it
  9. tmux-bridge keys codex Enter # press enter
  10. ```
  11. https://github.com/user-attachments/assets/9d5463ba-5972-4bbd-a07e-b585f1178011
  12. ## Install
  13. ```bash
  14. curl -fsSL https://shawnpana.com/smux/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 20 on GitHub
  15. ```
  16. This installs:
  17. - **tmux** if not already installed (via Homebrew, apt, dnf, pacman, or apk)
  18. - **tmux.conf** with Option-key bindings, mouse support, pane labels, and a minimal status bar
  19. - **tmux-bridge** CLI for cross-pane agent communication
  20. - **smux-pane** CLI that lets closed panes and windows be reopened, like browser tabs
  21. - **jq** if not already installed (used by smux-pane)
  22. Everything lives in `~/.smux/`.
  23. ## Keybindings
  24. All keybindings use **Option (Alt)** with no prefix required.
  25. ### Panes
  26. | Key | Action |
  27. |---|---|
  28. | `Option+i/k/j/l` | Navigate up/down/left/right (no wrap) |
  29. | `Option+Shift+i/k/j/l` | Swap pane with its neighbor up/down/left/right |
  30. | `Option+n` | New pane (split + auto-tile) |
  31. | `Option+w` | Close pane |
  32. | `Option+Shift+w` | Close window |
  33. | `Option+Shift+n` | Reopen the last closed pane or window (see [Reopening](#reopening-closed-panes-and-windows)) |
  34. | `Option+o` | Cycle layouts |
  35. | `Option+g` | Mark pane |
  36. | `Option+y` | Swap with marked pane |
  37. ### Windows
  38. | Key | Action |
  39. |---|---|
  40. | `Option+m` | New window, placed right after the current one |
  41. | `Option+u` | Next window |
  42. | `Option+h` | Previous window |
  43. | `Option+Shift+u/h` | Move window right/left |
  44. ### Scrolling
  45. | Key | Action |
  46. |---|---|
  47. | `Option+Tab` | Toggle scroll mode |
  48. | `i/k` | Scroll up/down |
  49. | `Shift+I/K` | Half-page up/down |
  50. | `q` or `Escape` | Exit scroll mode |
  51. ### Mouse
  52. - Click to select panes
  53. - Drag to select text (auto-copies to clipboard)
  54. - Scroll wheel to scroll
  55. ## Reopening closed panes and windows
  56. Closing works like closing a browser tab: the process really ends, but enough is remembered to bring the pane back with `Option+Shift+n`.
  57. - A pane returns to the slot it had in its window, with its label and working directory. If the window is gone, it is recreated at its old number.
  58. - `Option+Shift+w` closes a whole window as one entry, and reopening brings back all of its panes together.
  59. - A pane that was running **Claude Code resumes the exact conversation** it had. The session is read from the file Claude Code keeps for each running process, so it survives moving the pane around. Other processes are not restarted; you get a shell where they were.
  60. - The last 25 closes are kept, newest first, and survive a tmux restart. Scrollback is not kept.
  61. The keys call `smux-pane`, which you can also use directly:
  62. | Command | Description |
  63. |---|---|
  64. | `smux-pane close <pane>` | Remember the pane, then kill it |
  65. | `smux-pane close-window <pane>` | Remember every pane in the window, then kill the window |
  66. | `smux-pane revive` | Reopen whatever was closed most recently |
  67. | `smux-pane list` | Show what can be reopened, newest first |
  68. | `smux-pane peek <pane>` | Show what closing a pane would record, without closing it |
  69. Window numbers always match their position in the status bar: `Option+m` opens the new window right after the current one, and numbers close up when a window goes away.
  70. ## tmux-bridge
  71. A CLI for cross-pane communication. Any tool that can run bash can use it — Claude Code, Codex, Gemini CLI, or a plain shell script.
  72. | Command | Description |
  73. |---|---|
  74. | `tmux-bridge list` | Show all panes with target, process, label |
  75. | `tmux-bridge read <target> [lines]` | Read last N lines from a pane |
  76. | `tmux-bridge type <target> <text>` | Type text into a pane (no Enter) |
  77. | `tmux-bridge keys <target> <key>...` | Send keys (Enter, Escape, C-c, etc.) |
  78. | `tmux-bridge name <target> <label>` | Label a pane for easy addressing |
  79. | `tmux-bridge resolve <label>` | Look up a pane by label |
  80. | `tmux-bridge id` | Print this pane's ID |
  81. See the [smux skill](skills/smux/SKILL.md) for full documentation on agent-to-agent workflows.
  82. ## Update
  83. ```bash
  84. smux update
  85. ```
  86. ## Uninstall
  87. ```bash
  88. smux uninstall
  89. ```
  90. ## AI Agent Skills
  91. Install the smux skill to teach your agents how to use tmux-bridge:
  92. ```bash
  93. npx skills add ShawnPana/smux
  94. ```
  95. Works with Claude Code, Codex, Cursor, Copilot, and [40+ other agents](https://skills.sh).
  96. ## Requirements
  97. - macOS (requires [Homebrew](https://brew.sh)) or Linux
  98. - tmux 3.2+ (installed automatically)
  99. - jq (installed automatically)
  100. ## Sponsor
  101. smux is free and maintained in my own time.
  102. [Sponsoring](https://github.com/sponsors/ShawnPana) keeps it that way.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.