convez.ai
SkillDevOps & InfraestruturaIntermediário
rayhon

tmux-worktrees

rayhon/tmux-worktrees

Gerenciador de sessões tmux para git worktrees com múltiplos serviços

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill Claude Code que gerencia sessões de desenvolvimento em tmux para git worktrees. Cada worktree recebe sua própria janela tmux com painéis para cada serviço definido em um arquivo `tmux-worktree.yaml`, permitindo orquestração integrada de múltiplos ambientes de desenvolvimento.

Instalação

$npx convez-ai rayhon/tmux-worktrees

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Gerenciar múltiplas branches com seus próprios ambientes isolados
  • Orquestrar APIs, frontends e outros serviços simultaneamente em tmux
  • Navegar entre worktrees e painéis com atalhos teclado integrados

Veredito

Ferramenta especializada para fluxo de desenvolvimento com git worktrees, integrando Claude Code com tmux de forma limpa. Reduz fricção ao gerenciar múltiplos ambientes paralelos, embora exija configuração por projeto e familiaridade com tmux.

README

A tradução para o português deste README ainda está na fila.

tmux-worktrees

A Claude Code skill that manages a tmux dev session for git worktrees. Each worktree gets its own tmux window with panes for every service defined in a tmux-worktree.yaml file at the repo root.

Overall View

  • Top: worktree selector
  • Bottom: agent and services quick view

Worktree View

  • Bottom left: worktrees — Shift + ←/→ to navigate between them
  • Bottom right: agent + service labels — Alt + ←/→ cycles through the panes, active one highlights yellow

Install

