Claude Code Remote - 远程邮件控制系统

一个强大的 Claude Code 远程控制工具，让你可以通过邮件回复来远程操控 Claude Code，实现真正的无人值守智能编程助手。

🌟 核心功能

• 📧 智能邮件通知 - Claude 完成任务时自动发送邮件通知
• 🔄 邮件回复控制 - 回复邮件内容自动注入到 Claude Code 中执行
• 📱 完全远程操作 - 在任何地方通过邮件控制你的 Claude Code
• 🛡️ 安全可靠 - 白名单机制确保只有授权用户可以发送命令
• 📋 多行支持 - 支持复杂的多行命令和格式化内容

🚀 新手完整教程

📋 前置要求

在开始之前，请确保你的系统满足以下要求：

• ✅ macOS (推荐) 或 Linux
• ✅ Node.js 14+
• ✅ Claude Code 已安装并可正常使用
• ✅ tmux 已安装 (brew install tmux)
• ✅ 邮箱账号 (Gmail、Outlook 或其他 SMTP/IMAP 支持的邮箱)

🎯 第一步：快速体验（5分钟）

# 1. 克隆项目
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote

# 2. 安装依赖
npm install

# 3. 测试基本功能
node taskping.js --help
node taskping.js status
node taskping.js test

如果看到桌面通知弹出，说明基础功能正常！

📧 第二步：配置邮件（10分钟）

2.1 创建邮件配置文件

# 在项目根目录创建 .env 文件
touch .env

2.2 编辑 .env 文件

将以下内容复制到 .env 文件中，并替换为你的邮箱信息：

# ===== SMTP 发送邮件配置 =====
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# ===== IMAP 接收邮件配置 =====  
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
IMAP_USER=your-email@gmail.com
IMAP_PASS=your-app-password

# ===== 邮件路由配置 =====
EMAIL_TO=your-notification-email@gmail.com
ALLOWED_SENDERS=your-notification-email@gmail.com

# ===== 系统配置 =====
SESSION_MAP_PATH=/Users/your-username/path/to/Claude-Code-Remote/src/data/session-map.json
INJECTION_MODE=pty
CLAUDE_CLI_PATH=claude
LOG_LEVEL=info

2.3 常见邮箱配置

Gmail:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
IMAP_HOST=imap.gmail.com
IMAP_PORT=993

Outlook/Hotmail:

SMTP_HOST=smtp-mail.outlook.com
SMTP_PORT=587
IMAP_HOST=outlook.office365.com
IMAP_PORT=993

📌 重要：Gmail 用户必须使用应用密码

1. 访问 Google 账户设置
2. 启用两步验证
3. 生成应用密码
4. 在 .env 文件中使用应用密码，而不是账户密码

2.4 测试邮件配置

# 测试邮件发送功能
node taskping.js test

如果收到测试邮件，说明邮件配置成功！

⚙️ 第三步：配置 Claude Code 钩子（5分钟）

3.1 找到 Claude Code 配置文件

# Claude Code 配置文件位置
~/.claude/settings.json

3.2 编辑配置文件

将以下内容添加到 ~/.claude/settings.json：

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

🔥 重要：替换路径

• 将 /Users/your-username/path/to/Claude-Code-Remote 替换为你的实际项目路径
• 可以用 pwd 命令获取当前目录的完整路径

🎮 第四步：开始使用（马上开始！）

4.1 启动邮件监听服务

# 在项目目录启动邮件监听
npm run relay:pty

你会看到类似输出：

🚀 Starting TaskPing PTY Relay service...
📧 IMAP server: imap.gmail.com
👤 Email account: your-email@gmail.com
🔒 Whitelist senders: your-email@gmail.com

4.2 创建 Claude Code 会话

在新的终端窗口中：

# 创建一个新的 Claude Code 会话
tmux new-session -d -s my-project
tmux attach -t my-project

# 在 tmux 会话中启动 Claude Code
claude

4.3 开始远程控制

1. 与 Claude 对话：

   > 请帮我分析这个项目的结构
   

