mcpField
T
tmux-background-tasks

tmux-background-tasks

github.com/justbecauselabsDevelopment1108 installsUpdated 10w ago
Repository

About tmux-background-tasks

tmux-background-tasks is a skill for running and managing long-lived commands in tmux sessions. It covers checking availability, reusing sessions, and attaching to or stopping background tasks.

Key features

  1. 01Checks whether tmux is installed
  2. 02Starts commands in detached sessions
  3. 03Reuses existing sessions
  4. 04Provides attach and log-viewing commands
  5. 05Stops sessions on request

Use cases

  1. 01Keeping a development server running
  2. 02Running a watcher while using other commands
  3. 03Reattaching to a background worker

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/justbecauselabs/agent-skills --skill tmux-background-tasks

After installing, type/tmux-background-tasksin Claude Code to confirm it loaded.

Details

From the project README

Tmux Background Tasks

If tmux is not installed, stop and ask the user to install it before proceeding.

Overview

Use tmux to run and manage long-lived commands in the background. Do not keep these tasks alive with the default process tool; always launch them in tmux so they survive across commands and can be reattached.

Workflow

  1. Verify tmux is installed If tmux is missing, stop and ask the user to install it (e.g., brew install tmux on macOS). Do not proceed until tmux is available.

  2. Pick a stable session name Use a predictable, unique name like <repo>-<task> (e.g., myapp-api, myapp-expo).

  3. Start or reuse the session Check for an existing session before starting a new one.

  4. Provide attach/detach guidance Tell the user how to attach to the session if they want to view logs or interact.

  5. Stop or restart when requested Terminate the session cleanly when the user asks to stop the task.

Command Patterns

Check tmux:

  • command -v tmux
  • tmux -V

Create a new detached session running a command:

  • tmux new-session -d -s <name> -- <command>
  • If you need a login shell or env: tmux new-session -d -s <name> -- bash -lc '<command>'

Reuse or attach:

  • tmux has-session -t <name>
  • tmux attach -t <name>
  • tmux ls

Send a stop signal or kill:

  • tmux send-keys -t <name> C-c
  • tmux kill-session -t <name>

Peek at recent output (non-interactive):

  • tmux capture-pane -pt <name> -S -200

Notes

  • Prefer tmux for servers, watchers, workers, and dev tools that should remain running while other commands execute.
  • Avoid creating duplicate sessions. If tmux has-session -t <name> succeeds, reuse it or attach.

Comments

Markdown supported