Skip to content

Instantly share code, notes, and snippets.

@enachb

enachb/muxile-integration.md

Created January 14, 2026 23:40
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save enachb/d988664682b64059334ae28619fd1674 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save enachb/d988664682b64059334ae28619fd1674 to your computer and use it in GitHub Desktop.
Download ZIP
Muxile Integration Guide for Claude Code - Mobile tmux session access
Raw
muxile-integration.md

Muxile Integration Guide

What is Muxile?

Muxile is a tmux plugin that provides mobile web access to your running tmux sessions. It creates a secure WebSocket tunnel through Cloudflare Workers, allowing you to monitor and control your terminal from any device with a web browser.

Why Use Muxile with Claude Code?

When running long-duration Claude Code tasks (multi-step refactoring, data processing, batch operations), you can:

  • Monitor progress from your phone without interrupting
  • Send follow-up commands or ask clarifying questions remotely
  • Share links with teammates to collaboratively debug issues
  • Receive actionable Discord notifications with direct session links
  • Keep working if your SSH connection drops

How It Works in This Project

Discord Hook Integration

The .claude/hooks/discord-notify.sh script automatically:

  1. Detects when Claude Code is running in a tmux session
  2. Generates a Muxile shareable link: muxile://open?session=<session-name>
  3. Embeds the link in Discord notifications with a "Resume Session" button
  4. Allows team members to jump directly into your session from Slack/Discord

Example notification:

đź”” Claude Code Stopped
Description: Task completed successfully
Project: cloud
Resume Session: [claude-work] (clickable link)

Setup Steps

1. Install tmux

# macOS
brew install tmux

# Linux
sudo apt install tmux

2. Install Muxile Dependencies

# macOS
brew install qrencode jq
cargo install websocat

# Ubuntu/Debian
sudo apt install qrencode jq
# websocat may need cargo install

3. Install Muxile Plugin

Option A: Using TPM (Recommended)

Add to ~/.tmux.conf:

set -g @plugin 'bjesus/muxile'
run '~/.tmux/tpm/tpm'

Then press Ctrl+b then I to install.

Option B: Manual

git clone https://github.com/bjesus/muxile.git ~/.tmux/plugins/muxile
echo "run '~/.tmux/plugins/muxile/muxile.tmux'" >> ~/.tmux.conf

4. Configure Muxile (Optional)

Add to ~/.tmux.conf:

set -g @muxile-port 8888      # Custom port (default: random)
set -g @muxile-host localhost # Set hostname

Using Muxile

Starting Your Session

# Create named tmux session
tmux new-session -s claude-work

# Navigate to project
cd /path/to/cloud

# Start Claude Code
claude

# Start a task...

Sharing the Session

# In the tmux session, press:
# prefix + Shift+T (typically: Ctrl+b then Shift+T)

# A QR code and shareable link will appear:
# muxile://open?session=claude-work
# https://muxile.github.io/#<token>

Accessing from Mobile

  1. Scan the QR code with your phone camera
  2. Open the link in your browser
  3. See your tmux pane content
  4. Type commands in the input field
  5. Commands execute in real-time

Stopping Sharing

# Press Ctrl+C to exit QR code view
# Press prefix + Shift+T again to disable sharing

Discord Hook Configuration

The hook automatically detects your tmux session and includes the Muxile link. No manual configuration needed!

To verify the hook is active:

ls -la .claude/hooks/
# Should see: discord-notify.sh

Advanced Usage

Persistent Detaching Workflow

# 1. Start long task in tmux
tmux new-session -s work
cd ~/project
claude

# 2. Start a refactoring task
# "Refactor the authentication system"

# 3. Get to a good checkpoint, then detach
# Press: Ctrl+b then d

# 4. From your phone, view progress via Muxile QR code
# (ask Claude Code to pause if needed)

# 5. Later, reattach from any device
tmux attach-session -t work

Multi-Window Monitoring

# Window 1: Claude Code task
tmux new-window -t work
cd ~/project && claude

# Window 2: Build logs
tmux new-window -t work
tail -f build.log

# Window 3: Tests
tmux new-window -t work
go test -v ./...

# Share the main Muxile session, cycle through windows on mobile

Combining with SSH + Tailscale

For full remote access from anywhere:

# On remote device
tailscale up
ssh user@<your-tailscale-ip>

# Attach to your session
tmux attach-session -t work

Troubleshooting

Muxile Link Not Appearing

Check if qrencode is installed:

which qrencode
# If missing:
brew install qrencode  # macOS
sudo apt install qrencode  # Linux

Session Not Found

Verify tmux session exists:

tmux ls
# Create if missing:
tmux new-session -s claude

Connection Drops (SSH)

Use mosh instead for unstable networks:

brew install mosh
mosh user@hostname

WebSocket Timeout

Muxile uses Cloudflare Workers with a 5-minute timeout. For longer sessions:

  • Use SSH + tmux attach for unlimited time
  • Reconnect to Muxile QR code periodically

Best Practices

  1. Name your sessions clearly: tmux new-session -s claude-alerts-feature
  2. Use meaningful tmux windows: Separate Claude Code, logs, and tests
  3. Share carefully: Muxile links expose your terminal—use with trusted teammates only
  4. Monitor Discord hooks: Check that notifications are reaching your team channel
  5. Detach cleanly: Use Ctrl+b then d rather than killing terminals

Links & References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment