AGENT SKILL

tmux-monitor

Monitor and report status of all tmux sessions including dev environments, spawned agents, and running processes. Uses tmuxwatch for enhanced visibility.

License 许可
MIT
最近更新
2026-11-12
Stars
★ 1
Forks
1

01 前言 Front Matter

name
tmux-monitor
version
1.0.0
description
Monitor and report status of all tmux sessions including dev environments, spawned agents, and running processes. Uses tmuxwatch for enhanced visibility.

02 资源文件 1

03 SKILL.md 正文

tmux-monitor Skill

Purpose

Provide comprehensive visibility into all active tmux sessions, running processes, and spawned agents. This skill enables checking what's running where without needing to manually inspect each session.

Capabilities

  1. Session Discovery: Find and categorize all tmux sessions
  2. Process Inspection: Identify running servers, dev environments, agents
  3. Port Mapping: Show which ports are in use and by what
  4. Status Reporting: Generate detailed reports with recommendations
  5. tmuxwatch Integration: Use tmuxwatch for enhanced real-time monitoring
  6. Metadata Extraction: Read session metadata from .tmux-dev-session.json and agent JSON files

When to Use

  • User asks "what's running?"
  • Before starting new dev environments (check port conflicts)
  • After spawning agents (verify they started correctly)
  • When debugging server/process issues
  • Before session cleanup
  • When context switching between projects

Implementation

Step 1: Check tmux Availability

if ! command -v tmux &> /dev/null; then
    echo "❌ tmux is not installed"
    exit 1
fi

if ! tmux list-sessions 2>/dev/null; then
    echo "✅ No tmux sessions currently running"
    exit 0
fi

Step 2: Discover All Sessions

# Get all sessions with metadata
SESSIONS=$(tmux list-sessions -F '#{session_name}|#{session_windows}|#{session_created}|#{session_attached}')

# Count sessions
TOTAL_SESSIONS=$(echo "$SESSIONS" | wc -l | tr -d ' ')

Step 3: Categorize Sessions

Group by prefix pattern:

  • dev-* → Development environments
  • agent-* → Spawned agents
  • claude-* → Claude Code sessions
  • monitor-* → Monitoring sessions
  • Others → Miscellaneous
DEV_SESSIONS=$(echo "$SESSIONS" | grep "^dev-" || true)
AGENT_SESSIONS=$(echo "$SESSIONS" | grep "^agent-" || true)
CLAUDE_SESSIONS=$(echo "$SESSIONS" | grep "^claude-" || true)

Step 4: Extract Details for Each Session

For each session, gather:

Window Information:

tmux list-windows -t "$SESSION" -F '#{window_index}:#{window_name}:#{window_panes}'

Running Processes (from first pane of each window):

tmux capture-pane -t "$SESSION:0.0" -p -S -10 -E 0

Port Detection (check for listening ports):

# Extract ports from session metadata
if [ -f ".tmux-dev-session.json" ]; then
    BACKEND_PORT=$(jq -r '.backend.port // empty' .tmux-dev-session.json)
    FRONTEND_PORT=$(jq -r '.frontend.port // empty' .tmux-dev-session.json)
fi

# Or detect from process list
lsof -nP -iTCP -sTCP:LISTEN | grep -E "node|python|uv|npm"

Step 5: Load Session Metadata

Dev Environment Metadata (.tmux-dev-session.json):

if [ -f ".tmux-dev-session.json" ]; then
    PROJECT=$(jq -r '.project' .tmux-dev-session.json)
    TYPE=$(jq -r '.type' .tmux-dev-session.json)
    BACKEND_PORT=$(jq -r '.backend.port // "N/A"' .tmux-dev-session.json)
    FRONTEND_PORT=$(jq -r '.frontend.port // "N/A"' .tmux-dev-session.json)
    CREATED=$(jq -r '.created' .tmux-dev-session.json)
fi

