📟 linux-session-multiplexing

A quick-reference guide for Linux operating system commands, shell optimizations, process auditing, and complete interactive/programmatic tmux multiplexing controls.

---

🐧 Linux Core commands & System Audits

📁 File Permissions & System Paths

You'll often need to manage file ownership and execution rights. Use these commands to inspect and modify permissions.

### View detailed directory listing with ownership, size, and permissions
ls -la ~/my-project

### Change file permissions (755 = owner read/write/execute, group/others read/execute)
chmod 755 start_agent_workspace.sh

### Change file ownership to current user and group recursively
chown -R $(whoami):$(whoami) ~/my-project

### Find absolute path of an executable
which python
which tmux

📡 Network: Port Audits & Webhooks

When services fail to communicate, verify port bindings and socket states with these network utilities.

### Check if ports (e.g. 5432 pgvector, 8000 FastAPI, 5678 n8n) are listening
netstat -tulpn | grep LISTEN
ss -tulpn | grep LISTEN

### Probe local endpoint connection response
curl -I http://127.0.0.1:8000/health

### Track active socket counts on port 8000
netstat -an | grep :8000 | wc -l

⚙️ Processes: CPU & Memory Audits

To diagnose slow performance or runaway memory usage, use these commands to monitor and terminate rogue processes.

### Display live, interactive system process usage (sorted by CPU/Memory)
top
htop

### Check RAM utilization metrics in Megabytes
free -h

### Check filesystem disk space utilization
df -h

### Find processes matching 'python' and print PIDs
pgrep -fl python

### Forcefully terminate a process by its PID
kill -9 [PID]

### Terminate all processes running a specific command
pkill -f agent.py

---

📟 tmux Command Reference (Session Multiplexing)

🎛️ Interactive Shortcuts (Prefix: Ctrl+b)

Press Ctrl+b together, release, then press the shortcut key below:

Shortcut	Target Action
d	Detach from active session (keep processes running in background)
c	Create a new full-screen window (tab)
n	Switch to the Next window
p	Switch to the Previous window
%	Split the active pane Vertically (left/right)
"	Split the active pane Horizontally (top/bottom)
x	Kill (close) the active pane
z	Zoom (maximize) active pane (press again to restore)
[	Enter Scroll Mode (use arrow keys to read history, press q to exit)

---

💻 tmux CLI (Terminal Commands)

1. Session Management

You can manage tmux sessions directly from your shell, starting background workers or gracefully shutting them down.

### Start a new tmux session with a custom name
tmux new-session -s agent-orchestrator

### Start a detached background session immediately
tmux new-session -d -s agent-background

### List all active background sessions running in memory
tmux list-sessions
tmux ls

### Reattach to a running session
tmux attach-session -t agent-orchestrator
tmux a -t agent-orchestrator

### Gracefully terminate a session
tmux kill-session -t agent-orchestrator

### Kill all active tmux sessions
tmux kill-server

2. Programmatic Layouts & Window Controls

Automate your terminal layout by programmatically dividing windows into side-by-side or stacked panes.

### Split a specific window vertically (creates horizontal panes)
tmux split-window -v -t agent-orchestrator:0

### Split a specific window horizontally (creates vertical panes)
tmux split-window -h -t agent-orchestrator:0

### Balance pane layout sizes evenly
tmux select-layout -t agent-orchestrator tiled
tmux select-layout -t agent-orchestrator even-horizontal
tmux select-layout -t agent-orchestrator even-vertical

### Select and activate a specific pane index (e.g. Pane 1)
tmux select-pane -t agent-orchestrator:0.1

3. Keystroke Injection & Buffer Captures

You can inject commands into running sessions and scrape their historical text output for remote logging.

### Send command string to a specific pane (Pane 0) and trigger Enter (C-m)
tmux send-keys -t agent-orchestrator:0.0 "python run_loop.py" C-m

### Capture the complete scrollback text buffer of a pane and print to stdout
tmux capture-pane -p -t agent-orchestrator:0.0

### Save a pane scrollback buffer directly to a file
tmux capture-pane -S -100 -E now -p -t agent-orchestrator:0.0 > scrollback_dump.log

---

🐍 Python tmux Orchestration (Subprocess Cheat)

Use Python's subprocess engine to automate detached execution and telemetry grabs programmatically:

import subprocess

### 1. Spawn a detached tmux runner
subprocess.run(["tmux", "new-session", "-d", "-s", "agent-runner"])

### 2. Inject command payload
subprocess.run(["tmux", "send-keys", "-t", "agent-runner:0.0", "python agent.py", "C-m"])

### 3. Poll scrollback buffer autonomously
result = subprocess.run(
    ["tmux", "capture-pane", "-p", "-t", "agent-runner:0.0"],
    capture_output=True,
    text=True
)
print("Active Console Logs:\n", result.stdout)

### 4. Clean up environment
subprocess.run(["tmux", "kill-session", "-t", "agent-runner"])