skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
steveclarke/dotfiles61 installs

tmux-worktree-session

Spin up an isolated git worktree in its own tmux session — coding agent in one window, a shell in another, dev stack in a third — with the agent briefed and already working. Use for spinning up a worktree, starting a feature/branch/task in isolation, handing work to a fresh agent (Claude/Codex), or setting up an isolated tmux dev session.

How do I install this agent skill?

npx skills add https://github.com/steveclarke/dotfiles --skill tmux-worktree-session
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill automates the setup of development environments using tmux and git worktrees by identifying and running project-local scripts. While intended for productivity, it presents a surface for indirect prompt injection and unintended command execution if the repository being worked on is untrusted or contains malicious configuration files.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

tmux Worktree Session

Stand up a self-contained workspace: an isolated git worktree, a tmux session to drive it, the dev stack running, and a fresh agent already working a briefing. The human attaches and the work is already in motion.

Composes two skills: tmux-orchestration for safely driving panes, and handoff for writing the briefing.

Standard layout

Session: <Project>-<work>     (hyphenated, no spaces)
├── Window 1 "agent" → coding agent (Claude/Codex), cwd = worktree, given a
│                      kickoff prompt pointing at the briefing
├── Window 2 "cli"   → bare shell for tests and ad-hoc commands
└── Window 3 "dev"   → dev stack

Three windows, one thing each — no splits. The common shape; adapt it (no dev stack, two agents, a logs window). Confirm if non-obvious. Don't add a git/lazygit window unless the user asks for one.

Inputs

Fill from context, don't interrogate:

  • Work name → branch + session name. Prefer a PR/issue number if one exists.
  • Agent + mode → Claude or Codex, fast/plan. Ask once if unsure.
  • Base branch → usually the default; worktree tools often base on origin/<default>, which matters for step 1.

Process

1. Write the briefing, commit it to the base branch first

Use handoff to write what the agent reads: mission, scoped task, files/patterns, conventions, guardrails. A briefing, not a history.

If the worktree tool bases new trees on origin/<default>, commit and push the briefing to the base branch before creating the worktree — otherwise it won't be there for the agent.

2. Discover and run the worktree tool

Look (see cheatsheet), don't assume. Common: bin/worktree create <name>, bin/worktree create --pr 42. Fallback: git worktree add ../<repo>-<branch> -b <branch> origin/<default>.

Creation often triggers a full bootstrap (deps, DB, secrets) that takes minutes — don't assume it hung. It may prompt for a secret (1Password, master key, env token): that's the user's to approve — surface it and wait, never type credentials yourself. Run it in a visible pane and wait for a real completion signal (append ; echo DONE_$? and poll) before starting the dev stack.

3. Discover dev-stack and test commands

Look (see cheatsheet). Prefer a headless/detached mode for your control (e.g. process-compose -D + status/logs); a foreground TUI is fine for the human to watch. Note the test runner — the cli window and agent need it.

4. Build the session

Mechanics via tmux-orchestration. Specifics that bite:

  • Create it detached so the user's current session is untouched.
  • Hyphenated name, no spaces.
  • Window 1 agent: cd to worktree, launch agent; when its UI is ready, buffer-paste the kickoff, then Enter as a separate step. Keep it short — point at the briefing. Optionally hand it the sibling pane ids (cli, dev) so it can poll them itself via the tmux CLI.
  • Window 2 cli: cd to worktree, bare shell for tests and ad-hoc commands.
  • Window 3 dev: cd to worktree, run the dev stack.

Every window cds into the worktree and needs the right toolchain (see version-manager gotcha).

5. Verify and report

  • Dev stack actually healthy (poll status/health), not just "started"; read process logs if anything failed.
  • Agent actually started (capture its pane, don't assume the paste landed).
  • Report: tmux attach -t <session>.

Gotchas

Version managers don't activate in spawned shells (the big one). A shell you spawn programmatically (tmux new-session, non-login) often lacks the user's version manager (mise/asdf/rbenv/nvm), so ruby/node/python silently falls back to the system version and bootstrap fails (e.g. "Could not find bundler").

  • Detect: compare ruby -v etc. in your pane vs the user's. Mismatch = the smell.
  • Fix interactive panes: put shims on PATH, e.g. mise export PATH="$HOME/.local/share/mise/shims:$PATH".
  • Fix the dev stack's child processes too: each command that needs a mise-managed tool runs eval "$(mise activate bash)" && … (or mise exec --).

Pane mechanics + safety → tmux-orchestration. Pane-id targeting, never writing to your own pane, read-before-write, buffer-pasting multi-line prompts, Enter as a separate step — all of that lives there. Don't restate it; follow it. Two things worth repeating here: no spaces in session names (session:window targets mis-parse), and quit a dev TUI with its real key (process-compose F10), not a guessed Ctrl-C.

Discovery cheatsheet

NeedLook for
Worktree toolbin/worktree, script/worktree, DEVSTACK.md, just/make, else git worktree add
Dev stackbin/dev, npm/pnpm dev, foreman/overmind, process-compose, docker compose, mise run dev, project verbs
Test runnerbin/rspec, pnpm test, pytest, go test, Makefile
Toolchain.mise.toml/.tool-versions/.ruby-version/.nvmrc — confirm the spawned shell uses it

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/steveclarke/dotfiles/tmux-worktree-session">View tmux-worktree-session on skillZs</a>