{"id":50772571,"url":"https://github.com/tmux-contrib/tmux-layout","last_synced_at":"2026-06-11T20:30:18.971Z","repository":{"id":357573235,"uuid":"1237380655","full_name":"tmux-contrib/tmux-layout","owner":"tmux-contrib","description":"Declarative tmux sessions in YAML — define windows and panes once, then `tmux-layout switch dev`.","archived":false,"fork":false,"pushed_at":"2026-06-08T02:16:19.000Z","size":33,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T04:13:08.081Z","etag":null,"topics":["bash","cli","developer-tools","dotfiles","productivity","session-manager","terminal","tmux","tmux-plugin","yaml"],"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/tmux-contrib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T06:09:30.000Z","updated_at":"2026-06-04T03:19:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tmux-contrib/tmux-layout","commit_stats":null,"previous_names":["tmux-contrib/tmux-layout"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tmux-contrib/tmux-layout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-layout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-layout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-layout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-layout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmux-contrib","download_url":"https://codeload.github.com/tmux-contrib/tmux-layout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmux-contrib%2Ftmux-layout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34217312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","cli","developer-tools","dotfiles","productivity","session-manager","terminal","tmux","tmux-plugin","yaml"],"created_at":"2026-06-11T20:30:17.313Z","updated_at":"2026-06-11T20:30:18.953Z","avatar_url":"https://github.com/tmux-contrib.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmux-layout\n\n\u003e Stop hand-rolling tmux sessions. Declare your windows and panes in a YAML\n\u003e file once, then jump back into the same workspace any time with a single\n\u003e command — Nix dev shell aware, env-substitution included.\n\n[![CI](https://github.com/tmux-contrib/tmux-layout/actions/workflows/ci.yml/badge.svg)](https://github.com/tmux-contrib/tmux-layout/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/tmux-contrib/tmux-layout)](https://github.com/tmux-contrib/tmux-layout/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n```sh\ntmux-layout switch dev\n```\n\n## Install\n\n### Zsh plugin\n\n```zsh\n# zinit\nzinit light tmux-contrib/tmux-layout\n\n# antidote (in ~/.zsh_plugins.txt)\ntmux-contrib/tmux-layout\n\n# oh-my-zsh\ngit clone https://github.com/tmux-contrib/tmux-layout \\\n  \"${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/tmux-layout\"\n# then add `tmux-layout` to plugins=(...) in ~/.zshrc\n```\n\nThe plugin file simply prepends the repo directory to `$PATH` so the\n`tmux-layout` script becomes available as a command.\n\n### Nix\n\n```sh\nnix run github:tmux-contrib/tmux-layout -- switch dev\n# or install:\nnix profile install github:tmux-contrib/tmux-layout\n```\n\n### Manual\n\n```sh\ngit clone https://github.com/tmux-contrib/tmux-layout\nln -s \"$PWD/tmux-layout/tmux-layout\" /usr/local/bin/tmux-layout\n```\n\n### Dependencies\n\n- Bash 4.4+\n- `tmux`\n- [`yq`](https://github.com/mikefarah/yq) (Go, mikefarah/yq) —\n  `brew install yq` or `nix profile install nixpkgs#yq-go`\n- `envsubst` (from gettext) — preinstalled on most Linux/Nix systems;\n  macOS: `brew install gettext`\n\n## Usage\n\n```sh\ntmux-layout switch \u003cname\u003e    # apply a layout\ntmux-layout list             # list available layouts\ntmux-layout --help\ntmux-layout switch --help\n```\n\n## Layout file\n\n`~/.config/tmux/layouts/dev.yml`:\n\n```yaml\nsession:\n  name: my-session-name\n  cwd: ~/code # optional; default cwd for every pane\nwindows:\n  - name: my-window-name\n    layout: tiled # optional; passed to `tmux select-layout`\n    cwd: ~/code/myapp # optional; overrides session.cwd for this window\n    panes:\n      - name: my-tig-pane # optional; sets pane title\n        command: \"tig\" # optional; empty leaves pane in default shell\n      - name: my-claude-pane\n        command: \"claude\"\n      - name: my-nvim-pane\n        command: \"nvim\"\n        cwd: ~/code/myapp/src # optional; overrides window.cwd for this pane\n```\n\nA layout may declare multiple `windows`, each with one or more `panes`.\nThe first pane is the window's initial pane; subsequent panes are\ncreated via `tmux split-window`.\n\n## Behavior\n\n- **Inside tmux**: the layout's windows are appended to the current\n  session.\n- **Outside tmux**: a new session named `session.name` is created and\n  attached. If the session already exists, it is attached as-is (no\n  modification) — re-running is safe.\n- **Working directory**: `cwd:` may be set at session, window, or pane\n  level. Precedence is **pane \u003e window \u003e session**, so a window-level\n  `cwd` applies to all its panes unless a pane overrides it. A leading\n  `~` expands to `$HOME`; `${VAR}` forms are expanded via `envsubst`\n  (see below); anything else is passed to `tmux -c` as-is (absolute or\n  relative to wherever tmux is invoked).\n- **Nix dev shells**: if `IN_NIX_SHELL` is set, every pane command is\n  run as `nix develop -c \"$SHELL\" -c \"\u003ccmd\u003e\"` so tools defined in the\n  dev shell remain available and shell features (pipes, `\u0026\u0026`, aliases)\n  work inside the pane command.\n- **Env substitution**: `${VAR}` references in the YAML are expanded\n  via `envsubst` before parsing, e.g.:\n\n  ```yaml\n  session:\n    name: \"${USER}-dev\"\n  windows:\n    - name: editor\n      panes:\n        - command: \"${EDITOR:-vim}\"\n  ```\n\n  Substitution happens at parse time, not at command run time, so any\n  `$VAR` in a `command:` is expanded by `envsubst` (not by the shell at\n  runtime).\n\n## License\n\n[MIT](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmux-contrib%2Ftmux-layout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmux-contrib%2Ftmux-layout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmux-contrib%2Ftmux-layout/lists"}