Agent Metadata ({{HOME_TOOL_DIR}}/agents/*.json):

if [ -f "/.claude/agents/${SESSION}.json" ]; then
    AGENT_TYPE=$(jq -r '.agent_type' "/.claude/agents/${SESSION}.json")
    TASK=$(jq -r '.task' "/.claude/agents/${SESSION}.json")
    STATUS=$(jq -r '.status' "/.claude/agents/${SESSION}.json")
    DIRECTORY=$(jq -r '.directory' "/.claude/agents/${SESSION}.json")
    CREATED=$(jq -r '.created' "/.claude/agents/${SESSION}.json")
fi

Step 6: tmuxwatch Integration

If tmuxwatch is available, offer enhanced view:

if command -v tmuxwatch &> /dev/null; then
    echo ""
    echo "📊 Enhanced Monitoring Available:"
    echo "   Real-time TUI: tmuxwatch"
    echo "   JSON export:   tmuxwatch --dump | jq"
    echo ""

    # Optional: Use tmuxwatch for structured data
    TMUXWATCH_DATA=$(tmuxwatch --dump 2>/dev/null || echo "{}")
fi

Step 7: Generate Comprehensive Report

# tmux Sessions Overview

**Total Active Sessions**: {count}
**Total Windows**: {window_count}
**Total Panes**: {pane_count}

---

## Development Environments ({dev_count})

### 1. dev-myapp-1705161234
- **Type**: fullstack
- **Project**: myapp
- **Status**: ⚡ Active (attached)
- **Windows**: 4 (servers, logs, claude-work, git)
- **Panes**: 8
- **Backend**: Port 8432 → http://localhost:8432
- **Frontend**: Port 3891 → http://localhost:3891
- **Created**: 2025-01-13 14:30:00 (2h ago)
- **Attach**: `tmux attach -t dev-myapp-1705161234`

---

## Spawned Agents ({agent_count})

### 2. agent-1705160000
- **Agent Type**: codex
- **Task**: Refactor authentication module
- **Status**: ⚙️  Running (15 minutes)
- **Working Directory**: /workspace/myapp
- **Git Worktree**: worktrees/agent-1705160000
- **Windows**: 1 (work)
- **Panes**: 2 (agent | monitoring)
- **Last Output**: "Analyzing auth.py dependencies..."
- **Attach**: `tmux attach -t agent-1705160000`
- **Metadata**: `{{HOME_TOOL_DIR}}/agents/agent-1705160000.json`

### 3. agent-1705161000
- **Agent Type**: aider
- **Task**: Generate API documentation
- **Status**: ✅ Completed (5 minutes ago)
- **Output**: Documentation written to docs/api/
- **Attach**: `tmux attach -t agent-1705161000` (review)
- **Cleanup**: `tmux kill-session -t agent-1705161000`

---

## Running Processes Summary

| Port | Service      | Session                  | Status  |
|------|--------------|--------------------------|---------|
| 8432 | Backend API  | dev-myapp-1705161234     | Running |
| 3891 | Frontend Dev | dev-myapp-1705161234     | Running |
| 5160 | Supabase     | dev-shotclubhouse-xxx    | Running |

---

## Quick Actions

**Attach to session**:
```bash
tmux attach -t <session-name>

Kill session:

tmux kill-session -t <session-name>

List all sessions:

tmux ls

Kill all completed agents:

for session in $(tmux ls | grep "^agent-" | cut -d: -f1); do
    STATUS=$(jq -r '.status' "{{HOME_TOOL_DIR}}/agents/${session}.json" 2>/dev/null)
    if [ "$STATUS" = "completed" ]; then
        tmux kill-session -t "$session"
    fi
done

Recommendations

{generated based on findings}


### Step 8: Provide Contextual Recommendations

**If completed agents found**:

⚠️ Found 1 completed agent session:

  • agent-1705161000: Task completed 5 minutes ago

Recommendation: Review results and clean up: tmux attach -t agent-1705161000 # Review tmux kill-session -t agent-1705161000 # Cleanup


**If long-running detached sessions**:

💡 Found detached session running for 2h 40m:

  • dev-api-service-1705159000

Recommendation: Check if still needed: tmux attach -t dev-api-service-1705159000


**If port conflicts detected**:

⚠️ Port conflict detected:

  • Port 3000 in use by dev-oldproject-xxx
  • New session will use random port instead

Recommendation: Clean up old session if no longer needed


## Output Formats

### Compact (Default)

5 active sessions:

  • dev-myapp-1705161234 (fullstack, 4 windows, active)
  • dev-api-service-1705159000 (backend-only, 4 windows, detached)
  • agent-1705160000 (codex, running 15m)
  • agent-1705161000 (aider, completed ✓)
  • claude-work (main session, current)

3 running servers:

  • Port 8432: Backend API (dev-myapp)
  • Port 3891: Frontend Dev (dev-myapp)
  • Port 5160: Supabase (dev-shotclubhouse)

### Detailed (Verbose)

Full report with all metadata, sample output, recommendations.

### JSON (Programmatic)

```json
{
  "sessions": [
    {
      "name": "dev-myapp-1705161234",
      "type": "dev-environment",
      "category": "fullstack",
      "windows": 4,
      "panes": 8,
      "status": "attached",
      "created": "2025-01-13T14:30:00Z",
      "ports": {
        "backend": 8432,
        "frontend": 3891
      },
      "metadata_file": ".tmux-dev-session.json"
    },
    {
      "name": "agent-1705160000",
      "type": "spawned-agent",
      "agent_type": "codex",
      "task": "Refactor authentication module",
      "status": "running",
      "runtime": "15m",
      "directory": "/workspace/myapp",
      "worktree": "worktrees/agent-1705160000",
      "metadata_file": "{{HOME_TOOL_DIR}}/agents/agent-1705160000.json"
    }
  ],
  "summary": {
    "total_sessions": 5,
    "total_windows": 12,
    "total_panes": 28,
    "running_servers": 3,
    "active_agents": 1,
    "completed_agents": 1
  },
  "ports": [
    {"port": 8432, "service": "Backend API", "session": "dev-myapp-1705161234"},
    {"port": 3891, "service": "Frontend Dev", "session": "dev-myapp-1705161234"},
    {"port": 5160, "service": "Supabase", "session": "dev-shotclubhouse-xxx"}
  ]
}

Integration with Commands

This skill is used by:

  • /tmux-status command (user-facing command)
  • Automatically before starting new dev environments (conflict detection)
  • By spawned agents to check session status

Dependencies

  • tmux (required)
  • jq (required for JSON parsing)
  • lsof (optional, for port detection)
  • tmuxwatch (optional, for enhanced monitoring)

File Structure

{{HOME_TOOL_DIR}}/agents/
  agent-{timestamp}.json           # Agent metadata

.tmux-dev-session.json             # Dev environment metadata (per project)

/tmp/tmux-monitor-cache.json       # Optional cache for performance

Related Commands

  • /tmux-status - User-facing wrapper around this skill
  • /spawn-agent - Creates sessions that this skill monitors
  • /start-local, /start-ios, /start-android - Create dev environments

Steering Protocol

Beyond monitoring, use these patterns to actively manage coding sessions.

Session Naming Convention

Use consistent names so sessions are self-documenting and parseable:

{tool}-{scope}-{id}[-{desc}]
Segment Values Example
tool cc (Claude Code), codex, pi cc
scope issue, fix, pr, feature, task issue
id Issue number, PR number, or short identifier 174
desc Optional short slug auth-refactor

Examples: cc-issue-174-auth-refactor, codex-fix-1520, cc-pr-186

Monitoring Signals

When monitoring a coding session, look for these signals:

Signal Action
Model is generating code Let it work
"I'll now..." planning text Verify approach is correct
Error/stack trace repeating Intervene (steer)
Idle / waiting for input Check if stuck or done
"I've completed..." summary Move to verify phase
Session has exited Check output / PR status

Steering (when intervention is needed)

# Correct course
tmux send-keys -t "${SESSION}" \
  "STOP. You're going the wrong direction. <specific correction>" Enter

# Unstick
tmux send-keys -t "${SESSION}" \
  "You seem stuck. Try: <specific suggestion>" Enter

# Add context
tmux send-keys -t "${SESSION}" \
  "Additional context: <file path, pattern, constraint>" Enter

# Abort
tmux send-keys -t "${SESSION}" "/exit" Enter

Steering Rules

  1. Be specific. "Fix the types" is bad. "Change costTotal to v.optional(v.float64())" is good.
  2. Don't over-steer. Interruptions reset context. If on track, let it work.
  3. One correction at a time. Multiple simultaneous corrections confuse the model.
  4. Stuck 3+ times on same issue? Kill session, rethink approach, respawn with better prompt.

Completion Detection

Detect session state from capture-pane output:

OUTPUT=$(tmux capture-pane -t "$SESSION" -p | tail -30)

# Completion signals
echo "$OUTPUT" | grep -qE "I've completed|changes have been|PR.*created|committed.*pushed" && echo "DONE"

# Error signals
echo "$OUTPUT" | grep -qE "Error:|FATAL|panic|OOM|killed|context.*exhausted" && echo "ERROR"

# Stuck signals (same error repeating 3+ times)
echo "$OUTPUT" | grep -iE "error|fail|fatal|panic" | sort | uniq -c | sort -rn | head -1 | awk '$1 >= 3 {print "STUCK"}'

Session Health Check

Periodically check for stale sessions:

tmux list-sessions -F '#{session_name}' 2>/dev/null | while IFS= read -r s; do
  [ -z "$s" ] && continue
  LAST_ACTIVITY=$(tmux display -t "$s" -p '#{session_activity}')
  IDLE_SECS=$(( $(date +%s) - LAST_ACTIVITY ))
  if [ $IDLE_SECS -gt 3600 ]; then
    echo "⚠️ $s idle for ${IDLE_SECS}s — consider cleanup"
  fi
done

Notes

  • This skill is read-only (monitoring/discovery), never modifies sessions
  • Steering commands above are for manual intervention when needed
  • Safe to run anytime without side effects
  • Provides snapshot of current state
  • Can be cached for performance (TTL: 10 seconds)
  • Should be run before potentially conflicting operations

04 同仓库更多 Skills

stevengonsalvez
stevengonsalvez/ainb-toolkit

well-formed

Fixture skill that satisfies every mechanical rule, used to prove the conformance check passes a clean tree instead of failing everything.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

underscore-tools

Fixture skill that spells the tool allowlist key with an underscore instead of the hyphen the spec requires.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

no-frontmatter

暂无简介

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

long-description

Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling. Fixture skill with a deliberately oversized description used to prove the conformance check rejects anything past the 1024 character ceiling.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

some-other-name

Fixture skill whose frontmatter name does not match its parent directory name.

★ 1
stevengonsalvez
stevengonsalvez/ainb-toolkit

bad_Name

Fixture skill whose name uses an underscore and a capital letter, so it violates the agentskills.io name pattern.

★ 1