Claude Code within tmux

Manage Claude Code instances living inside tmux sessions. Users usually create separate tmux sessions for separate projects. Use this skill when you need to read the latest Claude Code response in a particular tmux session / project, send it a prompt and get the response, or run /compact directly via tmux (no extra scripts required).

Security Scan

The skill's instructions match the stated purpose (interacting with Claude inside tmux) but there are notable mismatches and safety concerns (it expects tmux use but doesn't declare it, and the runtime instructions allow reading arbitrary tmux panes and sending keystrokes without explicit safeguards).

Purpose & Capability

The skill is clearly intended to operate on tmux sessions running Claude Code, but the registry metadata declares no required binaries or config paths. SKILL.md relies entirely on the tmux binary and (optionally) non-default tmux sockets; the skill should have declared tmux as a required binary and noted socket access.

Instruction Scope

The runtime instructions tell the agent to capture pane contents (tmux capture-pane) and send keystrokes (tmux send-keys). That gives the agent the ability to read arbitrary tmux scrollback and inject input into live sessions. There are no built-in safeguards described (e.g., confirmation prompts, limits on which sessions to target, or checks for sensitive content) beyond a manual 'double-check' tip.

Install Mechanism

Instruction-only skill with no install steps or external downloads. This minimizes supply-chain risk because nothing is written to disk by the skill package itself.

Credentials

The skill requests no credentials or env vars, which is proportionate. However, the instructions access tmux sockets and pane buffers (potentially system-level artifacts) without declaring that dependency; this should be documented so users understand the access surface.

Persistence & Privilege

always:false (no forced inclusion). The skill can be invoked autonomously by the agent per platform default; combined with the instruction scope (ability to read/send to tmux), this increases potential blast radius but is not by itself an incoherence or over-privilege in the metadata.

What to consider before installing

This skill will read tmux pane contents and can inject keystrokes into live tmux sessions named 'claude'. Before installing or using it: (1) Ensure tmux is installed and that you trust any tmux sessions this agent can access — the skill can read past messages (which may include secrets) and send prompts. (2) Prefer running Claude sessions in private sockets or dedicated sessions so the agent can't accidentally target other users' or system sessions. (3) Ask the skill author to declare 'tmux' as a required binary and to add explicit confirmation steps before sending input into a session. (4) Avoid sending sensitive data through this skill, and require explicit user approval each time the agent will inject keystrokes into a live session.

Goal

Give Codex a repeatable checklist for interacting with Claude Code when it’s running inside tmux. Everything happens with standard tmux commands—no helper scripts. Follow these steps any time you see instructions like “check Claude in session X” or “run /compact on Claude.”

Conventions

1. Session naming – We refer to tmux sessions by their tmux session name. Session names can be assigned using tmux new-session -s <session_name>. E.g. if we had created a tmux session for project FooBar using tmux new-session -s foobar, then we will refer to this session by the name foobar.
2. Claude pane – Within a session, there should be exactly one pane whose window title or pane title is claude. If the pane isn’t named, rename it first (Ctrl-b : select-pane -T claude).
3. Standard markers – Claude Code prints user prompts with ❯ … and its replies with ⏺ …. We rely on that to spot the latest exchange.

Workflow

1. Locate the Claude pane

tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_title}' | grep "^<session_name>" | grep -i claude

• If nothing matches, say “No pane titled ‘claude’ found inside session <name>.”
• If multiple panes match, pick the one with the lowest window_index/pane_index unless context says otherwise.
• Record the target as <session>:<window>.<pane> for subsequent commands.

2. View the latest exchange

tmux capture-pane -p -J -t <target> -S -200

• Scan from the bottom upward for the last ❯ block (user) followed by ⏺ (Claude). Quote those lines back to the user.
• If no ❯/⏺ pair exists, say “No exchange found yet.”

3. Send a prompt

tmux send-keys -t <target> -l -- "<prompt>"
sleep 0.1
 tmux send-keys -t <target> Enter

• After sending, poll using capture-pane until a new ⏺ block appears (or a sensible timeout, e.g., 3 minutes). Report the reply verbatim.
• If the timeout expires, say “Claude hasn’t replied yet—still waiting.”

4. Run /compact

Same as sending any prompt, but send /compact. Confirm with “Triggered /compact in session <name>.” (Claude will respond in-pane; no need to quote unless asked.)

5. Dump raw buffer (debug)

tmux capture-pane -p -J -t <target> -S -400

Use this when the user wants the entire scrollback or when parsing fails.

Tips

• Always double-check you’re addressing the right pane before sending commands—especially in shared sessions.
• If the Claude pane lives on a non-default tmux socket, prefix every tmux command with tmux -S /path/to/socket ….
• When summarizing results, mention the session/pane you used—for traceability.
• If the user wants multiple sessions handled, repeat the workflow per session.

This skill keeps things simple: pure tmux, no external code. Use it whenever you need hands-on access to Claude Code running inside tmux.