tmux-cowork

Run long-running or interactive commands in a shared tmux session with completion detection.

1|1|Updated Nov 25, 2024
One-click install
npx skills add https://github.com/joeledwardson/dev-setup --skill tmux-cowork-joeledwardson
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tmux-cowork
Source: https://github.com/joeledwardson/dev-setup/tree/main/configs/claude/skills/tmux-cowork
Command: npx skills add https://github.com/joeledwardson/dev-setup --skill tmux-cowork-joeledwardson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Long-running commands like builds, dev servers, and migrations block the AI's Bash tool or finish without the user being able to watch, scroll back, or interrupt them. This Skill pushes such commands into a tmux session the user can attach to, while the AI polls for actual completion instead of assuming success. ## Core Features & Use Cases - Shared tmux sessions: Creates named sessions and cowork-<task> windows so the user can attach with tmux attach -t <session_name> and watch or Ctrl+C anything. - Reliable completion detection: Uses sentinel markers with exit codes (__CC_DONE_<code>__) and tee'd log files in scratchpads/ instead of blind sleeps, with backoff polling cadence. - Multi-command layouts: Supports pane splits, window reuse, and descriptive pane titles for parallel builds, tests, and dev servers. - Use Case: You ask the AI to run nixos-rebuild or npm run dev; it opens a cowork window in tmux, streams output to a log, polls until the sentinel fires, and reports the real exit code and log tail. ## Quick Start Ask the AI to run your dev server or long build in a tmux pane you can watch, then attach with the session name it reports.

Frequently Asked Questions about tmux-cowork

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a long-running command in tmux from an AI assistant?

Create a named tmux session and cowork window, then send the command with tmux send-keys. Append a sentinel marker like __CC_DONE_$?__ and tee output to a log file so completion and exit code can be detected by polling.

How to detect when a tmux command finishes?

Append a sentinel echo with the exit code after the command, teeing output to a log file, then poll capture-pane until the marker appears. Reading the log file is more reliable than capture-pane, which is lossy with scrollback and ANSI noise.

When should I use tmux versus the Bash tool for commands?

Use tmux for anything over 30 seconds, interactive prompts, dev servers, watch modes, or commands the user may need to Ctrl+C. Use the regular Bash tool for quick one-shot commands like git status, ls, or grep where tmux overhead is not worth it.

What if tmux is not installed on the system?

Fall back to the regular Bash tool with run_in_background set to true and inform the user. The tmux-based workflow only applies when the tmux binary is available on the machine.

How do I run multiple parallel commands in one tmux session?

Spawn separate cowork windows for unrelated tasks, or split one window with tmux split-window -h for two commands and -v with a main-horizontal layout for three or more. Set a pane title with select-pane -T so each pane is identifiable.