Monitor and interact with Claude Code tmux sessions

Install

/plugin install session-tools@claude-session-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add shsym/claude-session-tools.

Contents

Discovered from source

Skills 5

Approve Action

Detect permission prompts and approve or deny them.

Arguments

$ARGUMENTS: <session-name> [approve|deny]

Instructions

  1. Parse arguments:

    • Session name (required)
    • Action: approve, deny, or none (interactive)
  2. Capture session output:

    "$PLUGIN_DIR/bin/capture-session" "<session_name>" 30
    
  3. Look for permission prompts:

    • Bash command: followed by command
    • Allow ... to ...
    • Grant access
    • Use skill "..."
    • Permission dialog boxes
  4. If no permission prompt found:

    No pending permission request in session '<session_name>'.
    
  5. If permission prompt found, show details:

    ## Permission Request: <session_name>
    
    **Type:** <Bash/Edit/Skill/etc>
    **Details:** <what is being requested>
    
    Options:
    - approve: Allow this action
    - deny: Reject this action
    
  6. If action specified (approve/deny):

    Send the appropriate response:

    # For approve:
    tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
    
    # For deny:
    tmux send-keys -t "<session>" "n" && tmux send-keys -t "<session>" Enter
    

    Report:

    Sent '<action>' to session '<session_name>'.
    

Example

Interactive:

/session-tools:approve-action ai-worker-001

## Permission Request: ai-worker-001

**Type:** Bash
**Details:** npm install express

Options:
- /session-tools:approve-action ai-worker-001 approve
- /session-tools:approve-action ai-worker-001 deny

Direct:

/session-tools:approve-action ai-worker-001 approve

Sent 'approve' to session 'ai-worker-001'.

List Claude Code Sessions

List all running ai-* prefixed tmux sessions and show their current status.

Instructions

  1. Get all ai- sessions:*

    tmux list-sessions -F "#{session_name}" 2>/dev/null | grep -E '^ai-' || echo ""
    
  2. For each session, capture recent output:

    "$PLUGIN_DIR/bin/capture-session" "<session_name>" 15
    
  3. Analyze each session's output to determine status:

    • working - Has ✢, ⏺, or Thinking…
    • idle - At ❯ prompt with no activity
    • permission-prompt - Waiting for permission approval
    • waiting-input - Waiting for user input (y/n, choice, text)
    • stuck - In editor, pager, or hanging
  4. Output a table:

    Session                Status              Details
    ───────────────────────────────────────────────────
    ai-worker-001          working             Editing src/api.ts
    ai-worker-002          permission-prompt   Bash: npm install
    ai-brainstorm-design   idle                At prompt
    
  5. If no sessions found:

    No ai-* sessions found.
    
    To create one: /session-tools:spawn-session worker
    

Spawn Session

Create a new Claude Code tmux session with ai-* prefix to act as a subagent worker.

Arguments

$ARGUMENTS format: [type] [name-suffix] [-- initial prompt]

  • type - Session type: worker (default), brainstorm, auditor
  • name-suffix - Optional custom suffix (auto-generated if omitted)
  • -- initial prompt - Optional prompt to send after session starts

Examples:

  • /session-tools:spawn-session → ai-worker-001
  • /session-tools:spawn-session worker api → ai-worker-api
  • /session-tools:spawn-session brainstorm design → ai-brainstorm-design
  • /session-tools:spawn-session worker task1 -- Implement the login feature → spawns and sends prompt

Instructions

  1. Parse arguments:

    type = "worker" (default)
    suffix = auto-generated or provided
    prompt = text after "--" if present
    
  2. Generate session name:

    If no suffix provided, find next available number:

    "$PLUGIN_DIR/bin/next-session-name" "<type>"
    

    Returns: ai-<type>-<number> (e.g., ai-worker-003)

    If suffix provided: ai-<type>-<suffix>

  3. Validate session doesn't exist:

    tmux has-session -t "<session_name>" 2>/dev/null && echo "exists"
    

    If exists, error:

    Session '<session_name>' already exists. Choose a different name.
    
  4. Get working directory:

    Use current working directory for the new session:

    pwd
    
  5. Spawn the session:

    "$PLUGIN_DIR/bin/spawn-session" "<session_name>" "<working_dir>" ["<initial_prompt>"]
    

    The script:

    • Creates tmux session in detached mode
    • Starts claude in the session
    • Optionally sends initial prompt
  6. Verify session started:

    sleep 2
    "$PLUGIN_DIR/bin/detect-state" "<session_name>"
    
  7. Output result:

    Spawned session: <session_name>
    Working directory: <working_dir>
    Status: <state>
    
    To monitor: /session-tools:summarize-session <session_name>
    To attach:  tmux attach -t <session_name>
    

Session Types

TypePrefixPurpose
workerai-worker-*Task execution
brainstormai-brainstorm-*Ideation and exploration
auditorai-auditor-*Code review and verification

Example Usage

Spawn default worker:

/session-tools:spawn-session

Spawned session: ai-worker-001
Working directory: /Users/you/project
Status: idle - At prompt

To monitor: /session-tools:summarize-session ai-worker-001
To attach:  tmux attach -t ai-worker-001

