
session-tools
Monitor and interact with Claude Code tmux sessions
Install
/plugin install session-tools@claude-session-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add shsym/claude-session-tools.
Contents
Discovered from sourceSkills 5
Approve Action
Detect permission prompts and approve or deny them.
Arguments
$ARGUMENTS: <session-name> [approve|deny]
Instructions
-
Parse arguments:
- Session name (required)
- Action:
approve,deny, or none (interactive)
-
Capture session output:
"$PLUGIN_DIR/bin/capture-session" "<session_name>" 30 -
Look for permission prompts:
Bash command:followed by commandAllow...to...Grant accessUse skill "..."- Permission dialog boxes
-
If no permission prompt found:
No pending permission request in session '<session_name>'. -
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 -
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>" EnterReport:
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
-
Get all ai- sessions:*
tmux list-sessions -F "#{session_name}" 2>/dev/null | grep -E '^ai-' || echo "" -
For each session, capture recent output:
"$PLUGIN_DIR/bin/capture-session" "<session_name>" 15 -
Analyze each session's output to determine status:
working- Has✢,⏺, orThinking…idle- At❯prompt with no activitypermission-prompt- Waiting for permission approvalwaiting-input- Waiting for user input (y/n, choice, text)stuck- In editor, pager, or hanging
-
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 -
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,auditorname-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
-
Parse arguments:
type = "worker" (default) suffix = auto-generated or provided prompt = text after "--" if present -
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> -
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. -
Get working directory:
Use current working directory for the new session:
pwd -
Spawn the session:
"$PLUGIN_DIR/bin/spawn-session" "<session_name>" "<working_dir>" ["<initial_prompt>"]The script:
- Creates tmux session in detached mode
- Starts
claudein the session - Optionally sends initial prompt
-
Verify session started:
sleep 2 "$PLUGIN_DIR/bin/detect-state" "<session_name>" -
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
| Type | Prefix | Purpose |
|---|---|---|
worker | ai-worker-* | Task execution |
brainstorm | ai-brainstorm-* | Ideation and exploration |
auditor | ai-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
-
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 -
Monitor progress:
/session-tools:list-sessions -
Check specific worker:
/session-tools:summarize-session ai-worker-auth -
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
-
Validate session exists:
tmux has-session -t "<session_name>" 2>/dev/null || echo "NOT_FOUND" -
Capture extended output (500 lines):
"$PLUGIN_DIR/bin/capture-session" "<session_name>" 500 -
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?
-
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
-
Parse arguments:
- Extract session name (required)
- Check for
autoflag
-
Capture session output:
"$PLUGIN_DIR/bin/capture-session" "<session_name>" 40 -
Analyze the output and determine:
- Is it actively working? (Look for
✢,⏺,Thinking…) - Is it stuck? What type?
Stuck types:
Type Signs Fix yes_no(y/n),[Y/n],Continue?Send yornmulti_choice❯ 1., numbered optionsSend number text_inputEnter:,Type:, waiting for inputSend text or Escape permissionBash command,Allow, permission dialogSend yorninteractive_editor:alone (vim),(END),--More--:q!orqhanging_commandNo output, no prompt Ctrl-C worker_idle❯prompt, no taskNeeds new task - Is it actively working? (Look for
-
Report findings:
## Session: <name> **Status:** <working/stuck> **Stuck Type:** <type or N/A> **Details:** <what you see> **Suggested Fix:** <what to do> -
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-cThen 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