2. 接收邮件通知： Claude 完成任务后，你会收到邮件，内容类似：

   Subject: TaskPing 任务完成通知 [#ABC123]
   
   Claude has completed your task:
   "请帮我分析这个项目的结构"
   
   [Claude的完整回复内容...]
   
   Reply to this email to send new commands.
   Token: ABC123
   

3. 回复邮件控制： 直接回复邮件：

   请继续优化代码性能
   

4. 命令自动执行： 你的回复会自动注入到 Claude Code 中并执行！

🎯 高级使用技巧

📝 多行命令支持

你可以在邮件回复中使用复杂的多行命令：

请按以下步骤进行：

1. 分析当前代码结构
2. 识别性能瓶颈
3. 提供具体的优化建议

详细要求：
- 重点关注数据库查询优化
- 检查内存使用情况
- 提供代码示例

谢谢！

🔄 多项目管理

# 项目 A
tmux new-session -d -s project-a
tmux send-keys -t project-a "cd /path/to/project-a && claude" Enter

# 项目 B  
tmux new-session -d -s project-b
tmux send-keys -t project-b "cd /path/to/project-b && claude" Enter

每个会话都会有独立的邮件 Token，你可以同时控制多个项目！

📊 监控和管理

# 查看系统状态
node taskping.js status

# 查看待处理命令
node taskping.js commands list

# 查看活跃会话
tmux list-sessions

# 清理命令队列
node taskping.js commands clear

🎬 使用场景示例

场景1：代码审查自动化

1. 在办公室启动代码审查任务
2. 回家路上收到完成邮件："发现3个问题"
3. 回复邮件："请修复第一个问题"
4. Claude 自动开始修复
5. 通过邮件持续跟进进度

场景2：长时间项目监控

1. 启动大型重构任务
2. Claude 分模块完成工作
3. 每个阶段完成时收到邮件通知
4. 通过邮件回复指导下一步工作

场景3：多地协作开发

1. 在不同地点都能通过邮件控制同一个 Claude Code 实例
2. 无需 VPN 或复杂的远程桌面设置
3. 只需要邮箱就能远程编程

🔧 系统管理命令

# 邮件监听服务
npm run relay:pty              # 启动邮件监听（前台运行）

# 系统状态检查
node taskping.js status        # 查看整体状态
node taskping.js test          # 测试所有功能

# 命令队列管理  
node taskping.js commands list    # 查看待处理命令
node taskping.js commands status  # 查看处理状态
node taskping.js commands clear   # 清空命令队列

# 会话管理
tmux list-sessions             # 查看所有会话
tmux attach -t session-name    # 连接到会话
tmux kill-session -t session-name  # 删除会话

🔍 故障排除

❓ 常见问题

Q: npm install 失败

# 检查 Node.js 版本
node -v  # 需要 14+

# 清理并重新安装
rm -rf node_modules package-lock.json
npm install

Q: 邮件发送失败

# 检查邮件配置
node taskping.js status
node taskping.js test

# 常见问题：
# 1. Gmail 用户必须使用应用密码
# 2. 检查 SMTP/IMAP 端口和安全设置
# 3. 确认网络可以访问邮件服务器

Q: 命令注入失败

# 检查 tmux 会话
tmux list-sessions

# 检查会话内容
tmux capture-pane -t session-name -p

# 检查允许的发件人
grep ALLOWED_SENDERS .env

Q: Claude hooks 不触发

# 验证 hooks 配置
cat ~/.claude/settings.json

# 手动测试 hook
node taskping.js notify --type completed

# 检查文件路径是否正确

Q: 收不到邮件通知

# 检查 SMTP 配置
node taskping.js test

# 检查垃圾邮件文件夹
# 确认邮件地址配置正确

🐛 调试模式

# 启用详细日志
LOG_LEVEL=debug npm run relay:pty

# 查看会话映射
cat src/data/session-map.json

# 查看处理过的邮件
cat src/data/processed-messages.json

🛡️ 安全说明

• ✅ 白名单机制 - 只有 ALLOWED_SENDERS 中的邮箱可以发送命令
• ✅ 会话隔离 - 每个 Token 只能控制对应的会话
• ✅ 命令验证 - 自动过滤危险命令
• ✅ 超时机制 - 会话有过期时间，自动清理

🤝 贡献和支持

报告问题

如果遇到问题，请在 GitHub Issues 中报告。

功能请求

欢迎提交新功能建议和改进意见。

贡献代码

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 发起 Pull Request

📄 许可证

本项目采用 MIT 许可证。

---

🚀 让 Claude Code 无处不在，随时随地智能编程！

如果这个项目对你有帮助，请给我们一个 ⭐ Star！