Control Claude Code remotely via email. Start tasks locally, receive notifications when Claude completes them, and send new commands by simply replying to emails.

🎥 Watch Demo Video

🐦 Follow @Jiaxi_Cui for updates and AI development insights

• 📧 Email Notifications: Get notified when Claude completes tasks
• 🔄 Email Control: Reply to emails to send new commands to Claude
• 📱 Remote Access: Control Claude from anywhere with just email
• 🔒 Secure: Whitelist-based sender verification
• 📋 Multi-line Support: Send complex commands with formatting

git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote
npm install

# Copy example config
cp .env.example .env

# Edit with your email credentials
nano .env

Required settings:

SMTP_USER=[email protected]
SMTP_PASS=your-app-password
IMAP_USER=[email protected]  
IMAP_PASS=your-app-password
EMAIL_TO=[email protected]
ALLOWED_SENDERS=[email protected]
SESSION_MAP_PATH=/your/path/to/Claude-Code-Remote/src/data/session-map.json

📌 Gmail users: Use App Passwords, not your regular password.

Add to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node /your/path/to/Claude-Code-Remote/claude-remote.js notify --type completed",
        "timeout": 5
      }]
    }],
    "SubagentStop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node /your/path/to/Claude-Code-Remote/claude-remote.js notify --type waiting",
        "timeout": 5
      }]
    }]
  }
}

# Start email monitoring
npm run relay:pty

# In another terminal, start Claude Code
tmux new-session -d -s my-project
tmux attach -t my-project
claude

1. Use Claude normally in tmux session
2. Get email notifications when Claude completes tasks
3. Reply to emails with new commands
4. Commands execute automatically in Claude

📖 Detailed Email Reply Guide: English | 中文

📩 Notification received:

Subject: Claude Code Remote Task Complete [#ABC123]

Claude completed: "Analyze the code structure"
[Claude's full response...]

Reply to send new commands.

📨 Your reply:

Please optimize the performance and fix any bugs you find.

⚡ Result: Your command automatically executes in Claude!

• Remote Code Reviews: Start reviews at office, continue from home via email
• Long-running Tasks: Monitor progress and guide next steps remotely
• Multi-location Development: Control Claude from anywhere without VPN

# Test functionality
node claude-remote.js test

# Check status
node claude-remote.js status

# View pending commands
node claude-remote.js commands list

# Manage sessions
tmux list-sessions
tmux attach -t session-name

Email not working?

node claude-remote.js test  # Test email setup

Commands not injecting?

tmux list-sessions  # Check if session exists
grep ALLOWED_SENDERS .env  # Verify sender whitelist

Hooks not triggering?

node claude-remote.js notify --type completed  # Test manually

• ✅ Sender Whitelist: Only authorized emails can send commands
• ✅ Session Isolation: Each token controls only its specific session
• ✅ Auto Expiration: Sessions timeout automatically

Found a bug or have a feature request?

• 🐛 Issues: GitHub Issues
• 🐦 Updates: Follow @Jiaxi_Cui on Twitter
• 💬 Discussions: Share your use cases and improvements

MIT License - Feel free to use and modify!

🚀 Make Claude Code truly remote and accessible from anywhere!

⭐ Star this repo if it helps you code more efficiently!

💡 Tip: Share your remote coding setup on Twitter and tag @Jiaxi_Cui - we love seeing how developers use Claude Code Remote!