home / skills / dtinth / agent-skills / tmux

tmux skill

safe

This skill helps you manage long-running commands using tmux sessions and windows, enabling background execution and easy status checks.

npx playbooks add skill dtinth/agent-skills --skill tmux

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: tmux
description: Use this skill to run background processes or long running processes using tmux.
---

`tmux` lets you run commands in the background and check on them later. When you run a normal bash command, you have to wait for it to finish. With tmux, you can start a command, let it run in the background, and check its output whenever you want.

Key Terms:

- Session: A container that holds your tabs. Like a browser window.
- Tab: A place where one command runs. Like a browser tab. We call this a "window" in tmux.

# Step 1: Create or Use a Session

Always do this first:

```bash
# Create a new session
tmux new-session -d -s mysession
```

- Use the project name (e.g. working directory basename) as the session name.
- If it fails with "duplicate session", it means the session already exists. It may be created by a prior session. You can use it, but check its state before continuing.

```bash
# See what sessions exist
tmux ls

# Delete a session when done
tmux kill-session -t mysession
```

# Step 2: Create Tabs (Windows)

```bash
# Create a tab called "mytab" in session "mysession"
tmux new-window -t mysession -n mytab
```

- Always give your tab a name. Don't use numbers.
- Always specify the session name in the command line as there may be multiple tmux sessions active.

```bash
# See what tabs exist
tmux list-windows -t mysession

# Delete a tab
tmux kill-window -t mysession:mytab
```

# Step 3: Run a Command in a Tab

```bash
# Run "npm start" in the "server" tab
tmux send-keys -t mysession:server 'npm start' Enter
```

- Always end with `Enter` to actually run the command.

```bash
# Stop a running command: Send Ctrl+C
tmux send-keys -t mysession:server C-c
```

Common stop signals:
- `C-c` = Ctrl+C (interrupt)
- `C-d` = Ctrl+D (end input)

# Step 4: Check What Happened

```bash
# See what's on screen now
tmux capture-pane -t mysession:server -p
```

If you don't see the output you want yet, sleep and run again. If you don't know how long it will take, start at 15 seconds, doubling the sleep duration each time, but never sleep more than 4 minutes (240 seconds).

Overview

This skill helps you run and manage background or long-running processes using tmux. It provides practical commands and conventions to create sessions, named tabs (windows), run commands, inspect output, and clean up when finished. Use it to keep processes alive on remote hosts, restart services, or monitor logs without keeping an SSH session open.

How this skill works

The skill guides you to create a persistent tmux session that holds named windows (tabs) where individual commands run. You send commands into a window, leave them running, and later capture the pane contents to inspect output or send control keys like Ctrl+C. It emphasizes naming sessions and windows and includes inspection and cleanup commands.

When to use it

Run servers, background jobs, or watchers that must survive a disconnected SSH session.
Monitor logs or long builds while you detach and reattach later.
Run interactive or long-running tooling on remote machines without screen persistence.
Isolate multiple processes in separate named windows for easier management.
Automate periodic checks by capturing pane output on demand.

Best practices

Name sessions after your project (use the directory basename) so multiple sessions are easy to identify.
Always name windows instead of relying on numbers for clarity.
Specify the session name (-t) in commands to avoid affecting the wrong session.
Use tmux capture-pane to retrieve output; repeat with exponential backoff if the process is still producing output.
Clean up with tmux kill-window or tmux kill-session when work is complete to avoid stale sessions.

Example use cases

Start a web server in a named window, detach, and reconnect later to review logs and restart.
Run a long test suite in its own session so you can keep other terminal work separate.
Tail multiple log files in different windows to compare behavior across services.
Launch a build or deploy script and periodically capture the pane to check progress without staying attached.
Keep debugging shells for different microservices running concurrently in named windows.

FAQ

What if tmux reports a duplicate session?

A duplicate session error means a session with that name already exists. List sessions with tmux ls, inspect its windows, and either reuse it or kill it with tmux kill-session -t <name> if it is stale.

How do I stop a running command inside a tmux window?

Send an interrupt or end signal using tmux send-keys -t <session>:<window> C-c (Ctrl+C) or C-d (Ctrl+D) depending on the process; include Enter when sending ordinary commands.