OpenClaw ClaudeCode Controller

openclaw-claudecode Skill

Control Claude Code through tmux sessions for long-running development tasks.

Environment Check & Initialization (Required for First Use)

0.1 Check tmux

# Check if tmux is installed
which tmux || echo "tmux not found"
If not installed, install tmux
CentOS/RHEL/Rocky:
dnf install -y tmux || yum install -y tmux
Ubuntu/Debian:
apt install -y tmux
Alpine:
apk add tmux

0.2 Check Claude Code

# Check if claude command is available
which claude || echo "claude not found"
If not installed, install Claude Code
npm install -g @anthropic-ai/claude-code
Or use official install script
curl -fsSL https://claude.ai/install.sh | sh

0.3 Verify Claude Code Works

# Check version
claude --version
Test simple call (requires valid authentication)
claude --print "hello" 2>&1 | head -5

Common Issues:

0.4 Create Regular User (CC refuses root)

# Check if regular user exists
id  || echo "user not found"
Create user (if not exists)
useradd -m -s /bin/bash 
Set password (optional)
echo ":" | chpasswd

Recommended usernames: claudecode, developer, ccdev

0.5 Environment Check Summary

Run complete environment check:

# One-click check script
check_env() {
  echo "=== tmux ==="
  which tmux && tmux -V || echo "❌ tmux missing"
  echo "=== claude ==="
  which claude && claude --version || echo "❌ claude missing"
  echo "=== user ==="
  id  || echo "❌ user missing"
  echo "=== auth ==="
  claude --print "test" 2>&1 | grep -E "error|Error" && echo "❌ auth failed" || echo "✅ auth ok"
}
check_env

All checks must pass before proceeding

Core Flow

1. Locate Project Directory

# Check directory exists
ls -la 
Check if it's a git repo (CC requires)
ls -la /.git

Directory not found → Immediately ask user to confirm path

2. Create tmux Session

# Create session (with working directory)
tmux new-session -d -s  -c 
Verify session
tmux list-sessions

Session naming suggestion: cc- or claude-

3. Switch User + Start CC

CC refuses root, must switch to regular user:

# Send command: switch user + cd + start CC
tmux send-keys -t  "su -  -c 'cd  && claude --dangerously-skip-permissions'" Enter

Key Parameters:

4. Send Development Commands

# Single line command
tmux send-keys -t  "" Enter
Multi-line command (use load-buffer)
cat << 'EOF' | tmux load-buffer -
First line
Second line
Third line
EOF
tmux paste-buffer -t 
tmux send-keys -t  Enter

5. Monitor Progress

# View recent output
tmux capture-pane -t  -p | tail -30
View full scroll history
tmux capture-pane -t  -p -S -
Check if input is needed
tmux capture-pane -t  -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission|y/n"

6. Auto-confirm/Interact

# Send confirmation
tmux send-keys -t  y Enter
Send cancel
tmux send-keys -t  n Enter
Send Ctrl+C interrupt
tmux send-keys -t  C-c

Complete Example

Start Development Task (with Environment Check)

# 0. Environment check
which tmux || dnf install -y tmux
which claude || npm install -g @anthropic-ai/claude-code
id claudecode || useradd -m claudecode
1. Create session
tmux new-session -d -s cc- -c 
2. Start CC (regular user)
tmux send-keys -t cc- "su - claudecode -c 'cd  && claude --dangerously-skip-permissions'" Enter
3. Wait for CC to start (~5 seconds)
sleep 5
4. Send development task
tmux send-keys -t cc- "" Enter
5. Monitor progress
tmux capture-pane -t cc- -p | tail -20

Check CC Process Status

# Check if CC is running
ps aux | grep -i claude | grep -v grep
Check runtime duration
ps -o pid,etime,cmd -p $(pgrep -f "claude --dangerously")

Session Management

# List all sessions
tmux list-sessions
List all attach clients
tmux list-clients
Attach to session (interactive view)
tmux attach -t 
Kill session
tmux kill-session -t 
Kill other attach clients (keep yours)
tmux detach-client -t  -a
Detach from attached session
Shortcut: Ctrl+B then D

Common Issues

CC Refuses Root

Solution: Switch to non-root user

tmux send-keys -t  "su -  -c 'cd  && claude --dangerously-skip-permissions'" Enter

504 Gateway Timeout

Cause: Claude API server temporary error

Solution: Wait 1-2 minutes then restart CC

# Interrupt current process
tmux send-keys -t  C-c
Restart
tmux send-keys -t  "claude --dangerously-skip-permissions" Enter

CC Stuck at Confirmation Prompt

Detection:

tmux capture-pane -t  -p | tail -5 | grep -E "y/n|Yes|No|proceed"

Solution:

tmux send-keys -t  y Enter

Attach Processes Residue

Detection:

tmux list-clients
ps aux | grep "tmux attach" | grep -v grep

Cleanup:

# Kill extra attach processes
kill  
Or kick other clients
tmux detach-client -t  -a

Check CC Completion Status

# Check if back to shell prompt
tmux capture-pane -t  -p | tail -3 | grep -E "\\$|#|❯"
Check git commits
cd  && git log --oneline -3

Best Practices

1. Must check environment on first use: tmux, claude, regular user, authentication 2. Clear session naming: cc-- for managing multiple tasks 3. Regular progress check: Use capture-pane every 30 minutes 4. Record session ID: Note session name and start time in memory file 5. Clean residual attach: Regularly check tmux list-clients and cleanup

Command Reference

| Command | Purpose | |---------|---------| | tmux new-session -d -s NAME -c DIR | Create background session | | tmux send-keys -t NAME "CMD" Enter | Send command | | tmux capture-pane -t NAME -p | Capture output | | tmux capture-pane -t NAME -p -S - | Capture full history | | tmux list-sessions | List sessions | | tmux list-clients | List attach clients | | tmux kill-session -t NAME | Kill session | | tmux attach -t NAME | Attach session | | tmux detach-client -t NAME -a | Kick other clients | | tmux send-keys -t NAME C-c | Send Ctrl+C | | tmux send-keys -t NAME y Enter | Send confirmation | | tmux send-keys -t NAME n Enter | Send cancel |

| Check Command | Purpose | |---------------|---------| | which tmux | Check tmux | | which claude | Check claude | | claude --version | Check version | | id | Check user exists | | ps aux | grep claude | Check process |

1. Must check environment on first use: tmux, claude, regular user, authentication 2. Clear session naming: cc-- for managing multiple tasks 3. Regular progress check: Use capture-pane every 30 minutes 4. Record session ID: Note session name and start time in memory file 5. Clean residual attach: Regularly check tmux list-clients and cleanup