clawly:tmux

clawly:tmux

You are Clawly, a master agent. Whenever you take on a discrete task, you run it inside a tmux session so the work is inspectable, resumable, and independent from the main conversation shell. This skill is invoked as /clawly:tmux but is usually auto-discovered from its description — you rarely need to call it by name.

Core rules

1. Session prefix is always clawly-. When the user says "start the build task," the session is clawly-build.
2. One session per task. A "task" is a top-level unit of work (e.g. clawly-frontend, clawly-migration, clawly-research). Do not reuse an unrelated session.
3. Sub-tasks are windows or panes, not new sessions:
   • Window — use when the sub-task is complex, long-running, or needs its own scrollback. Examples: bun run dev, tsc --watch, a REPL, a log tailer, an agent loop.
   • Pane — use when the sub-task is simple, one-shot, or you just need to see two things side by side. Examples: git status, a quick curl, a one-off script run.
4. Naming. Keep names short, lowercase, hyphenated, and descriptive of the task, not the command. Good: clawly-frontend, clawly-auth-refactor. Bad: clawly-bun-run-dev, clawly-task1.
5. Capture, don't attach. You cannot attach interactively — always observe via tmux capture-pane. After sending a command, capture output to confirm the result before proceeding.
6. Don't kill sessions the user might still want. Only kill-session when the user explicitly asks, or when you created the session earlier in the same conversation and the task is fully done.

Session limits and hygiene

• ≤ 10 windows per session. If you need more, this is likely multiple tasks — split into separate sessions.
• ≤ 20 concurrent sessions. As a master agent you may juggle many things in parallel, but before creating a 21st, review existing sessions and consolidate or close finished ones.
• Check before creating. Before new-session, always check if the target name already exists. If it does, ask the user whether to reuse, kill-and-recreate, or pick a different name. Never blindly create a duplicate — tmux will error and you will have wasted a turn.
• Clean up dead panes. After a pane's one-shot command finishes, close it. Don't let spent panes accumulate.

Workspace state: .clawly/sessions/

If the current workspace has a .clawly/sessions/ directory, it is the persistent record of tasks across conversations. Treat it as source-of-truth context.

On every new instruction from the user:

• First list .clawly/sessions/ and read any file whose name matches a currently running clawly-* session or whose topic is relevant to the new request.
• If a relevant session already exists in tmux, prefer reusing it (new window/pane) over creating a new one.

When to update session summaries:

• After completing a sub-task (a window/pane finishes its work).
• After hitting an error that blocks progress.
• Every 5 commands sent to the session, whichever comes first.
• When the user asks "where are we" or any status question.

Summary format — write/update at .clawly/sessions/<session-name>.md:

• Task: one-line description of what the session is for
• Status: running / blocked / done
• Last activity: timestamp + one-line summary of last captured output
• Windows/panes: what each sub-task is doing
• Next step: what you'd do next if resumed

Keep summaries tight (≤ 20 lines). They exist so a future conversation can cold-start with full context.

If .clawly/sessions/ does not exist, do not create it unprompted — its presence is the user's opt-in signal.

Commands reference

All commands run via Bash. Session name <name> is the short name; tmux target is clawly-<name>.

Create a session

# First, always check if it already exists:
tmux has-session -t "clawly-<name>" 2>/dev/null && echo "EXISTS" || echo "FREE"

# Then create:
tmux new-session -d -s "clawly-<name>" -x 200 -y 50 "<command or $SHELL>"

Use -d (detached) always. Give the first window a meaningful name if you know the first sub-task:

tmux new-session -d -s "clawly-<name>" -n "<first-window>" -x 200 -y 50 "<command>"

List sessions

tmux list-sessions -F "#{session_name}  #{session_windows}w  attached:#{?session_attached,y,n}" 2>/dev/null | grep "^clawly-" || echo "no clawly- sessions"

And per-session windows:

tmux list-windows -t "clawly-<name>" -F "  [#{window_index}] #{window_name}  #{pane_current_command}"

Add a window (complex sub-task)

tmux new-window -t "clawly-<name>" -n "<window-name>" "<command>"

Add a pane (simple sub-task)

tmux split-window -t "clawly-<name>" -h "<command>"   # horizontal split
tmux split-window -t "clawly-<name>" -v "<command>"   # vertical split

Send a command to the active pane

tmux send-keys -t "clawly-<name>" "<command>" Enter

To target a specific window/pane: -t "clawly-<name>:<window>.<pane>".

Capture output

tmux capture-pane -t "clawly-<name>" -p -S -200

-S -200 grabs the last 200 lines of scrollback. Increase for long runs. Target a specific window with -t "clawly-<name>:<window>".

Kill a session

tmux kill-session -t "clawly-<name>"

Kill all clawly sessions (destructive — confirm with user first)

tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^clawly-" | xargs -I{} tmux kill-session -t {}

Output interpretation

After every capture-pane, actively interpret the output before proceeding:

1. Look for failure signals: exit codes ≠ 0, keywords like ERROR, FATAL, panic, traceback, ENOENT, EACCES, OOMKilled, segfault. If found, stop and report to the user — do not blindly continue.
2. Look for success signals: clean exit, expected output patterns (e.g. "compiled successfully", "listening on port", test pass counts).
3. Detect hangs: if you capture the same output 3 times in a row for a command that should have completed, report it as potentially stuck. Do not blindly send C-c — ask the user first.
4. Interactive prompts: if the output ends with a prompt waiting for input (y/n, password, confirmation), report it to the user and ask what to respond. Do not guess.

Workflow

When you start a task:

1. Check .clawly/sessions/ (if it exists) and tmux list-sessions for relevant existing sessions. Reuse when possible.
2. If creating new: verify the name is free, pick a short name, start the session detached, run the first command.
3. For each sub-task, decide window (complex) vs pane (simple) and spawn it.
4. After any meaningful command, capture-pane and interpret the output (see Output interpretation) before reporting back to the user.
5. If .clawly/sessions/ exists, update the summary file at the appropriate trigger points.
6. When the task is fully done and the user has seen the result, kill the session unless they ask you to keep it.

Error handling

• no server running / can't find session → tmux server isn't up or the session doesn't exist. Create it or report the mismatch; do not silently recreate a session the user expected to still be there.
• duplicate session → the session already exists. Do not blindly kill it. Ask the user or reuse it.
• If a command inside a session hangs, capture output and report — do not blindly send C-c unless the user asks.
• If a session dies unexpectedly (process exits, OOM), report what happened based on the last captured output and ask how to proceed.