Tmux Utilities

The devenv-full container includes custom tmux utilities optimized for Claude Code development workflow. These utilities provide seamless session management with syntax highlighting, Ghostty integration, and advanced output capture.

CRITICAL: Always use these tmux utilities when running development scripts. This prevents duplicate processes and keeps synchronization between Claude and the user.

Available Utilities

Command	Description
`tx`	Send command to tmux session (smart execution)
`txout`	Capture output from tmux session
`cx`	Create tmux session + open Ghostty
`cxa`	Attach to existing tmux session
`cxl`	List all tmux sessions
`cxk`	Kill tmux session

Installation

Utilities are pre-installed in devenv-full at ~/dotfiles/claude-tmux/ and added to PATH.

Core Utilities

`tx` - Smart Command Executor

Send commands to tmux sessions with automatic output capture and syntax highlighting.

tx <session> <command> [options]

Features:

Auto-wait for command completion (detects prompt return)
Auto-capture and display output with syntax highlighting
Configurable timeout (default: 30s)
Beautiful formatted output with icons and colors

Options:

--no-wait, -nw - Fire and forget mode
--timeout, -t N - Custom timeout in seconds
--raw, -r - Raw output, no formatting
--lines, -l N - Lines to capture (default: 200)
--help, -h - Show help

Examples:

# Execute, wait, and show output
tx music-api "bun run dev"

# Fire and forget (for long-running servers)
tx music-api "bun run dev" --no-wait

# Custom timeout for slow operations
tx build-server "npm run build" -t 120

# Complex command with pipes (tx handles escapes)
tx music-api "curl -s api.example.com | jq '.data.users'"

# Capture more output
tx music-api "bun test" --lines 500

Output:

▶ music-api → bun run dev
◐ Waiting (30s timeout)...
✓ Done in 2.34s
───────────────────────────────────────────────────────
$ bun run dev
🔮 Starting development server...
➜  Local:   http://localhost:3000/
➜  Network: use --host to expose
───────────────────────────────────────────────────────

`txout` - Smart Output Capture

Capture and display output from tmux sessions.

txout <session> [lines] [options]

Features:

Syntax highlighting by default
Follow mode (-f) for live tail
Background capture (-b) returns immediately with PID
JSON detection and formatting

Options:

--follow, -f - Live follow mode (Ctrl+C to stop)
--bg, -b - Background capture
--raw, -r - Raw output, no formatting
--all, -a - Capture all lines
--help, -h - Show help

Examples:

# Show last 50 lines (default)
txout music-api

# Show last 100 lines
txout music-api 100

# Live follow mode
txout music-api -f

# Background capture to file
txout music-api -b
# Returns: Background capture PID: 12345, Log: /tmp/txout_music-api_12345.log

# Raw output for piping
txout music-api -r | grep "error"

Follow Mode:

$ txout music-api -f
◉ music-api (Ctrl+C)
─── music-api───────────────────────────────────────
$ bun run dev
Starting server...
Ready on http://localhost:3000
[continues updating...]

`cx` - Create Session

Create new tmux session and open Ghostty window.

cx [session-name] [--no-ghostty]

Features:

Creates tmux session with custom config
Opens Ghostty window automatically
Displays welcome banner with ASCII art
Copies attach command to clipboard

Options:

--no-ghostty - Create session without opening Ghostty

Examples:

# Create session "shared" (default)
cx

# Create named session
cx music-api

# Create without Ghostty
cx build-server --no-ghostty

Output:

Created tmux session: music-api
Opened Ghostty and attached to session

Commands:
  cxa music-api     - Attach from another terminal
  cxl               - List all sessions
  Ctrl+A d          - Detach from session
  Ctrl+A |          - Split horizontal
  Ctrl+A -          - Split vertical

`cxa` - Attach to Session

Attach to existing tmux session.

cxa [session-name]

Examples:

# Attach to specific session
cxa music-api

# List sessions if no name given
cxa
# Shows available sessions

`cxl` - List Sessions

List all active tmux sessions.

cxl

Output:

Active tmux sessions:
  ● music-api: 1 windows (created Wed Jan 15 10:30:00 2025)
  ● vps-helsinki: 2 windows (created Wed Jan 15 09:15:00 2025)

`cxk` - Kill Session

Kill a tmux session.

cxk [session-name]

WARNING: This kills the entire session and all running processes. Ensure work is saved first.

Workflow

Standard Development Workflow

Create session for project:

