{"id":13474747,"url":"https://github.com/zolrath/wemux","last_synced_at":"2025-05-14T21:08:20.532Z","repository":{"id":2654761,"uuid":"3645373","full_name":"zolrath/wemux","owner":"zolrath","description":"Multi-User Tmux Made Easy","archived":false,"fork":false,"pushed_at":"2022-10-03T08:50:52.000Z","size":633,"stargazers_count":3646,"open_issues_count":36,"forks_count":142,"subscribers_count":71,"default_branch":"master","last_synced_at":"2025-04-13T17:46:57.765Z","etag":null,"topics":["bash-script","multiuser","tmux"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zolrath.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-03-07T03:23:41.000Z","updated_at":"2025-04-12T13:53:00.000Z","dependencies_parsed_at":"2022-09-01T07:21:41.332Z","dependency_job_id":null,"html_url":"https://github.com/zolrath/wemux","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zolrath%2Fwemux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zolrath%2Fwemux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zolrath%2Fwemux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zolrath%2Fwemux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zolrath","download_url":"https://codeload.github.com/zolrath/wemux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219281,"owners_count":22034380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash-script","multiuser","tmux"],"created_at":"2024-07-31T16:01:14.502Z","updated_at":"2025-05-14T21:08:15.515Z","avatar_url":"https://github.com/zolrath.png","language":"Shell","funding_links":[],"categories":["Shell","User Interaction","Interaction","Command-Line Productivity","others"],"sub_categories":["Command Line Interface","Command Line"],"readme":"![wemux: Multi-User Tmux Sessions Made Easy](http://i.imgur.com/iOjcz.png)\n********************************************************************************\n\nwemux enhances tmux to make multi-user terminal multiplexing both easier and\nmore powerful. It allows users to host a wemux server and have clients join\nin either:\n\n**Mirror Mode** gives clients (another SSH user on your machine) read-only\naccess to the session, allowing them to see you work, or\n\n**Pair Mode** allows the client and yourself to work in the same terminal\n(shared cursor)\n\n**Rogue Mode** allows the client to pair or work independently in another\nwindow (separate cursors) in the same tmux session.\n\nIt features multi-server support as well as user listing\nand notifications when users attach/detach.\n\n## How To Install\n  **IMPORTANT**: Wemux requires tmux version \u003e= 1.6\n  \n### MacPorts (on OS X)\n  If you have [MacPorts](https://www.macports.org/) installed you can\n  install wemux with a very simple:\n\n    sudo port install wemux\n\n### Homebrew (on OS X)\n  If you have [Homebrew](http://mxcl.github.com/homebrew/) installed you can\n  install wemux with a fairly simple:\n\n    brew install wemux\n\n  The user that installed wemux will automatically be added to the wemux host list.\n  To change the host or add more hosts, edit `/usr/local/etc/wemux.conf` and add the\n  username to the host_list array.\n\n  Users in the host_list will be able to start new wemux servers, all other\n  users will be wemux clients and join these servers.\n\n    $ vim /usr/local/etc/wemux.conf\n         OR\n    $ wemux conf\n\n    host_list=(zolrath brocksamson)\n\n### Manual Installation\n  The rest of this readme will operate under the assumption you'll place wemux\n  in `wemux/` in your `/usr/local/share` directory. To make wemux available for\n  all users, perform the following steps, using sudo as required:\n\n  Git clone this repo.\n\n    git clone git://github.com/zolrath/wemux.git /usr/local/share/wemux\n\n  Symlink the `wemux` file into your $PATH via `/usr/local/bin/`,\n  being sure to use the full path.\n\n    ln -s /usr/local/share/wemux/wemux /usr/local/bin/wemux\n\n  **IMPORTANT**: Copy the `wemux.conf.example` file to `/usr/local/etc/wemux.conf`\n\n    cp /usr/local/share/wemux/wemux.conf.example /usr/local/etc/wemux.conf\n\n  Then set a user to be a wemux host by adding their username to the host_list in\n  `/usr/local/etc/wemux.conf`. Users in the host_list will be able to start new wemux\n  servers, all other users will be wemux clients and join these servers.\n\n    vim /usr/local/etc/wemux.conf\n    host_list=(zolrath brocksamson)\n\n  To upgrade to a new version of wemux return to the `/usr/local/share/wemux`\n  directory and perform a `git pull`\n\n## Host Commands\n#### wemux start\n  Use `wemux start` to start a wemux server, chmod /tmp/wemux-wemux to 1777 so\n  that other users may connect to it, and attach to it.  If a wemux server\n  already exists, it will attach to it instead.\n#### wemux attach\n  Use `wemux attach` to attach to an existing wemux server.\n#### wemux stop\n  Use `wemux stop` to kill the wemux server and remove the /tmp/wemux-wemux\n  socket.\n#### wemux kick *username*\n  Use `wemux kick \u003cusername\u003e` to kick an SSH user from the server and remove\n  their wemux rogue sessions.\n#### wemux config\n  Use `wemux config` to open `/usr/local/etc/wemux.conf` in your $EDITOR.\n  Note this only works if you have the environment variable EDITOR configured.\n#### wemux\n  When `wemux` is run without any arguments in host mode, it is just like\n  running wemux start.  It will reattach to an existing wemux server if it\n  exists, otherwise it will start a new server.\n\n## Client Commands\n#### wemux mirror\n  Use `wemux mirror` to attach to server in read-only mode.\n#### wemux pair\n  Use `wemux pair` to attach to server in pair mode, allowing the client to \n  control the terminal as well.\n#### wemux rogue\n  Use `wemux rogue` to attach to server in rogue mode, which allows both editing\n  with the host and switching to windows independently from the host.\n#### wemux logout\n  Use `wemux logout` to remove your rogue mode session.\n#### wemux\n  When `wemux` is run without any arguments in client mode, its behavior\n  attempts to intelligently select mirror, pair, or rogue:\n\n  * If the client does not have an existing rogue session it will attach to the\n  wemux server in pair mode.\n  * If the client has already started a wemux rogue session, it will\n  reattach to the server in rogue mode.\n  * If both rogue and pair mode are disabled, it will attach in mirror mode.\n  * By setting `default_client_mode=\"rogue\"` in `wemux.conf` this can be changed\n  to always join in rogue mode, even if a rogue session doesn't already exist.\n\n#### Other Commands\n  wemux passes commands it doesn't understand through to tmux with the correct\n  socket setting.\n\n  `wemux list-sessions` is equivalent to entering `tmux -S /tmp/wemux-wemux\n  list-sessions`\n\n## User List\n  wemux can display a list of connected users, indicating users in mirror mode\n  with [m] at the end of their name.\n\n  If you'd like to see a list of all users currently connected to the wemux\n  server, you have three options:\n\n### wemux users\n  Enter `wemux users` in the terminal to display a list of all currently\n  connected wemux users.\n\n    $ wemux users\n    Users connected to 'wemux':\n      1. zolrath\n      2. csagan[m]\n\n### Status Bar\n  You can add the user list to your status bar by adding #(wemux status_users)\n  where you see fit by editing your `~/tmux.conf` file.\n\n    set -g status-right \"#(wemux status_users)\"\n\n### Display Message\n  If you'd rather display users on command via a tmux message, similar to the\n  user attachment/detachment messages, you can do so by editing your\n  `~/tmux.conf` file.  Pick whatever key you'd like to bind the displaying the\n  message to. Using t as an example:\n\n    unbind t\n    bind t run-shell 'wemux display_users'\n\n  Note that the tmux prefix should be pressed before t to activate the command.\n\n  User listing can be disabled by setting `allow_user_list=\"false\"` in\n  `wemux.conf`\n\n### Short-form Commands\n  All commands have a short form. s for start, a for attach, p for pair etc.\n  For a complete list, type `wemux help` (or `wemux h`)\n\n# Multi-Host Capabilities\n********************************************************************************\n\n  wemux supports specifying the joining different wemux servers via `wemux join\n  \u003cserver\u003e`. This allows multiple hosts on the same machine to host their own\n  independent wemux servers with their own clients. By default this option is\n  disabled.\n\n  wemux will remember the last server specified to in order to make reconnecting\n  to the same server easy. `wemux help` will output the currently specified\n  server along with the wemux command list.\n\n  Changing servers can be enabled by setting `allow_server_change=\"true\"` in\n  `/usr/local/etc/wemux.conf`\n\n### Joining Different wemux Servers\n  To change the wemux server run `wemux join \u003cserver\u003e`. The name will be sanitized to contain no spaces or uppercase letters.\n\n    $ wemux join Project X\n    Changed wemux server from 'wemux' to 'project-x'\n    $ wemux\n    $ wemux stop\n    $ wemux reset\n    Changed wemux server from 'project-x' to 'wemux'\n\n#### wemux join *servername*\n  Join wemux server with specified name.\n\n    $ wemux join rails\n    Changed wemux server from 'wemux' to 'rails'\n\n#### wemux join *servernumber*\n  Alternatively, enter the server number displayed next to the server name in `wemux list`.\n\n    $ wemux j 1\n    Changed wemux server from 'rails' to 'project-x'\n\n#### wemux join\n  Join with no argument simply displays the current wemux server, if you're into that.\n\n    $ wemux join\n    Current wemux server: wemux\n\n### Resetting the Server Name\n  In order to easily return to the default server you can run `wemux reset`\n#### wemux reset\n  Joins the default wemux server: wemux (or value of default_server_name in wemux.conf)\n\n    $ wemux reset\n    Changed wemux server from 'project-x' to 'wemux'\n\n### Active Server List\n  To list the name of all currently running wemux servers run `wemux list`\n#### wemux list\n  List all currently active wemux servers.\n\n    $ wemux list\n    Currently active wemux servers:\n      1. project-x\n      2. rails\n      3. wemux    \u003c- current server\n\n  `wemux join` and `wemux stop` both accept either the name of a server or\n  the number indicated next to the name in `wemux list`.\n\n  Listing servers can be disabled by setting `allow_server_list=\"false\"` in\n  `/usr/local/etc/wemux.conf`\n\n# Configuration\n********************************************************************************\n\n  There are a number of additional options that be configured in\n  `/usr/local/etc/wemux.conf`.  In most cases the only option that must be changed is the\n  `host_list` array. To open your wemux configuration file, you can either open\n  `/usr/local/etc/wemux.conf` manually or run `wemux config`\n\n### Host Mode\n  To have an account act as host, ensure that you have added their username to the\n  `/usr/local/etc/wemux.conf` file's `host_list` array.\n\n    host_list=(zolrath hostusername brocksamson)\n\n### Pair Mode\n  Pair mode can be disabled, only allowing clients to attach to the server in\n  mirror mode by setting `allow_pair_mode=\"false\"`\n\n### Rogue Mode\n  Rogue mode can be disabled, only allowing clients to attach to the server in\n  mirror or pair mode by setting `allow_rogue_mode=\"false\"`\n\n### Default Client Mode\n When clients enter 'wemux' with no arguments by default it will first attempt to\n join an existing rogue mode session. If there is no rogue session it will start\n in pair mode.\n By setting default_client_mode to \"rogue\", 'wemux' with no arguments will always\n join a rogue mode session, even if it has to create it.\n\n  This can be changed by setting `default_client_mode=\"rogue\"`\n\n### Default Server Name\n  The default wemux server name will be used with `wemux reset` and when\n  `allow_server_name` is not enabled in `wemux.conf`.\n\n  This can be changed by setting `default_server_name=\"customname\"`\n\n### Changing Servers\n  The ability to change servers can be enabled by setting\n  `allow_server_change=\"true\"`\n\n### Listing Servers\n  Listing servers can be disabled by setting `allow_server_list=\"false\"`\n\n### Listing Users\n  Listing users can be disabled by setting `allow_user_list=\"false\"` in\n  `wemux.conf`\n\n### Kicking SSH Users\n  Kicking SSH users from the server can be disabled by setting\n  `allow_kick_user=\"false\"` in `wemux.conf`\n\n### Announcements\n  When a user joins a server in either mirror, pair, or rogue mode, a message is\n  displayed to all currently attached users:\n\n    csagan has attached in mirror mode.\n    csagan has detached.\n\n This can be disabled by setting `announce_attach=\"false\"`\n\n In addition, when a user switches from one server to another via the `wemux\n join \u003cservername\u003e` command, their movement is displayed similarly to the\n attach messages.\n\n  If csagan enters `wemux join applepie` the users on the default server\n  `wemux` will see:\n\n    csagan has switched to server: applepie\n\n  If csagan returns to default server with: `wemux reset` users on `wemux`\n  will see:\n\n    csagan has joined this server.\n\n  This can be disabled by setting `announce_server_change=\"false\"`\n\n### Automatic SSH Client Modes\n  To make an SSHed user start in a wemux mode automatically, add one of the\n  following lines to the users `.bash_profile` or `.zshrc`\n\n  **Option 1**: Automatically log the client into mirror mode upon login,\n  disconnect them from the server when they detach.\n\n    wemux mirror; exit\n\n  **Option 2**: Automatically start the client in mirror mode but allow them to\n  detach.\n\n    wemux mirror\n\n  **Option 3**: Automatically start the client in pair mode but allow them to\n  detach.\n\n    wemux pair\n    \n  **Option 4**: Automatically start the client in rogue mode but allow them to\n  detach.\n\n    wemux rogue\n\n  **Option 5**: Only display the connection commands, don't automatically start\n  any modes.\n\n    wemux help\n\n  Please note that this does not ensure a logged in user will not be able to exit\n  tmux and access their shell. If the user is not trusted, you must perform any\n  security measures one would normally perform for a remote user.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzolrath%2Fwemux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzolrath%2Fwemux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzolrath%2Fwemux/lists"}