Spawn with task:

/session-tools:spawn-session worker api -- Implement the REST API endpoints for user authentication

Spawned session: ai-worker-api
Working directory: /Users/you/project
Status: working - Processing prompt

To monitor: /session-tools:summarize-session ai-worker-api
To attach:  tmux attach -t ai-worker-api

Spawn brainstorm session:

/session-tools:spawn-session brainstorm arch -- What are the best approaches for implementing caching in this codebase?

Spawned session: ai-brainstorm-arch
Working directory: /Users/you/project
Status: working - Analyzing

Workflow: Using as Subagents

  1. Spawn workers for parallel tasks:

    /session-tools:spawn-session worker auth -- Implement authentication
    /session-tools:spawn-session worker api -- Implement API routes
    /session-tools:spawn-session worker tests -- Write integration tests
    
  2. Monitor progress:

    /session-tools:list-sessions
    
  3. Check specific worker:

    /session-tools:summarize-session ai-worker-auth
    
  4. Handle blockers:

    /session-tools:approve-action ai-worker-auth approve
    /session-tools:unstick-session ai-worker-api auto
    

Summarize Session

Capture and analyze a session's recent activity.

Arguments

$ARGUMENTS: <session-name>

Instructions

  1. Validate session exists:

    tmux has-session -t "<session_name>" 2>/dev/null || echo "NOT_FOUND"
    
  2. Capture extended output (500 lines):

    "$PLUGIN_DIR/bin/capture-session" "<session_name>" 500
    
  3. Analyze the output to identify:

    • Current state: working, idle, stuck, waiting for input
    • Recent tool calls: Look for ⏺ markers (Read, Edit, Bash, etc.)
    • Files being worked on: Paths mentioned in tool calls
    • Current task: What is Claude working on?
    • Errors/warnings: Any error messages or failures
    • Progress: What has been accomplished?
  4. Output structured summary:

    # Session Summary: <session_name>
    
    ## Current State
    <working/idle/stuck/waiting>
    
    ## Current Task
    <description of what Claude is doing>
    
    ## Recent Activity
    - <tool call 1>
    - <tool call 2>
    - ...
    
    ## Files Touched
    - <file 1>
    - <file 2>
    
    ## Errors/Issues
    <any errors or None>
    
    ## Progress
    <summary of what's been done>
    

Example

/session-tools:summarize-session ai-worker-001

# Session Summary: ai-worker-001

## Current State
working

## Current Task
Implementing user authentication API endpoints

## Recent Activity
- Read src/api/routes.ts
- Edit src/api/auth.ts (added login endpoint)
- Bash: npm test
- Read test output

## Files Touched
- src/api/routes.ts
- src/api/auth.ts
- src/api/middleware/auth.ts

## Errors/Issues
None

## Progress
- Created login endpoint
- Added JWT token generation
- Currently writing tests

Unstick Session

Detect what's blocking a session and suggest or apply a resolution.

Arguments

$ARGUMENTS format: <session-name> [auto]

Instructions

  1. Parse arguments:

    • Extract session name (required)
    • Check for auto flag
  2. Capture session output:

    "$PLUGIN_DIR/bin/capture-session" "<session_name>" 40
    
  3. Analyze the output and determine:

    • Is it actively working? (Look for ✢, ⏺, Thinking…)
    • Is it stuck? What type?

    Stuck types:

    TypeSignsFix
    yes_no(y/n), [Y/n], Continue?Send y or n
    multi_choice❯ 1., numbered optionsSend number
    text_inputEnter:, Type:, waiting for inputSend text or Escape
    permissionBash command, Allow, permission dialogSend y or n
    interactive_editor: alone (vim), (END), --More--:q! or q
    hanging_commandNo output, no promptCtrl-C
    worker_idle❯ prompt, no taskNeeds new task
  4. Report findings:

    ## Session: <name>
    
    **Status:** <working/stuck>
    **Stuck Type:** <type or N/A>
    **Details:** <what you see>
    
    **Suggested Fix:** <what to do>
    
  5. If auto mode and stuck:

    Execute the fix using tmux send-keys:

    # For yes_no:
    tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
    
    # For multi_choice:
    tmux send-keys -t "<session>" "1" && tmux send-keys -t "<session>" Enter
    
    # For text_input (cancel):
    tmux send-keys -t "<session>" Escape
    
    # For permission:
    tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
    
    # For interactive_editor (vim):
    tmux send-keys -t "<session>" Escape && tmux send-keys -l -t "<session>" ":q!" && tmux send-keys -t "<session>" Enter
    
    # For interactive_editor (pager):
    tmux send-keys -t "<session>" "q"
    
    # For hanging_command:
    tmux send-keys -t "<session>" C-c
    

    Then re-capture and verify the fix worked.

Example

/session-tools:unstick-session ai-worker-001

## Session: ai-worker-001

**Status:** stuck
**Stuck Type:** permission
**Details:** Waiting for approval: "Bash command: npm install"

**Suggested Fix:** Send 'y' Enter to approve, or 'n' Enter to deny

Sponsors

Details

Marketplace
shsym/claude-session-tools
Category
Community