- Perl 79.9%
- JavaScript 11%
- Roff 8.9%
- Shell 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
The hook hash printed as a HASH reference. It now prints its keys and
values, sorted, as { key => 'value', ... }.
hook_sub isn't a default option, so it was listed under unknown keys,
as the code ref it was loaded into. It's now listed with the options
and shows the configured path, with the reason it isn't used when the
file was rejected.
|
||
| extras | ||
| .gitignore | ||
| .perltidyrc | ||
| dot.tmuxc.conf | ||
| LICENSE | ||
| README.md | ||
| tmuxc | ||
| tmuxc.1 | ||
tmuxc
tmuxc attaches to a local or remote tmux session and breaks out each window into a local terminal. Each window in a session is tracked by tmuxc, and when found, a shell script is created that is executed by a terminal of your choice. The shell script creates a new cloned session that's part of the base session you're monitoring, sets a few options, and focuses a specific window. When that window in tmux is closed, the cloned session is killed, causing the script to finish executing and the terminal to close.
tmuxc is written in pure core Perl, so it should work as-is on most any modern system. It's been successfully tested on Void Linux, FreeBSD, OpenBSD, Ubuntu, Arch.
.tmux.conf changes
A few changes to tmux's configuration will need to be made. Because of the way tmuxc operates, in multi-window-mode new windows that are created in a session should not automatically get focus. This behavior is nominally controlled by the -d flag on new-window and breakp. A full list of changes to .tmux.conf are listed below.
# Create a new window. In tmuxc multi-window-mode the window is created without focus
# (-d), so the terminal you pressed the key in keeps its window; tmuxc opens a new
# terminal for the new window. Single-window-mode and plain tmux sessions get a
# normal new-window.
bind-key c if-shell -F '#{==:#{@tmuxc_wm},multi}' 'new-window -d' 'new-window'
# Break the current pane out into a new window, the same way.
bind b if-shell -F '#{==:#{@tmuxc_wm},multi}' 'breakp -d' 'breakp'
# In multi-window-mode each terminal shows one window, so switching windows in it
# would leave two terminals on the same window. Make next/previous window do nothing
# there.
bind-key n if-shell -F '#{!=:#{@tmuxc_wm},multi}' 'next-window'
bind-key p if-shell -F '#{!=:#{@tmuxc_wm},multi}' 'previous-window'
# Optional: hide the status bar in multi-window-mode and show it in single-window-mode.
# The hook runs against the session a terminal attaches to; sessions tmuxc doesn't
# manage keep the global status setting. A session's @tmuxc_status, if on or off, wins.
set-hook -g client-attached {
if -F '#{==:#{@tmuxc_wm},multi}' { set-option status off }
if -F '#{==:#{@tmuxc_wm},single}' { set-option status on }
if -F '#{==:#{@tmuxc_status},off}' { set-option status off }
if -F '#{==:#{@tmuxc_status},on}' { set-option status on }
}
tmuxc sets the session option @tmuxc_wm to single or multi on every session its terminals attach to, so one set of bindings works for both window modes and for sessions tmuxc doesn't manage. Key bindings are global to the tmux server, so set them here rather than in on_connect. To pin one session's status bar, add set-option @tmuxc_status off (or on) to its on_connect.
Configuration file
The tmuxc configuration file is written as an anonymous Perl hash. The syntax is generally easy to pick up - adapting the example listed below to your environment should be a quick process.
tmuxc uses the first of these files that exists: ~/.config/tmuxc.conf, ~/.tmuxc.conf, ~/.config/tmuxc/tmuxc.conf, and on Haiku /boot/home/config/settings/tmuxc.settings. Use -c to point at a different file.
Session names can't contain ., : or @: tmux splits session targets at . and :, and tmuxc names each instance session@host. tmuxc replaces each of those characters with -, so a session named my.session runs as my-session and is looked up in the configuration file under that name. Existing tmux sessions with those characters in their names are left out of the remote session menu.
Example ~/.config/tmuxc.conf for a local tmux instance
{
temp => "$ENV{'XDG_RUNTIME_DIR'}/tmuxc/",
terminal => [ qw(kitty) ],
ssh_args => [ qw(-A) ],
selector => [ 'bemenu -l 10 -i -n -w -P > -p tmuxc --fn "Hack 18"' ],
input_prompt => [ 'bemenu -l 10 -i -n -w --fn "Hack 18" -p' ],
session => 'global-session',
hosts => {
localhost => {
'global-session' => {
initialize => [ qw(tmux new-session -d -s global-session) ],
},
},
},
}
Example ~/.config/tmuxc.conf for a local and remote tmux instance
{
temp => "$ENV{'XDG_RUNTIME_DIR'}/tmuxc/",
terminal => [ qw(kitty) ],
ssh_args => [ qw(-A) ],
selector => [ 'bemenu -l 10 -i -n -w -P > -p tmuxc --fn "Hack 18"' ],
input_prompt => [ 'bemenu -l 10 -i -n -w --fn "Hack 18" -p' ],
session => 'global-session',
hosts => {
localhost => {
'global-session' => {
initialize => [ qw(tmux new-session -d -s global-session) ],
},
},
'my.remote.server.com' => {
'global-session' => {
initialize => [ qw(tmux new-session -d -s global-session) ],
},
},
},
}
Example advanced configuration:
{
terminal => [qw(kitty)],
session => 'global-session',
ssh_args => [qw(-A -X)],
selector => [ qw(bemenu -l 20 -i -n -w -P > -p tmuxc --fn), "Hack 18" ],
input_prompt => [ qw(bemenu -l 20 -i -n -w --fn), "Hack 18", qw(-p) ],
temp => "$ENV{'XDG_RUNTIME_DIR'}/tmuxc/",
detach => 0,
hosts => {
localhost => {
'global-session' => {
blacklist => ['ignore'],
initialize =>
[qw(tmuxp load -2 -d ~/Documents/global-session.yml)],
},
'monitoring' => {
skipnw => 1,
initialize => [qw(tmuxp load -2 -d ~/Documents/monitoring.yml)],
},
},
'irc.vm' => {
'weechat' => {
skipnw => 1,
blacklist => [ 'ignore', 'top' ],
initialize =>
[qw(/usr/local/bin/tmuxp-3.6 load -2 -d ~/weechat.yml)],
},
},
'bastion.host' => {
wm => 'single',
tmux_bin => '/home/myuser/bin/tmux',
'global-session' => {
initialize => [qw( tmux new-session -d -s global-session )],
on_connect => [ 'set status on', 'set-option prefix C-k', ],
},
'ansible-host' => {
initialize => [qw( tmux new-session -d -s ansible )],
on_connect => [ 'set status off', 'set-option set-titles-string "#T"' ],
},
'puppet-host' => {
wm => 'multi',
initialize => [qw( tmux new-session -d -s puppet )],
on_connect => [ 'set status off' ],
},
},
},
}
The value for the terminal key should be set to what your terminal uses to execute a custom command. Examples:
kittyxtermxfce4-terminal -etermit -egnome-terminal -e
To connect to a remote host, a number of conditions should be met for optimal use. First, ensure your local machine has keyed access to the remote host. Second, ensure that SSH multiplexing is allowed. Modern defaults usually allow 10 multiplexed clients. This means you can have 9 windows open, and one control session. This can be increased by modifying MaxSessions in sshd_config on the remote host.
Each host requires a separate instance of tmuxc to be run. Using the above example, you'd run the following:
tmuxc -bto connect to the localhost instance, under the default session of 'global-session', then daemonize tmuxctmuxc -h my.remote.server.com -bto connect to the remote host, under the default session of 'global-session', then daemonize tmuxc.
Hosts and sessions do not need to be in the configuration file. You can simply run tmuxc as-is. The configuration file is just parsed by the internal tmuxc -l launcher mode to present a session selector for you.
When a terminal is closed with out exiting the program running in the tmux window (e.g. exiting a shell), that specific window is marked as 'ignored' for the life of the tmuxc process. That means that when you create a new window, the one you just closed and a new one do not open up. You can re-open all windows for a session by running tmuxc -m and selecting Open All Windows, and then picking a session if multiple exist.
Hotkey integrations
Below is a sample i3 integration:
# Present the session launcher menu
bindsym $mod+equal exec --no-startup-id tmuxc -l
# Present a single-depth menu showing all sessions and the actions allowed for each
bindsym $mod+m exec --no-startup-id tmuxc -M
# Open a new terminal in the running session, or present a menu if multiple sessions are running
bindsym $mod+Return exec --no-startup-id tmuxc -n
Global/host/session options
If the default option is acceptable, you do not need to define it again in a configuration file. However, if you want to change it for a specific host or even a specific session, you can do so. Define the configuration key and value at the appropriate level, and it will override that setting.
alive_count (default 2): Set the SSHServerAliveCountMaxoption for control master connections.alive_interval (default 3): Set the SSHServerAliveIntervaloption for control master connections.background (default 0): Set to 1 to automatically detach/background the tmuxc process after launch.blacklist (default []): An array of tmux window names that never get a terminal opened for them. Inherits as described in Inheriting array options.conn_timeout (default 3): Set the SSHConnectTimeoutoption for control master connections.detach (default 0): Set to 1 to attempt to detach all other clients connected to the TMUX session.env_prefix (default TMUX_SESSION): Combine this prefix with_NAMEand inject the tmux session name into the environment.exitlast (default 1): Exit the control daemon after the last window in the tmux session exits, or after the terminal is closed in single-window-mode. Set to 0 to keep the daemon running and re-create the session instead.hook (default {}): A hash passed tohook_subfor each terminal. The most specific level that defines it wins; hashes from different levels aren't merged. See Terminal hook.hook_sub (default unset): Global only. A code ref, or the absolute path of a file that returns one, called before each terminal opens. See Terminal hook.input_prompt (default rofi -dmenu -p): Define the prompt for user input, notably when creating an ephemeral session.log_facility (default ""): Define the syslog log facility.log_level (default 5): Define the logging level, values of 5, 6 or 7 are accepted.on_connect (default[]): Define an array of tmux commands to be sent to the session a terminal attaches to. In single-window-mode they run once against the control session; in multi-window-mode they run against each cloned session as its terminal is opened. Commands without-tapply to that session.persist (default 10s): Set the SSHControlPersistoption for control master connections.prereq_interval (default 1): Seconds between passes overssh_prereqswhile one of them fails, timed from the start of each pass. If a pass takes longer than this, the next one starts right away.prettyps (default 1): Control the process name on the command line, reducing it tobinaryname session@host.poe (default none): Enable purge-on-exit forephemeraloranysessions. This will execute akill-sessionagainst the session on exit.reconnect (default 1): Attempt to reconnect to the remote host and re-open windows if SSH drops. This is useful for laptops that are suspended frequently.selector (default: rofi -dmenu -i): Define the menu command, used for picking a session / session action.skipnw (default 0):tmuxc -nskips the session when choosing which running session to open a new window in, unless-hor-sis given. Only read from the session's own entry, not from the host or global level.ssh_args(default []): Additional arguments to add to each SSH connection.ssh_prereqs(default []): An array of commands run in order on the local host before each attempt to create an SSH ControlMaster connection. If one exits non-zero, the remaining commands are skipped. Withreconnectenabled,tmuxcruns the list again from the top everyprereq_intervalseconds until every command passes, without adding to the SSH reconnect backoff; otherwise it exits. Inherits as described in Inheriting array options.ssh_control(default %C): SSH tokens to name the ControlMaster path. Refer tossh_config(5)for more details.temp (default $HOME/.tmuxc/): The location of the runtime temp directory. While this can be changed on a per-host and per-session basis, it should be avoided.tmuxcuses a shared directory to discover other running instances and to insert commands into other running sessions. Unless a shared directory is used, instances will be 'lost' to each other.terminal (default xterm): The default terminal to use when opening up new windows.tmux_bin (default tmux): The name of the tmux binary to use, can also include the full path like/home/user/bin/tmux-3.0.wm (default multi): Window mode.multiopens a terminal for each window in the tmux session.singleis the traditional approach to tmux, it simply opens a terminal with your full tmux session attached in it. Refer toon_connectfor session tuning (set status on, for example, if it's off by default.) tmuxc sets the session option@tmuxc_wmto the window mode on each session its terminals attach to; see .tmux.conf changes.
Inheriting array options
blacklist and ssh_prereqs can be set globally, per host and per session. The most specific level that defines the key wins, and the levels above it are ignored. To include the values from the level above, add the element '@inherit%parent%' to the array at the position they should appear. Levels that don't define the key are skipped, so a session's '@inherit%parent%' reaches the global value when its host doesn't define the key. A level that defines the key without '@inherit%parent%' stops inheritance there; an empty array opts out entirely. Write the element in single quotes or qw(), since Perl interpolates @inherit inside double quotes.
{
ssh_prereqs => [ 'vpn-up' ],
hosts => {
'work.host' => {
ssh_prereqs => [ '@inherit%parent%', 'ping -c1 -W1 work.host' ], # vpn-up, then ping
'global-session' => {
ssh_prereqs => [ '@inherit%parent%', 'check-session-thing' ], # vpn-up, ping, then this
},
},
'home.host' => {
ssh_prereqs => [], # no prereqs for this host
},
},
}
Run tmuxc -h <host> -s <session> -o to see the merged configuration values for a given host and session. Values under Runtime are generated by tmuxc and can't be configured. Unknown keys lists top-level keys tmuxc doesn't use, which usually means a typo.
Terminal hook
hook_sub is called each time tmuxc opens a terminal, in both window modes, with the session's hook hash and a context hash. It can return an array ref of extra terminal arguments, which are inserted right after the terminal binary, ahead of options such as -e. If it dies, the error is logged and the terminal opens without them. It runs inside tmuxc before the terminal starts, so keep it quick.
The context for window @12 of global-session on shellhost.test.com, from a machine named laptop, in multi-window-mode:
{
host => 'shellhost.test.com',
session => 'global-session',
target => 'tmuxc/laptop/global-session/12',
name => 'tmuxc-laptop-global-session-12',
wm => 'multi',
temp => '/home/user/.tmuxc/',
}
and for weechat in single-window-mode:
{
host => 'shellhost.test.com',
session => 'weechat',
target => 'tmuxc/laptop/weechat',
name => 'tmuxc-laptop-weechat',
wm => 'single',
temp => '/home/user/.tmuxc/',
}
target is the tmux session the terminal attaches to, and name is the target with / replaced by -: unique per terminal on the local machine, but not across remote hosts. host is localhost for local sessions, and temp always ends in /.
When hook_sub is a path, the file is loaded on every configuration load, so a reload picks up changes. Its last expression must be the code ref. Like the configuration file it runs inside tmuxc, so keep to my variables and anonymous subs. If it can't be loaded, tmuxc logs why and opens terminals without a hook.
extras/kwin is a hook that places terminals with KWin.