tmux_skill

This skill helps you manage long-lived dev processes in tmux by using session-scoped windows and shell initialization.

TypeScript

36

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill 0xbigboss/claude-code --skill tmux

SKILL.md6.3 KB

Overview

This skill provides patterns and safe defaults for running long-lived processes inside tmux sessions tied to a project. It focuses on idempotent session creation, window management, and reliable shell initialization so dev servers, watchers, and background tools survive the conversation. The guidance prevents accidental destruction of unrelated sessions and ensures environment initialization (PATH, direnv) runs correctly.

How this skill works

The skill derives a session name from the git project root (falling back to the current directory) and enforces a one-project-one-session rule. It always checks for an existing session with tmux has-session and uses send-keys to run commands inside the spawned interactive shell. Windows represent separate processes inside the same session; monitoring and lifecycle operations target the project session only.

When to use it

Starting long-lived dev servers (npm run dev, rails s, tilt up)
Running file or test watchers that should persist beyond the terminal
Launching background database or logging processes for a project
When processes are expected to outlive the chat session
Not for one-shot builds or commands that complete in <10s or need stdout inline

Best practices

Always check tmux has-session before creating a new session to avoid duplicates
Derive session name from git rev-parse --show-toplevel or fallback to $PWD
Use tmux send-keys to run commands so shell init (PATH, direnv) executes
Add windows to the existing project session instead of creating parallel sessions
Never run tmux kill-server and never kill sessions that don’t match the project

Example use cases

Start a project session and run a dev server in a 'server' window, idempotently
Add a 'tests' window for test watchers without duplicating the session
Tail logs in a 'logs' window and capture recent output for quick checks
Restart a process by sending Ctrl+C then re-sending the start command via send-keys
Poll a window’s pane output for ready indicators like 'listening' or 'ready'

FAQ

send-keys runs commands in the interactive shell created by tmux so shell initialization (PATH, direnv, shell rc) runs; inline commands to new-session often bypass that initialization and break environment-dependent tools.

How should I name sessions and windows?

Derive the session name from the git project root (basename of git rev-parse --show-toplevel) and use descriptive window names like server, tests, logs for separate processes.