zhongwei/gh-dashed-claude-marketplace-plugins-tmux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:17:58 +08:00
commit 72ca635273
15 changed files with 5327 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

503
references/session-lifecycle.md Normal file
View File

@@ -0,0 +1,503 @@
# Session Lifecycle Guide
> Practical guide for managing tmux sessions through their complete lifecycle - from creation to cleanup
## Overview
Tmux sessions managed by this skill follow a predictable lifecycle. Understanding these stages helps you make better decisions about when to create, reuse, or clean up sessions. This guide provides real-world workflows and decision trees for daily use.
**When to use this guide:**
- You're unsure whether to create a new session or reuse an existing one
- You need to debug a crashed or stuck session
- You want to understand proper cleanup workflows
- You're managing multiple parallel sessions
## Lifecycle Stages
```
┌─────────────┐
│ PRE-CHECK │ Check existing sessions
│ (optional) │ Tool: list-sessions.sh
└──────┬──────┘
│
↓
┌─────────────┐
│ CREATE │ Spawn new tmux session
│ │ Tool: create-session.sh
└──────┬──────┘
│
↓
┌─────────────┐
│ INIT │ Wait for startup (prompt appears)
│ │ Tool: wait-for-text.sh
└──────┬──────┘
│
↓
┌─────────────┐
│ ACTIVE USE │ Send commands, capture output
│ │ Tools: safe-send.sh, wait-for-text.sh
└──────┬──────┘
│
↓
┌─────────────┐
│ IDLE │ Session exists but unused
│ │ Tool: list-sessions.sh (check status)
└──────┬──────┘
│
↓
┌─────────────┐
│ CLEANUP │ Remove dead/stale sessions
│ │ Tools: cleanup-sessions.sh, tmux kill-session
└─────────────┘
```
**Error recovery:**
- If session crashes → Check with `pane-health.sh`
- If session becomes zombie → Remove with `cleanup-sessions.sh`
- If network interruption → Reconnect using `tmux attach` or resume with session name
## Common Workflows
### 1. Quick Python Calculation (Ephemeral Session)
**Use case:** Run a one-off calculation, get the result, and cleanup immediately.
**Duration:** < 5 minutes
**Commands:**
```bash
# 1. Check no conflicts
./tools/list-sessions.sh
# 2. Create session
./tools/create-session.sh -n quick-calc --python
# 3. Send calculation
./tools/safe-send.sh -s quick-calc -c "import math; print(math.factorial(100))" -w ">>>" -T 10
# 4. Capture output
SOCKET=$(jq -r '.sessions["quick-calc"].socket' ~/.local/state/claude-tmux/.sessions.json)
tmux -S "$SOCKET" capture-pane -p -t quick-calc:0.0 -S -10
# 5. Cleanup immediately
tmux -S "$SOCKET" kill-session -t quick-calc
./tools/cleanup-sessions.sh
```
**When to use:** One-time calculations, quick tests, disposable experiments.
### 2. Long-Running Analysis (Persistent Session)
**Use case:** Hours or days of interactive REPL work with state preservation.
**Duration:** Hours to days
**Commands:**
```bash
# 1. Check existing sessions first
./tools/list-sessions.sh
# 2. Create persistent session with descriptive name
./tools/create-session.sh -n data-analysis-2025-11 --python
# 3. Load data (may take time)
./tools/safe-send.sh -s data-analysis-2025-11 -c "import pandas as pd" -w ">>>"
./tools/safe-send.sh -s data-analysis-2025-11 -c "df = pd.read_csv('large_dataset.csv')" -w ">>>" -T 300
# 4. Work interactively over time
./tools/safe-send.sh -s data-analysis-2025-11 -c "df.describe()" -w ">>>"
# ... hours later ...
./tools/safe-send.sh -s data-analysis-2025-11 -c "df.groupby('category').mean()" -w ">>>"
# 5. Check session health periodically
./tools/pane-health.sh -s data-analysis-2025-11
# 6. Cleanup only when done (days later)
./tools/list-sessions.sh # Verify it's the right session
tmux -S "$(jq -r '.sessions["data-analysis-2025-11"].socket' ~/.local/state/claude-tmux/.sessions.json)" kill-session -t data-analysis-2025-11
./tools/cleanup-sessions.sh
```
**When to use:** Long-running analysis, state preservation, multiple work sessions.
**Best practices:**
- Use descriptive names (include date or project name)
- Check health before resuming work
- Don't cleanup until completely done
- Capture important output early
### 3. Recovering from Crashed Session
**Use case:** Session died unexpectedly, need to investigate and restart.
**Duration:** 5-10 minutes
**Commands:**
```bash
# 1. Check session status
./tools/list-sessions.sh
# Output shows: status "dead" or "zombie"
# 2. Diagnose the issue
./tools/pane-health.sh -s crashed-session --format text
# Check exit code: 1=dead, 2=missing, 3=zombie
# 3. Capture any remaining output for debugging
SOCKET=$(jq -r '.sessions["crashed-session"].socket' ~/.local/state/claude-tmux/.sessions.json)
tmux -S "$SOCKET" capture-pane -p -t crashed-session:0.0 -S -200 > crash-output.txt 2>/dev/null || echo "Pane unavailable"
# 4. Remove dead session from registry
./tools/cleanup-sessions.sh # Removes dead sessions automatically
# 5. Create replacement session
./tools/create-session.sh -n crashed-session-recovery --python
# 6. Resume work with new session
./tools/safe-send.sh -s crashed-session-recovery -c "# Resuming from crash..." -w ">>>"
```
**When to use:** Session crashed, process died, debugging needed.
**Troubleshooting tips:**
- Always capture output before cleanup (may contain error messages)
- Check system logs if crash is mysterious: `dmesg`, `journalctl`
- Verify PYTHON_BASIC_REPL=1 was set (common cause of silent failures)
### 4. Multi-Session Workspace (Parallel Tasks)
**Use case:** Multiple parallel tasks (data loading, analysis, monitoring) in separate sessions.
**Duration:** Variable
**Commands:**
```bash
# 1. Check existing sessions
./tools/list-sessions.sh
# 2. Create multiple sessions with clear names
./tools/create-session.sh -n loader-session --python
./tools/create-session.sh -n analysis-session --python
./tools/create-session.sh -n monitor-session --python
# 3. Start parallel work
# Session 1: Load large dataset
./tools/safe-send.sh -s loader-session -c "import pandas as pd; df = pd.read_csv('huge.csv')" -w ">>>" -T 600 &
# Session 2: Run analysis on existing data
./tools/safe-send.sh -s analysis-session -c "results = analyze_data()" -w ">>>" -T 300 &
# Session 3: Monitor system
./tools/safe-send.sh -s monitor-session -c "import psutil; psutil.cpu_percent()" -w ">>>"
# 4. Check all sessions status
./tools/list-sessions.sh
# 5. Cleanup when done
./tools/cleanup-sessions.sh --all # Or cleanup individually
```
**When to use:** Parallel independent tasks, workspace organization, resource isolation.
**Best practices:**
- Use descriptive session names (purpose-based: loader-*, analysis-*, monitor-*)
- One session per major task (don't overload single session)
- Check `list-sessions.sh` frequently to monitor all sessions
- Cleanup all related sessions together when project complete
## Decision Trees
### Should I Create a New Session or Reuse?
```
Start
│
├─→ Is this a quick one-off task?
│ └─→ YES → Create new ephemeral session
│ (cleanup immediately after)
│
├─→ Do I have an existing session for this work?
│ ├─→ YES → Is it still alive?
│ │ ├─→ YES → Reuse existing session
│ │ └─→ NO → Create new session
│ └─→ NO → Create new session
│
└─→ Am I starting a new long-running project?
└─→ YES → Create new persistent session
(descriptive name with date/project)
```
**Rules of thumb:**
- ✅ **Create new** for: Different projects, parallel tasks, isolation needed
- ✅ **Reuse** for: Continuing same work, state preservation needed
- ❌ **Don't reuse** for: Unrelated tasks (state pollution), different projects
### When Should I Clean Up Sessions?
```
Start
│
├─→ Is session marked as "dead" or "zombie"?
│ └─→ YES → Cleanup immediately
│ (./tools/cleanup-sessions.sh)
│
├─→ Has the task completed?
│ └─→ YES → Cleanup immediately
│ (tmux kill-session + cleanup-sessions.sh)
│
├─→ Is session idle for > 1 hour?
│ ├─→ AND no state preservation needed?
│ │ └─→ YES → Cleanup
│ └─→ OR state needed?
│ └─→ NO → Keep (long-running analysis)
│
└─→ Am I done for the day but continuing tomorrow?
└─→ Keep session (resume later)
```
**Cleanup commands:**
```bash
# Remove only dead/zombie sessions (safe, default)
./tools/cleanup-sessions.sh
# Remove sessions older than 1 hour
./tools/cleanup-sessions.sh --older-than 1h
# Remove all sessions (careful!)
./tools/cleanup-sessions.sh --all
# Preview what would be removed (dry-run)
./tools/cleanup-sessions.sh --dry-run
```
### How Should I Handle Session Errors?
```
Error Detected
│
├─→ Is session responding to commands?
│ ├─→ NO → Check health (pane-health.sh)
│ │ ├─→ Dead/zombie → Capture output → Cleanup → Recreate
│ │ └─→ Alive but hung → Send C-c → Retry command
│ └─→ YES → Problem is elsewhere (not session)
│
├─→ Are commands being executed but output wrong?
│ └─→ Check PYTHON_BASIC_REPL=1 was set
│ └─→ Not set? Restart session with env var
│
└─→ Is prompt not appearing?
└─→ Increase timeout (-T flag)
└─→ Still failing? Check pane content manually
```
## Tool Reference Matrix
| Lifecycle Stage | Tool | Purpose | Example Command |
|-----------------|------|---------|-----------------|
| **Pre-check** | `list-sessions.sh` | Check existing sessions | `./tools/list-sessions.sh` |
| **Create** | `create-session.sh` | Spawn new session | `./tools/create-session.sh -n my-session --python` |
| **Init** | `wait-for-text.sh` | Wait for startup prompt | `./tools/wait-for-text.sh -s my-session -p ">>>" -T 15` |
| **Active Use** | `safe-send.sh` | Send commands safely | `./tools/safe-send.sh -s my-session -c "print(42)" -w ">>>"` |
| **Active Use** | `safe-send.sh` (multiline) | Send code blocks | `./tools/safe-send.sh -s my-session -m -c "def foo():\n return 42" -w ">>>"` |
| **Monitoring** | `pane-health.sh` | Check session health | `./tools/pane-health.sh -s my-session` |
| **Monitoring** | `list-sessions.sh` | View all sessions | `./tools/list-sessions.sh --json` |
| **Capture** | `tmux capture-pane` | Get session output | `tmux -S $SOCKET capture-pane -p -t session:0.0 -S -100` |
| **Cleanup** | `cleanup-sessions.sh` | Remove dead sessions | `./tools/cleanup-sessions.sh` |
| **Cleanup** | `tmux kill-session` | Terminate specific session | `tmux -S $SOCKET kill-session -t my-session` |
## Troubleshooting Quick Reference
### Session Not Found
**Symptom:** `./tools/safe-send.sh -s my-session -c "cmd"` fails with "Session 'my-session' not found in registry"
**Causes:**
1. Session was never created
2. Session was created but not registered (`--no-register` flag used)
3. Session was cleaned up by mistake
**Fixes:**
```bash
# Check what sessions exist
./tools/list-sessions.sh
# Check if session exists outside registry
./tools/find-sessions.sh --all
# Recreate session
./tools/create-session.sh -n my-session --python
```
### Commands Not Executing
**Symptom:** Commands sent but REPL shows no activity
**Causes:**
1. PYTHON_BASIC_REPL=1 not set (most common!)
2. Session crashed/dead
3. Prompt not detected correctly
**Fixes:**
```bash
# Check session health
./tools/pane-health.sh -s my-session --format text
# Manually check what's in the pane
SOCKET=$(jq -r '.sessions["my-session"].socket' ~/.local/state/claude-tmux/.sessions.json)
tmux -S "$SOCKET" capture-pane -p -t my-session:0.0 -S -20
# If Python REPL, verify PYTHON_BASIC_REPL=1 was set
# Symptom: You'll see fancy colored prompts instead of plain >>>
# Fix: Kill and recreate with correct env var
```
### Output Capture Issues
**Symptom:** `tmux capture-pane` returns incomplete or truncated output
**Causes:**
1. Pane history buffer too small
2. Lines wrapped due to terminal width
3. ANSI color codes interfering
**Fixes:**
```bash
# Capture more history (-S flag = start line)
tmux -S "$SOCKET" capture-pane -p -t session:0.0 -S -500
# Join wrapped lines (-J flag)
tmux -S "$SOCKET" capture-pane -p -J -t session:0.0 -S -200
# Strip ANSI color codes
tmux -S "$SOCKET" capture-pane -p -t session:0.0 | sed 's/\x1b\[[0-9;]*[a-zA-Z]//g'
```
### Dead/Zombie Sessions
**Symptom:** `./tools/list-sessions.sh` shows status "dead" or "zombie"
**Causes:**
1. Process crashed
2. Session was killed manually
3. Out of memory / system issue
**Fixes:**
```bash
# Capture any remaining output for debugging
SOCKET=$(jq -r '.sessions["dead-session"].socket' ~/.local/state/claude-tmux/.sessions.json)
tmux -S "$SOCKET" capture-pane -p -t dead-session:0.0 -S -500 > debug.txt 2>/dev/null
# Remove from registry
./tools/cleanup-sessions.sh
# Recreate if needed
./tools/create-session.sh -n replacement-session --python
```
### Multiple Sessions with Same Name
**Symptom:** `./tools/create-session.sh -n my-session --python` fails with "session already exists"
**Causes:**
1. Forgot to check existing sessions first
2. Previous session not cleaned up
**Fixes:**
```bash
# Check existing sessions
./tools/list-sessions.sh
# Use different name OR cleanup old session first
tmux -S "$SOCKET" kill-session -t my-session
./tools/cleanup-sessions.sh
# Then create new session
./tools/create-session.sh -n my-session --python
```
## Best Practices
### ✅ DO
1. **Always check before creating**
```bash
./tools/list-sessions.sh # Check for conflicts first
```
2. **Use descriptive session names**
```bash
# Good: data-analysis-2025-11, debug-api-auth, monitor-prod
# Bad: session1, test, tmp
```
3. **Set PYTHON_BASIC_REPL=1 for Python**
```bash
# This is handled by create-session.sh --python automatically
# But verify if creating manually
```
4. **Wait for prompts after every command**
```bash
./tools/safe-send.sh -s session -c "command" -w ">>>" -T 10
# Always include -w flag for synchronization
```
5. **Use session registry (-s flag)**
```bash
# Preferred: ./tools/safe-send.sh -s my-session -c "cmd"
# Avoid: ./tools/safe-send.sh -S $SOCKET -t session:0.0 -c "cmd"
```
6. **Check health before critical operations**
```bash
if ./tools/pane-health.sh -s session; then
./tools/safe-send.sh -s session -c "critical_command"
fi
```
7. **Use multiline mode for code blocks**
```bash
# 10x faster than line-by-line
./tools/safe-send.sh -s session -m -c "def foo():\n return 42" -w ">>>"
```
8. **Cleanup dead sessions regularly**
```bash
# Run periodically or in cleanup scripts
./tools/cleanup-sessions.sh
```
9. **Capture output early and often**
```bash
# Before making destructive changes
tmux -S "$SOCKET" capture-pane -p -t session:0.0 -S -200 > backup.txt
```
10. **Use --dry-run for cleanup preview**
```bash
# See what would be removed before executing
./tools/cleanup-sessions.sh --dry-run
./tools/cleanup-sessions.sh --older-than 2d --dry-run
```
### ❌ DON'T
1. **Don't create sessions without checking first** - Leads to name conflicts
2. **Don't reuse sessions for unrelated work** - State pollution causes bugs
3. **Don't forget -w flag when sending commands** - Race conditions
4. **Don't skip health checks before critical operations** - Pane might be dead
5. **Don't use generic session names** - Hard to manage multiple sessions
6. **Don't leave dead sessions in registry** - Clutters output, wastes resources
7. **Don't forget to cleanup ephemeral sessions** - Resource leaks
8. **Don't send commands too fast** - Wait for prompts between commands
9. **Don't ignore session health warnings** - Investigate issues early
10. **Don't use line-by-line for large code blocks** - Use multiline mode instead
## Related References
- [Session Registry Guide](./session-registry.md) - Deep dive on registry system
- [Direct Socket Control](./direct-socket-control.md) - Advanced manual socket management
- [Main SKILL.md](../SKILL.md) - Complete tmux skill documentation
---
**Version:** Documented for tmux skill v1.3.0+ (includes multiline support)