Module 2: Hybrid GUI Editor + tmux

Introduction

Best of both worlds: GUI productivity + terminal power

Learn to integrate VS Code or Cursor with your tmux workflows for maximum productivity. This module bridges the gap between comfortable GUI editing and powerful terminal-based AI workflows.

What You'll Learn

Set up VS Code/Cursor to work seamlessly with tmux
Troubleshoot PATH and environment issues that break tools
Design efficient hybrid workflows for daily ops work
Create a personal working agreement for Editor + tmux + Claude

Why Hybrid?

Many ops professionals love their GUI editor for editing configs and scripts, but need tmux for persistent sessions, Claude interactions, and monitoring. This module teaches you to get the best of both without environment headaches.

Lesson 2.1: VS Code/Cursor Setup

Configure your GUI editor for tmux integration

Integration Setup

Opening Your Workspace from tmux

When you're inside a tmux session and want to open VS Code or Cursor pointing to your current directory:

Launch from tmux

# For VS Code
code ~/ops-workspace

# For Cursor
cursor ~/ops-workspace

# Open current directory
code .
cursor .

Recommended VS Code Extensions

Remote - SSH: Edit files on remote servers where your tmux runs
GitLens: Enhanced Git visibility for ops work
YAML/JSON: For config file editing
Markdown All in One: For SOPs and documentation

Pro Tip

Keep VS Code/Cursor open for editing, but run Claude in tmux. This separation keeps AI interactions persistent even if your editor crashes or restarts.

Lesson 2.2: PATH Troubleshooting

Fix common environment issues

Common Issues

The #1 frustration when combining GUI editors with tmux: tools work in one place but not the other. Here's what to look for:

Claude not found when launched from VS Code integrated terminal
Different PATH in terminal vs GUI editor's integrated terminal
Environment variables not loading (API keys, config paths)
Wrong shell profile being sourced in different contexts

Troubleshooting Checklist

Use this systematic checklist when a tool works in one terminal but not another:

tmux Tool Troubleshooting Checklist

Step-by-step guide to diagnose and fix PATH, environment, and shell configuration issues between normal terminals, tmux, and VS Code/Cursor.

Quick Diagnostic Commands

Step 1: Check PATH differences

# In your normal terminal
echo $PATH

# Then in tmux
echo $PATH

# Compare side by side - are they different?

Step 2: Check which binary

# In normal terminal
which claude

# In tmux
which claude

# If tmux says "not found", add PATH export to .bashrc

Step 3: Compare full environment

# Capture environment in normal terminal
env | sort > /tmp/env-normal.txt

# Capture in tmux
env | sort > /tmp/env-tmux.txt

# Compare
diff /tmp/env-normal.txt /tmp/env-tmux.txt

Debug Helper Script

Run this script to quickly dump your environment and start a debug session:

ops-tmux-debug.sh

A simple helper that prints your current environment and starts a named tmux session for debugging. Great for capturing environment state before reporting issues.

Common Fixes

Fix: Add PATH to .bashrc

If tools work in your login shell but not in tmux, add the PATH export to ~/.bashrc (not just ~/.profile or ~/.bash_profile):

~/.bashrc addition

# Add to ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

# For Node.js tools like claude
export PATH="$HOME/.npm-global/bin:$PATH"

VS Code Terminal Settings

In VS Code settings, check that "Terminal > Integrated: Inherit Env" is enabled. Also look for terminal.integrated.env.* overrides that might conflict.

Lesson 2.3: Workflow Design

Create your optimal hybrid setup

Best Practices

A well-designed hybrid workflow leverages each tool's strengths:

The Three-Tool Model

GUI Editor (VS Code/Cursor): Editing configs, scripts, SOPs, and runbooks
tmux: Persistent sessions for monitoring, logs, and Claude interactions
Claude: Explaining errors, drafting commands, proposing fixes (with human approval)

Personal Working Agreement

Document how you'll use each tool. This template helps establish clear boundaries and workflows:

Ops Working Agreement

A fillable template covering: what you use your editor for, what you use tmux for, Claude's responsibilities and limits, your default tmux layout, and handoff notes.

Recommended tmux Layout for Ops

Default Ops Layout

# Session: ops-main
# Window 1: "Monitor"
#   Pane 1: Claude (conversation pane)
#   Pane 2: Logs / dashboards
# Window 2: "Tickets"
#   Pane 1: Ticket commands / tools
#   Pane 2: Note-taking

# Create this layout:
tmux new -s ops-main -n Monitor
# (In pane 1, run claude)
# Ctrl-b % to split vertically
# (In pane 2, run your log viewer)
# Ctrl-b c to create Window 2
# tmux rename-window Tickets

Exercise: Design Your Workflow

Download the Working Agreement template above
Fill in what you use your editor for (be specific!)
Fill in what you'll use tmux for
Define Claude's boundaries: what can it suggest vs. what needs your explicit approval?
Sketch your ideal tmux layout (session name, windows, panes)

Handoff Practice

If you work with a team or do shift handoffs, include notes about which tmux sessions matter and their current state. This prevents "what was running?" confusion.

All Module 2 Downloads

Quick access to all resources from this module