# Tmux

> Manage long-running shell sessions with tmux — start a detached session, run a long task, reattach later, capture output. Use when a task takes longer than a single tool call (build, test, log tail).

- Skill: `team-commonly/tmux` (Agent Skill)
- Install (CLI): `npx skillmds@latest add team-commonly/tmux`
- Raw SKILL.md: https://api.skillmd.com/api/skills/team-commonly/tmux/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: team-commonly (https://skillmd.com/u/team-commonly)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/team-commonly/tmux

---


# tmux — long-running session management

`tmux` is on PATH in the gateway. Sessions persist across tool-call
boundaries within the same agent's lifetime, so you can fire off a long task
and come back to it on the next heartbeat.

## Start a detached session

```bash
# Run a long command in a fresh detached session named "build"
tmux new-session -d -s build "npm run build > /tmp/build.log 2>&1"
```

## Check on a session

```bash
# List sessions
tmux list-sessions

# Capture the current pane's visible output
tmux capture-pane -t build -p | tail -40

# Capture the full scrollback (last 1000 lines)
tmux capture-pane -t build -p -S -1000
```

## Send input to a session

```bash
# Send a command (note: end with C-m for Enter)
tmux send-keys -t build "echo done > /tmp/done.flag" C-m
```

## End a session

```bash
tmux kill-session -t build
```

## Common patterns

### Long-running build with status flag

```bash
tmux new-session -d -s build "
  npm run build > /tmp/build.log 2>&1
  echo \$? > /tmp/build.exit
"

# Later (next heartbeat):
if [ -f /tmp/build.exit ]; then
  EXIT=\$(cat /tmp/build.exit)
  echo "Build finished with exit code \$EXIT"
  tail -20 /tmp/build.log
else
  echo "Build still running..."
fi
```

### Tail a log without blocking

```bash
tmux new-session -d -s logs "kubectl logs -f -n commonly-dev deploy/backend > /tmp/backend.log"
# Read on demand:
tail -50 /tmp/backend.log
```

## When NOT to use tmux

- For one-shot commands → run them directly with `acpx_run` or shell.
- For tasks that need to outlive the agent's gateway pod → use a different
  mechanism (cron, scheduled job, etc.).
- For interactive workflows → tmux works but can't take human input from
  inside an agent.