cx music-api

Run development server:

tx music-api "bun run dev"

Monitor output:

txout music-api -f

Run tests in background:

tx music-api "bun test" --no-wait

Check test results:

txout music-api 100

VPS/SSH Workflow

For remote development sessions:

# Create VPS session
cx vps-helsinki

# SSH into VPS
tx vps-helsinki "ssh root@helsinki.example.com"

# Run commands on VPS
tx vps-helsinki "docker ps"
tx vps-helsinki "systemctl status nginx"

# Capture output
txout vps-helsinki 100

Multi-Project Workflow

Manage multiple projects simultaneously:

# Create sessions
cx music-api
cx yt-dl
cx bundlp

# Start all dev servers
tx music-api "bun run dev" --no-wait
tx yt-dl "bun run dev" --no-wait
tx bundlp "bun run dev" --no-wait

# Check status
cxl
txout music-api 10
txout yt-dl 10
txout bundlp 10

tmux Configuration

All sessions use custom config at ~/dotfiles/claude-tmux/tmux.conf:

Key Features:

Prefix: Ctrl+A (avoids conflict with Claude Code's Ctrl+B)
Mouse: Enabled for click panes and scroll history
Escape time: 0 (critical for vim/nvim)
Status bar: Cyberpunk/Synthwave style

Keybindings

Keybinding	Action
`Ctrl+A c`	Create new window
`Ctrl+A d`	Detach from session
`Ctrl+A \|`	Split horizontal
`Ctrl+A -`	Split vertical
`Alt+←/→/↑/↓`	Navigate panes (no prefix)
`Ctrl+Alt+←/→`	Resize panes
`Ctrl+A [`	Enter scroll/copy mode
`Ctrl+A ]`	Paste buffer

Status Bar

The status bar shows:

Session name and window number
Git branch (if in git repo)
Current path
CPU usage
Current time

New sessions display a welcome banner with:

Random ASCII art (Mr. Robot themed)
Random quote
System info (session, time, uptime, IP)
Utilities reference

Troubleshooting

Session already exists

$ cx music-api
Session 'music-api' already exists
Use: cxa music-api  (to attach)
Or:  tmux kill-session -t music-api  (to kill)

# Solution: Use cxa to attach, or cxk to kill

Command not found

$ tx music-api "bun run dev"
bash: tx: command not found

# Solution: Utilities are in ~/dotfiles/claude-tmux/
export PATH="$PATH:$HOME/dotfiles/claude-tmux"

Escape sequences in commands

# PROBLEM: This fails with regular tmux send-keys
tmux send-keys -t music-api "echo 'test' | jq" Enter

# SOLUTION: tx handles escapes automatically
tx music-api "echo 'test' | jq"

Output capture issues

# If syntax highlighting fails, use raw mode
txout music-api -r

# If output is truncated, capture more lines
txout music-api 500

# For background capture, read the log file
txout music-api -b
cat /tmp/txout_music-api_*.log

Session Naming Conventions

Standard session names for common projects:

Session	Project
`music-api`	mks-music-api-bot
`yt-dl`	yt-dlp-tui-bun
`bundlp`	bundlp
`att`	animated-text-tokens
`vps-helsinki`	SSH connection to Helsinki VPS

Performance Tips

Use --no-wait for long-running servers to avoid timeout
Use background capture (-b) for monitoring without blocking
Adjust timeout for operations that take longer than 30s
Limit capture lines for large outputs to improve performance

Integration with Claude Code

These utilities are designed for seamless Claude Code integration:

// Claude Code can use these utilities via MCP
{
  "tool": "tmux_send_keys",
  "arguments": {
    "name": "music-api",
    "command": "bun run dev",
    "wait": false
  }
}

{
  "tool": "tmux_capture_output",
  "arguments": {
    "name": "music-api",
    "lines": 100
  }
}

Tmux Utilities

Tmux Utilities

Available Utilities

Installation

Core Utilities

`tx` - Smart Command Executor

`txout` - Smart Output Capture

`cx` - Create Session

`cxa` - Attach to Session

`cxl` - List Sessions

`cxk` - Kill Session

Workflow

Standard Development Workflow

VPS/SSH Workflow

Multi-Project Workflow

tmux Configuration

Keybindings

Status Bar

Welcome Banner

Troubleshooting

Session already exists

Command not found

Escape sequences in commands

Output capture issues

Session Naming Conventions

Performance Tips

Integration with Claude Code

Actions

On this page