bash <(curl -fsSL https://raw.githubusercontent.com/rayhon/tmux-worktrees/main/install.sh)

Downloads the skill to ~/.claude/skills/tmux-worktrees/ and wires the global WorktreeCreate hook in ~/.claude/settings.json. Run once per machine.

Per-repo setup

Drop a tmux-worktree.yaml at your repo root:

main:
  label: CLAUDE
  # -c resumes the last session in this worktree; falls back to a fresh
  # session on first launch. --dangerously-skip-permissions auto-approves
  # all tool calls so you don't have to babysit every worktree.
  cmd: claude -c --dangerously-skip-permissions || claude --dangerously-skip-permissions

# Global env vars exported into every service pane (per-service `env:` overrides)
env:
  API_URL: "{API_URL}"
  NEXT_PUBLIC_API_URL: "{API_URL}"

services:
  - label: API
    cwd: backend
    port: 3100
    cmd: PORT={PORT} npm run dev

  - label: WEB
    cwd: frontend
    port: 3000
    env:                             # per-service additions/overrides
      AUTH_TRUSTED_ORIGINS: "{WEB_URL}"
      APP_URL: "{WEB_URL}"
    cmd: PORT={PORT} npm run dev

That's it. The hook is already active globally.

Heads up on --dangerously-skip-permissions: auto-approves every tool call Claude makes (writes, deletes, shell commands). Each worktree is in its own isolated folder so the blast radius is contained, but you're giving up the per-call prompt. Use cmd: claude if you'd rather keep the prompts.

Usage

claude --worktree feature-xyz   # creates worktree + symlinks env + npm install + adds tmux window
/tmux-worktrees                 # prepares the tmux session

/tmux-worktrees (invoked from inside Claude Code) sets up the tmux session in the background. Claude Code can't attach a TTY itself, so attach from your terminal:

tmux -L wt attach -t wt

You only need to attach once — re-running /tmux-worktrees after adding worktrees just refreshes the session you're already attached to.

Navigation

Mouse mode is on by default — the scroll wheel scrolls pane/Claude history and a drag-select copies to your system clipboard. Everything is also keyboard-driven:

ActionKeys
Cycle through panes within a worktreeAlt + ←/→ (or ↑/↓) — wraps around CLAUDE → MCP → AGENT → WEB
Switch between worktreesShift + ←/→
Worktree picker (with live preview)Alt + w
Pane pickerAlt + m
Toggle mouse modeCtrl+b m — turn off briefly for clean native terminal selection

The active pane shows up two ways: a bright pane (others dim gray) and the matching label highlighted in yellow in the top status bar.

Copy/paste

With the default mouse on, hold your terminal's bypass modifier and drag — on iTerm2/Terminal.app that's ⌥ Option + drag. Your terminal's native selection takes over, highlight stays, ⌘C copies, ⌘V pastes. No tmux highlight, no OSC 52, no clipboard wipes.

(A plain drag without the modifier is captured by tmux's mouse mode and piped to the system clipboard via pbcopy / wl-copy / xclip — that also works, but Option+drag gives the cleaner native selection.)

Hold the per-terminal bypass key while dragging:

TerminalHold while dragging (mouse mode ON)
iTerm2, Terminal.app⌥ Option
Alacritty, Ghostty, WezTerm⇧ Shift
KittyCtrl+Shift

Scrolling Claude's history

With the default mouse on, the scroll wheel enters tmux copy-mode and scrolls the pane's history (including Claude's chat) directly — no extra setup. If you've toggled mouse OFF via Ctrl+b m, the wheel falls back to your terminal's own scrollback instead; in that case use the keyboard:

ApproachHow
Wheel (default, mouse ON)Just scroll — tmux copy-mode shows the pane history. Press q to exit copy-mode.
Keyboard (works everywhere)fn + shift + ↑ / fn + shift + ↓ on a Mac laptop (= Shift+PageUp/PageDown). iTerm sends these to the alt-screen app directly.

macOS Option+arrow inside VS Code

VS Code intercepts Option+arrow for editor word-nav before tmux sees it. To make pane cycling work, add this to your VS Code keybindings.json:

{ "key": "alt+left",  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "" }, "when": "terminalFocus" },
{ "key": "alt+right", "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "" }, "when": "terminalFocus" },
{ "key": "alt+up",    "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "" }, "when": "terminalFocus" },
{ "key": "alt+down",  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "" }, "when": "terminalFocus" }

In iTerm2/Terminal.app, just enable Option-as-Meta in profile settings.

How it works

  • Port assignment is by worktree creation time — first worktree gets offset +10, next +20, next +30… Existing worktrees keep their ports forever; new worktrees always get the next unused offset, so adding one never collides with running dev servers.
  • {PORT} in the cmd is replaced with the actual assigned port.
  • {LABEL_URL} gives you another service's URL (e.g. {API_URL}).

tmux model — why windows, not sessions

tmux always nests four layers: server → session → window → pane. You can't skip one — a pane lives in a window, a window in a session, a session in a server. This skill maps worktrees onto that hierarchy like so:

SOCKET "wt"   (-L wt)            ← one tmux server, isolated from your default tmux
└── SESSION "wt"                 ← one session = the whole dashboard
    ├── WINDOW "feature-xyz"     ← one window per WORKTREE
    │   ├── pane CLAUDE  (left, large)
    │   ├── pane API
    │   └── pane WEB             ← one pane per SERVICE
    ├── WINDOW "bugfix-abc"      ← next worktree
    └── WINDOW "main"
tmux layermaps tocount
socket (-L wt)this skill's whole tmux server1
session (wt)the dashboard1
windowone worktreeN worktrees
paneone service in that worktreeone per services: entry (+ CLAUDE)

So worktrees are separated by windows, not by sessions or sockets.

Why one session with many windows (not a session per worktree)

The goal is glance across every worktree from a single attached client. Windows deliver that; separate sessions don't:

  • One attach sees everything. tmux -L wt attach -t wt drops you into all worktrees at once — flip between them with Shift + ←/→. Session-per-worktree would need a separate attach (or a session-picker hop) for each.
  • One status bar lists them all. Window tabs across the top are the worktree selector. A session only shows its own windows in the bar.
  • Adding a worktree is just new-window. The WorktreeCreate hook appends a window to the live session — no re-attach. new-session would spawn a detached session you'd have to find and attach separately.
  • Same nesting depth either way. Session-per-worktree isn't "less nested" — it's N sessions each holding one window, vs. 1 session holding N windows. Same number of layers; the single-session layout just keeps worktrees as siblings under one roof so the combined view works.

Session-per-worktree would win if you wanted each worktree fully isolated (detach one without seeing the others), or multiple people attaching to different worktrees independently. That's not this use case — here it's one dev, one screen, many worktrees, flip fast.

Why a dedicated socket (-L wt)

Separate concern from worktree layout. The -L wt socket runs this dashboard as its own tmux server, distinct from your normal default tmux. So:

  • A stray tmux kill-server (or tmux -L wt kill-server to rebuild) only hits this dashboard — never your unrelated tmux work.
  • No session/window name clashes with whatever else you run.
  • tmux -L wt ls shows only this skill's sessions; plain tmux ls shows your default server — two servers, blind to each other.

Every command targeting the dashboard repeats -L wt; without it you're talking to the default server, which won't have a wt session. Handy alias:

alias wt='tmux -L wt'   # then: wt attach -t wt   ·   wt ls   ·   wt kill-server

Common pitfalls

Worktrees run on offset ports (worktree #1 → +10, #2 → +20, …), but every env file in the worktree is symlinked from main, where the values were written for the original port (3000, 8787, etc). When an app reads its own URL from env, you get a mismatch — the dev server listens on :3010 but thinks it's still :3000. Symptoms range from broken auth callbacks to silently-wrong API targets.

Rule of thumb: any env var that encodes a port or base URL must be re-derived per worktree, not symlinked. Set them in cmd: using the {LABEL_URL} / {LABEL_PORT} placeholders so each worktree gets its own values.

The usual suspects:

App / libraryVariableFailure mode
Better AuthAPP_URL, AUTH_TRUSTED_ORIGINSInvalid origin: http://localhost:3010 on every sign-in
NextAuthNEXTAUTH_URLOAuth callback returns to main's port, session fails to set
Next.js public URLsNEXT_PUBLIC_APP_URL, NEXT_PUBLIC_API_URLClient-side fetches go to main's port instead of the worktree's
OAuth providers (Google/GitHub)redirect URI registered in provider dashboardredirect_uri_mismatch — provider only knows about main's port. Add localhost:3010/3020/3030 to allowed callbacks
CORS allowlistsserver-side allowed originsRequest from localhost:3010 rejected by the server it's calling
Cross-service URLsMCP_HUB_URL, API_URL, etc.Worktree's web app calls main's API/MCP instead of its own worktree copy

Use {LABEL_URL} placeholders to fix them at the worktree boundary. Example for Better Auth + cross-service URLs:

- label: WEB
  cwd: apps/web
  port: 3000
  cmd: |
    APP_URL={WEB_URL} NEXT_PUBLIC_APP_URL={WEB_URL}
    AUTH_TRUSTED_ORIGINS={WEB_URL}
    MCP_HUB_URL={MCP_URL} NEXT_PUBLIC_MCP_HUB_URL={MCP_URL}
    AGENT_HUB_URL={AGENT_URL}
    PORT={PORT} npm run dev

Now the worktree on port 3010 launches as a self-consistent http://localhost:3010 — auth, fetch, and CORS all agree.

Tip: if you see "Invalid origin", "redirect_uri_mismatch", or "Cross-Origin Request Blocked" anywhere on a fresh worktree, the answer is almost always a missing {LABEL_URL} in your cmd: line.

Requires

  • tmux
  • yq (brew install yq — auto-installed if missing)
Ver o original no GitHub

Bom para

Relacionados