{"id":13394875,"url":"https://github.com/tmuxinator/tmuxinator","last_synced_at":"2025-05-12T20:46:58.429Z","repository":{"id":1227894,"uuid":"1157388","full_name":"tmuxinator/tmuxinator","owner":"tmuxinator","description":"Manage complex tmux sessions easily","archived":false,"fork":false,"pushed_at":"2025-04-18T16:17:37.000Z","size":978,"stargazers_count":13003,"open_issues_count":99,"forks_count":625,"subscribers_count":145,"default_branch":"master","last_synced_at":"2025-05-05T16:06:48.741Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/tmuxinator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-12-10T21:49:50.000Z","updated_at":"2025-05-05T10:40:55.000Z","dependencies_parsed_at":"2023-01-13T11:02:18.407Z","dependency_job_id":"fd9ed130-361c-4449-a7ff-d987b63c335c","html_url":"https://github.com/tmuxinator/tmuxinator","commit_stats":{"total_commits":705,"total_committers":156,"mean_commits":4.519230769230769,"dds":0.8326241134751773,"last_synced_commit":"b15ddb9569b3c9ee39f9242030ae1d8b5b684521"},"previous_names":["aziz/tmuxinator"],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmuxinator%2Ftmuxinator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmuxinator%2Ftmuxinator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmuxinator%2Ftmuxinator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmuxinator%2Ftmuxinator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmuxinator","download_url":"https://codeload.github.com/tmuxinator/tmuxinator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253819147,"owners_count":21969297,"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":[],"created_at":"2024-07-30T17:01:34.755Z","updated_at":"2025-05-12T20:46:58.410Z","avatar_url":"https://github.com/tmuxinator.png","language":"Ruby","readme":"# Tmuxinator\n\n[![Gem Version](https://badge.fury.io/rb/tmuxinator.svg)](http://badge.fury.io/rb/tmuxinator) [![Integration Tests](https://github.com/tmuxinator/tmuxinator/actions/workflows/ci.yaml/badge.svg)](https://github.com/tmuxinator/tmuxinator/actions/workflows/ci.yaml) [![Coverage Status](https://img.shields.io/coveralls/tmuxinator/tmuxinator.svg)](https://coveralls.io/r/tmuxinator/tmuxinator?branch=master) [![Code Climate](https://codeclimate.com/github/tmuxinator/tmuxinator/badges/gpa.svg)](https://codeclimate.com/github/tmuxinator/tmuxinator) [![Dependency Status](https://gemnasium.com/tmuxinator/tmuxinator.svg)](https://gemnasium.com/tmuxinator/tmuxinator) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tmuxinator/tmuxinator?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\nCreate and manage tmux sessions easily.\n\n\u003ctable\u003e\n    \u003ctbody\u003e\n        \u003ctr align=\"center\"\u003e\n            \u003ctd\u003e\n                \u003cimg src=\"https://user-images.githubusercontent.com/289949/44366875-1a6cee00-a49c-11e8-9322-76e70df0c88b.gif\" alt=\"Screenshot\" width=\"80%\" /\u003e\n            \u003c/td\u003e\n        \u003c/tr\u003e\n    \u003c/tbody\u003e\n\u003c/table\u003e\n\n## Installation\n\n### RubyGems\n```\ngem install tmuxinator\n```\n\n### Homebrew\n```\nbrew install tmuxinator\n```\n\nSome users have [reported issues](https://github.com/tmuxinator/tmuxinator/issues/841) when installing via Homebrew, so the RubyGems installation is preferred until these are resolved.\n\ntmuxinator aims to be compatible with [the currently maintained versions of Ruby](https://www.ruby-lang.org/en/downloads/).\n\nSome operating systems may provide an unsupported version of Ruby as their \"system ruby\". In these cases, users should use [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv) to install a supported Ruby version and use that version's `gem` binary to install tmuxinator.\n\n## Editor and Shell\n\ntmuxinator uses your shell's default editor for opening files. If you're not\nsure what that is type:\n\n``` bash\necho $EDITOR\n```\n\nFor me that produces \"vim\". If you want to change your default editor simply\nput a line in ~/.bashrc that changes it. Mine looks like this:\n\n```bash\nexport EDITOR='vim'\n```\n\n## tmux\n\nThe recommended version of tmux to use is 1.8 or later, with the exception of 2.5, which is **not** supported (see [issue 536](https://github.com/tmuxinator/tmuxinator/issues/536) for details). Your mileage may vary for\nearlier versions. Refer to the FAQ for any odd behaviour.\n\n## Completion\n\nYour distribution's package manager may install the completion files in the\nappropriate location for the completion to load automatically on startup. But,\nif you installed tmuxinator via Ruby's `gem`, you'll need to run the following\ncommands to put the completion files where they'll be loaded by your shell.\n\n### bash\n```bash\nwget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.bash -O /etc/bash_completion.d/tmuxinator.bash\n```\n### zsh\n```bash\nwget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.zsh -O /usr/local/share/zsh/site-functions/_tmuxinator\n```\nNote: ZSH's completion files can be put in other locations in your `$fpath`. Please refer to the [manual](http://zsh.sourceforge.net/Doc/Release/Functions.html) for more details.\n\n### fish\n```bash\nwget https://raw.githubusercontent.com/tmuxinator/tmuxinator/master/completion/tmuxinator.fish -O ~/.config/fish/completions/tmuxinator.fish\n```\n## Usage\n\nA working knowledge of tmux is assumed. You should understand what windows and\npanes are in tmux. If not please consult the [man pages](https://web.archive.org/web/20220308205829/https://man.openbsd.org/OpenBSD-current/man1/tmux.1) for tmux.\n\n### Create a project\n\nCreate or edit your projects with:\n\n```\ntmuxinator new [project]\n```\n\nCreate or edit a local project where the config file will be stored in the\ncurrent working directory (in `.tmuxinator.yml`) instead of the default\nproject configuration file location (e.g. `~/.config/tmuxinator`):\n\n```\ntmuxinator new --local [project]\n```\n\nFor editing you can also use `tmuxinator open [project]`. `new` is aliased to\n`n`,`open` to `o`, and `edit` to `e`. Please note that dots can't be used in project\nnames as tmux uses them internally to delimit between windows and panes.\nYour default editor (`$EDITOR`) is used to open the file.\nIf this is a new project you will see this default config:\n\n```yaml\n# ~/.tmuxinator/sample.yml\n\nname: sample\nroot: ~/\n\n# Optional tmux socket\n# socket_name: foo\n\n# Note that the pre and post options have been deprecated and will be replaced by\n# project hooks.\n\n# Project hooks\n\n# Runs on project start, always\n# on_project_start: command\n\n# Run on project start, the first time\n# on_project_first_start: command\n\n# Run on project start, after the first time\n# on_project_restart: command\n\n# Run on project exit ( detaching from tmux session )\n# on_project_exit: command\n\n# Run on project stop\n# on_project_stop: command\n\n# Runs in each window and pane before window/pane specific commands. Useful for setting up interpreter versions.\n# pre_window: rbenv shell 2.0.0-p247\n\n# Pass command line options to tmux. Useful for specifying a different tmux.conf.\n# tmux_options: -f ~/.tmux.mac.conf\n\n# Change the command to call tmux. This can be used by derivatives/wrappers like byobu.\n# tmux_command: byobu\n\n# Specifies (by name or index) which window will be selected on project startup. If not set, the first window is used.\n# startup_window: editor\n\n# Specifies (by index) which pane of the specified window will be selected on project startup. If not set, the first pane is used.\n# startup_pane: 1\n\n# Controls whether the tmux session should be attached to automatically. Defaults to true.\n# attach: false\n\n# Enables the display of pane titles. For example \"editor\" below. Defaults to false.\n# enable_pane_titles: true\n\n# Configures pane title position. Can be: bottom, top, or \"off\". Note: \"off\" must be provided in quotes to avoid being interpreted as a boolean false. Defaults to top.\n# pane_title_position: bottom\n\n# Configures pane title format. Defaults to \"#{pane_index}: #{pane_title}\".\n# Please see the tmux manpage for details, on valid formats.\n# pane_title_format: \" [ #T ] \"\n\nwindows:\n  - editor:\n      layout: main-vertical\n      # Synchronize all panes of this window, can be enabled before or after the pane commands run.\n      # 'before' represents legacy functionality and will be deprecated in a future release, in favour of 'after'\n      # synchronize: after\n      panes:\n        - editor:\n          - vim\n        - guard\n  - server: bundle exec rails s\n  - logs: tail -f log/development.log\n```\n\nIt's also possible to create a new tmuxinator project from an existing tmux\nsession. This can be done by running the following command:\n\n```bash\ntmuxinator new [project] [session]\n```\n\nThis will record the windows, along with their specified layout, panes,\ntmux session options, and project root based on the tmux\ndefault-path of the specified tmux session in the new tmuxinator project.\n\n## Windows\n\nThe windows option allows the specification of any number of tmux windows. Each window is denoted by a YAML array entry, followed by a name* and command to be run.\n\n*Users may optionally provide a null YAML value (e.g. `null` or `~`) in place of a named window key, which will cause the window to use its default name (usually the name of their shell).\n\n```yaml\nwindows:\n  - editor: vim\n```\n\n### Window specific root\n\nAn optional root option can be specified per window:\n\n```yaml\nname: test\nroot: ~/projects/company\n\nwindows:\n  - small_project:\n      root: ~/projects/company/small_project\n      panes:\n        - start this\n        - start that\n```\n\nThis takes precedence over the main root option.\n\n## Panes\n\n**_Note that if you wish to use panes, make sure that you do not have `.` in your project name. tmux uses `.` to delimit between window and pane indices,\nand tmuxinator uses the project name in combination with these indices to target the correct pane or window._**\n\nPanes are optional and are children of window entries, but unlike windows, they do not need a name. In the following example, the `editor` window has 2 panes, one running vim, the other guard.\n\n```yaml\nwindows:\n  - editor:\n      layout: main-vertical\n      panes:\n        - vim\n        - guard\n```\n\nThe layout setting gets handed down to tmux directly, so you can choose from\none of [the five standard layouts](https://web.archive.org/web/20220308205829/https://man.openbsd.org/OpenBSD-current/man1/tmux.1#even-horizontal)\nor [specify your own](http://stackoverflow.com/a/9976282/183537).\n\n**Please note the indentation here is deliberate. YAML's indentation rules can be confusing, so if your config isn't working as expected, please check the indentation.** For a more detailed explanation of _why_ YAML behaves this way, see [this](https://stackoverflow.com/questions/50594758/why-isnt-two-spaced-yaml-parsed-like-four-spaced-yaml/50600253#50600253) Stack Overflow question.\n\n**Note:** If you're noticing inconsistencies when using a custom layout it may\nbe due [#651](https://github.com/tmuxinator/tmuxinator/issues/651). See [this\ncomment](https://github.com/tmuxinator/tmuxinator/issues/651#issuecomment-497780424)\nfor a workaround.\n\n### Pane titles\n\nIt is also possible (starting with tmux v2.6) to give a title to panes.\n\n```yaml\nenable_pane_titles: true\n\nwindows:\n  - editor:\n      layout: main-vertical\n      panes:\n        - editor:\n          - vim\n        - guard\n```\n\n## Interpreter Managers \u0026 Environment Variables\n\nTo use tmuxinator with rbenv, RVM, NVM etc, use the `pre_window` option.\n\n```yaml\npre_window: rbenv shell 2.0.0-p247\n```\n\nThese command(s) will run before any subsequent commands in all panes and windows.\n\n## Custom session attachment\n\nYou can set tmuxinator to skip auto-attaching to the session by using the `attach` option.\n\n```yaml\nattach: false\n```\nIf you want to attach to tmux in a non-standard way (e.g. for a program that makes use of tmux control mode like iTerm2), you can run arbitrary commands by using a project hook:\n\n```yaml\non_project_exit: tmux -CC attach\n```\n\n## Passing directly to send-keys\n\ntmuxinator passes commands directly to send keys. This differs from simply chaining commands together using `\u0026\u0026` or `;`, in that\ntmux will directly send the commands to a shell as if you typed them in. This allows commands to be executed on a remote server over\nSSH for example.\n\nTo support this both the window and pane options can take an array as an argument:\n\n```yaml\nname: sample\nroot: ~/\n\nwindows:\n  - stats:\n    - ssh stats@example.com\n    - tail -f /var/log/stats.log\n  - logs:\n      layout: main-vertical\n      panes:\n        - logs:\n          - ssh logs@example.com\n          - cd /var/logs\n          - tail -f development.log\n```\n\n## ERB\n\nProject files support [ERB](https://en.wikipedia.org/wiki/ERuby#erb) for reusability across environments. Eg:\n\n```yaml\nroot: \u003c%= ENV[\"MY_CUSTOM_DIR\"] %\u003e\n```\n\nYou can also pass arguments to your projects, and access them with ERB. Simple arguments are available in an array named `@args`.\n\nEg:\n```bash\n$ tmuxinator start project foo\n```\n\n```yaml\n# ~/.tmuxinator/project.yml\n\nname: project\nroot: ~/\u003c%= @args[0] %\u003e\n\n...\n```\n\nYou can also pass key-value pairs using the format `key=value`. These will be available in a hash named `@settings`.\n\nEg:\n```bash\n$ tmuxinator start project workspace=~/workspace/todo\n```\n\n```yaml\n# ~/.tmuxinator/project.yml\n\nname: project\nroot: ~/\u003c%= @settings[\"workspace\"] %\u003e\n\n...\n```\n\n## Starting a session\n\nThis will fire up tmux with all the tabs and panes you configured, `start` is aliased to `s`.\n\n```\ntmuxinator start [project] -n [name] -p [project-config]\n```\n\nIf you use the optional `[name]` argument, it will start a new tmux session with the custom name provided. This is to enable reuse of a project without tmux session name collision.\n\nIf there is a `./.tmuxinator.yml` file in the current working directory but not a named project file in `~/.tmuxinator`, tmuxinator will use the local file. This is primarily intended to be used for sharing tmux configurations in complex development environments.\n\nYou can provide tmuxinator with a project config file using the optional `[project-config]` argument (e.g. `--project-config=path/to/my-project.yaml` or `-p path/to/my-project.yaml`). This option will override a `[project]` name (if provided) and a local tmuxinator file (if present).\n\n## Shorthand\n\nThe [shell completion files](#completion) also include a shorthand alias for tmuxinator that can be used in place of the full name*.\n\n```\nmux [command]\n```\n\n*The `mux` alias has been removed from the Zsh completion script because it was resulting in unexpected behavior in some setups. Including aliases in completion scripts is not standard practice and the Bash and Fish aliases may be removed in a future release. Going forward, users should create their own aliases in their shell's RC file (e.g. `alias mux=tmuxinator`).\n\n## Other Commands\n\nCopy an existing project. Aliased to `c` and `cp`\n```\ntmuxinator copy [existing] [new]\n```\n\nList all the projects you have configured. Aliased to `l` and `ls`\n```\ntmuxinator list\n```\n\nStop a project.\n```\ntmuxinator stop [project]\n```\n\nStop all active projects.\n```\ntmuxinator stop-all\n```\n\nRemove a project. Aliased to `rm`\n```\ntmuxinator delete [project]\n```\n\nRemove all tmuxinator configs, aliases and scripts. Aliased to `i`\n```\ntmuxinator implode\n```\n\nExamines your environment and identifies problems with your configuration\n```\ntmuxinator doctor\n```\n\nShows tmuxinator's help. Aliased to `h`\n```\ntmuxinator help\n```\n\nShows the shell commands that get executed for a project\n```\ntmuxinator debug [project]\n```\n\nShows tmuxinator's version.\n```\ntmuxinator version\n```\n\nAppend a project's windows to the current session (instead of creating a new session)\n```\ntmuxinator start [project] --append\n```\n\n## Project Configuration Location\n\nUsing environment variables, it's possible to define which directory\ntmuxinator will use when creating or searching for project config\nfiles. (See [PR #511](https://github.com/tmuxinator/tmuxinator/pull/511).)\n\nTmuxinator will attempt to use the following locations (in this order) when\ncreating or searching for existing project configuration files:\n\n- `$TMUXINATOR_CONFIG`\n- `$XDG_CONFIG_HOME/tmuxinator`\n- `~/.tmuxinator`\n\n## FAQ\n\n### Window names are not displaying properly?\n\nAdd `export DISABLE_AUTO_TITLE=true` to your `.zshrc` or `.bashrc`\n\n### Commands being lost or corrupted\n\nIf a lot of commands or long commands are sent to a pane, and commands or characters seem to be lost or corrupted, it could be that the TTY typeahead buffer is full and losing new characters. This may happen when an earlier command takes a long time to complete. This seems to affect macOS with zsh more than other platforms.\n\nWhen this occurs, try putting your commands in a separate script and calling that from your tmuxinator configuration using e.g.: `source`.\n\n## Contributing\n\nTo contribute, please read the [contributing guide](https://github.com/tmuxinator/tmuxinator/blob/master/CONTRIBUTING.md).\n\n## Copyright\n\nCopyright (c) 2010-2020 Allen Bargi, Christopher Chow. See LICENSE for further details.\n","funding_links":[],"categories":["CLI Utilities","Ruby","Terminal","Awesome Ruby CLIs","others","终端","Tools","Tools and Plugins","Programming Languages","Developer Tools","Command line - Linux","开发者工具","\u003ca name=\"tools\"\u003e\u003c/a\u003eTools and session management"],"sub_categories":["Packages","Workflow","网络服务_其他","Ruby","Windows","Command Line Tools","Learning resources","命令行工具"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmuxinator%2Ftmuxinator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmuxinator%2Ftmuxinator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmuxinator%2Ftmuxinator/lists"}