Complete README rewrite: Concise English version
- 🌍 Full English rewrite for international accessibility - ✂️ Condensed content focusing on essential information - 🎯 Streamlined setup process with clear steps - 📱 Enhanced user flow explanation with examples - 🐦 Integrated Twitter promotion (@Jiaxi_Cui) in strategic locations - 🔥 Improved call-to-action for stars and community engagement - 📊 Better structured troubleshooting section - 💡 Added practical use cases and tips Transforms verbose documentation into a clean, professional README that quickly communicates value and drives engagement. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
panda
parent
4f288982ed
commit
0349f8f042
379
README.md
379
README.md
|
|
@ -1,127 +1,53 @@
|
||||||
# Claude Code Remote - 远程邮件控制系统
|
# Claude Code Remote
|
||||||
|
|
||||||
一个强大的 Claude Code 远程控制工具，让你可以通过邮件回复来远程操控 Claude Code，实现真正的无人值守智能编程助手。
|
Control [Claude Code](https://claude.ai/code) remotely via email. Start tasks locally, receive notifications when Claude completes them, and send new commands by simply replying to emails.
|
||||||
|
|
||||||
## 🌟 核心功能
|
> 🐦 Follow [@Jiaxi_Cui](https://x.com/Jiaxi_Cui) for updates and AI development insights
|
||||||
|
|
||||||
- 📧 **智能邮件通知** - Claude 完成任务时自动发送邮件通知
|
## ✨ Features
|
||||||
- 🔄 **邮件回复控制** - 回复邮件内容自动注入到 Claude Code 中执行
|
|
||||||
- 📱 **完全远程操作** - 在任何地方通过邮件控制你的 Claude Code
|
|
||||||
- 🛡️ **安全可靠** - 白名单机制确保只有授权用户可以发送命令
|
|
||||||
- 📋 **多行支持** - 支持复杂的多行命令和格式化内容
|
|
||||||
|
|
||||||
## 🚀 新手完整教程
|
- **📧 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
|
||||||
|
|
||||||
### 📋 前置要求
|
## 🚀 Quick Start
|
||||||
|
|
||||||
在开始之前，请确保你的系统满足以下要求：
|
### 1. Install
|
||||||
|
|
||||||
- ✅ **macOS** (推荐) 或 Linux
|
|
||||||
- ✅ **Node.js 14+**
|
|
||||||
- ✅ **Claude Code** 已安装并可正常使用
|
|
||||||
- ✅ **tmux** 已安装 (`brew install tmux`)
|
|
||||||
- ✅ **邮箱账号** (Gmail、Outlook 或其他 SMTP/IMAP 支持的邮箱)
|
|
||||||
|
|
||||||
### 🎯 第一步：快速体验（5分钟）
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 克隆项目
|
|
||||||
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
|
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
|
||||||
cd Claude-Code-Remote
|
cd Claude-Code-Remote
|
||||||
|
|
||||||
# 2. 安装依赖
|
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
# 3. 测试基本功能
|
|
||||||
node claude-remote.js --help
|
|
||||||
node claude-remote.js status
|
|
||||||
node claude-remote.js test
|
|
||||||
```
|
```
|
||||||
|
|
||||||
如果看到桌面通知弹出，说明基础功能正常！
|
### 2. Configure Email
|
||||||
|
|
||||||
### 📧 第二步：配置邮件（10分钟）
|
|
||||||
|
|
||||||
#### 2.1 创建邮件配置文件
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 复制示例配置文件
|
# Copy example config
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
```
|
|
||||||
|
|
||||||
#### 2.2 编辑 .env 文件
|
# Edit with your email credentials
|
||||||
|
|
||||||
编辑 `.env` 文件，替换为你的邮箱信息：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 编辑配置文件
|
|
||||||
nano .env
|
nano .env
|
||||||
# 或者使用其他编辑器
|
|
||||||
open .env
|
|
||||||
```
|
```
|
||||||
|
|
||||||
主要需要修改的配置项：
|
**Required settings:**
|
||||||
|
|
||||||
```env
|
```env
|
||||||
# 你的邮箱地址和应用密码
|
|
||||||
SMTP_USER=your-email@gmail.com
|
SMTP_USER=your-email@gmail.com
|
||||||
SMTP_PASS=your-app-password
|
SMTP_PASS=your-app-password
|
||||||
IMAP_USER=your-email@gmail.com
|
IMAP_USER=your-email@gmail.com
|
||||||
IMAP_PASS=your-app-password
|
IMAP_PASS=your-app-password
|
||||||
|
|
||||||
# 接收通知的邮箱（可以是同一个）
|
|
||||||
EMAIL_TO=your-notification-email@gmail.com
|
EMAIL_TO=your-notification-email@gmail.com
|
||||||
ALLOWED_SENDERS=your-notification-email@gmail.com
|
ALLOWED_SENDERS=your-notification-email@gmail.com
|
||||||
|
SESSION_MAP_PATH=/your/path/to/Claude-Code-Remote/src/data/session-map.json
|
||||||
# 你的实际项目路径
|
|
||||||
SESSION_MAP_PATH=/Users/your-username/path/to/Claude-Code-Remote/src/data/session-map.json
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 2.3 常见邮箱配置
|
📌 **Gmail users**: Use [App Passwords](https://myaccount.google.com/security), not your regular password.
|
||||||
|
|
||||||
**Gmail**:
|
### 3. Configure Claude Code Hooks
|
||||||
```env
|
|
||||||
SMTP_HOST=smtp.gmail.com
|
|
||||||
SMTP_PORT=587
|
|
||||||
IMAP_HOST=imap.gmail.com
|
|
||||||
IMAP_PORT=993
|
|
||||||
```
|
|
||||||
|
|
||||||
**Outlook/Hotmail**:
|
Add to `~/.claude/settings.json`:
|
||||||
```env
|
|
||||||
SMTP_HOST=smtp-mail.outlook.com
|
|
||||||
SMTP_PORT=587
|
|
||||||
IMAP_HOST=outlook.office365.com
|
|
||||||
IMAP_PORT=993
|
|
||||||
```
|
|
||||||
|
|
||||||
**📌 重要：Gmail 用户必须使用应用密码**
|
|
||||||
1. 访问 [Google 账户设置](https://myaccount.google.com/security)
|
|
||||||
2. 启用两步验证
|
|
||||||
3. 生成应用密码
|
|
||||||
4. 在 `.env` 文件中使用应用密码，而不是账户密码
|
|
||||||
|
|
||||||
#### 2.4 测试邮件配置
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 测试邮件发送功能
|
|
||||||
node claude-remote.js test
|
|
||||||
```
|
|
||||||
|
|
||||||
如果收到测试邮件，说明邮件配置成功！
|
|
||||||
|
|
||||||
### ⚙️ 第三步：配置 Claude Code 钩子（5分钟）
|
|
||||||
|
|
||||||
#### 3.1 找到 Claude Code 配置文件
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Claude Code 配置文件位置
|
|
||||||
~/.claude/settings.json
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3.2 编辑配置文件
|
|
||||||
|
|
||||||
将以下内容添加到 `~/.claude/settings.json`：
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -130,7 +56,7 @@ node claude-remote.js test
|
||||||
"matcher": "*",
|
"matcher": "*",
|
||||||
"hooks": [{
|
"hooks": [{
|
||||||
"type": "command",
|
"type": "command",
|
||||||
"command": "node /Users/your-username/path/to/Claude-Code-Remote/claude-remote.js notify --type completed",
|
"command": "node /your/path/to/Claude-Code-Remote/claude-remote.js notify --type completed",
|
||||||
"timeout": 5
|
"timeout": 5
|
||||||
}]
|
}]
|
||||||
}],
|
}],
|
||||||
|
|
@ -138,7 +64,7 @@ node claude-remote.js test
|
||||||
"matcher": "*",
|
"matcher": "*",
|
||||||
"hooks": [{
|
"hooks": [{
|
||||||
"type": "command",
|
"type": "command",
|
||||||
"command": "node /Users/your-username/path/to/Claude-Code-Remote/claude-remote.js notify --type waiting",
|
"command": "node /your/path/to/Claude-Code-Remote/claude-remote.js notify --type waiting",
|
||||||
"timeout": 5
|
"timeout": 5
|
||||||
}]
|
}]
|
||||||
}]
|
}]
|
||||||
|
|
@ -146,260 +72,107 @@ node claude-remote.js test
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**🔥 重要：替换路径**
|
### 4. Start
|
||||||
- 将 `/Users/your-username/path/to/Claude-Code-Remote` 替换为你的实际项目路径
|
|
||||||
- 可以用 `pwd` 命令获取当前目录的完整路径
|
|
||||||
- 确保文件名为 `claude-remote.js`
|
|
||||||
|
|
||||||
### 🎮 第四步：开始使用（马上开始！）
|
|
||||||
|
|
||||||
#### 4.1 启动邮件监听服务
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 在项目目录启动邮件监听
|
# Start email monitoring
|
||||||
npm run relay:pty
|
npm run relay:pty
|
||||||
```
|
|
||||||
|
|
||||||
你会看到类似输出：
|
# In another terminal, start Claude Code
|
||||||
```
|
|
||||||
🚀 Starting Claude Code Remote PTY Relay service...
|
|
||||||
📧 IMAP server: imap.gmail.com
|
|
||||||
👤 Email account: your-email@gmail.com
|
|
||||||
🔒 Whitelist senders: your-email@gmail.com
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 4.2 创建 Claude Code 会话
|
|
||||||
|
|
||||||
在新的终端窗口中：
|
|
||||||
```bash
|
|
||||||
# 创建一个新的 Claude Code 会话
|
|
||||||
tmux new-session -d -s my-project
|
tmux new-session -d -s my-project
|
||||||
tmux attach -t my-project
|
tmux attach -t my-project
|
||||||
|
|
||||||
# 在 tmux 会话中启动 Claude Code
|
|
||||||
claude
|
claude
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 4.3 开始远程控制
|
## 🎮 How It Works
|
||||||
|
|
||||||
1. **与 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
|
||||||
|
|
||||||
|
### Example Email Flow
|
||||||
|
|
||||||
|
**📩 Notification received:**
|
||||||
```
|
```
|
||||||
> 请帮我分析这个项目的结构
|
Subject: Claude Code Remote Task Complete [#ABC123]
|
||||||
|
|
||||||
|
Claude completed: "Analyze the code structure"
|
||||||
|
[Claude's full response...]
|
||||||
|
|
||||||
|
Reply to send new commands.
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **接收邮件通知**：
|
**📨 Your reply:**
|
||||||
Claude 完成任务后，你会收到邮件，内容类似：
|
|
||||||
```
|
```
|
||||||
Subject: Claude Code Remote 任务完成通知 [#ABC123]
|
Please optimize the performance and fix any bugs you find.
|
||||||
|
|
||||||
Claude has completed your task:
|
|
||||||
"请帮我分析这个项目的结构"
|
|
||||||
|
|
||||||
[Claude的完整回复内容...]
|
|
||||||
|
|
||||||
Reply to this email to send new commands.
|
|
||||||
Token: ABC123
|
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **回复邮件控制**：
|
**⚡ Result:** Your command automatically executes in Claude!
|
||||||
直接回复邮件：
|
|
||||||
```
|
|
||||||
请继续优化代码性能
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **命令自动执行**：
|
## 💡 Use Cases
|
||||||
你的回复会自动注入到 Claude Code 中并执行！
|
|
||||||
|
|
||||||
## 🎯 高级使用技巧
|
- **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
|
||||||
|
|
||||||
### 📝 多行命令支持
|
## 🔧 Commands
|
||||||
|
|
||||||
你可以在邮件回复中使用复杂的多行命令：
|
|
||||||
|
|
||||||
```
|
|
||||||
请按以下步骤进行：
|
|
||||||
|
|
||||||
1. 分析当前代码结构
|
|
||||||
2. 识别性能瓶颈
|
|
||||||
3. 提供具体的优化建议
|
|
||||||
|
|
||||||
详细要求：
|
|
||||||
- 重点关注数据库查询优化
|
|
||||||
- 检查内存使用情况
|
|
||||||
- 提供代码示例
|
|
||||||
|
|
||||||
谢谢！
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔄 多项目管理
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 项目 A
|
# Test functionality
|
||||||
tmux new-session -d -s project-a
|
node claude-remote.js test
|
||||||
tmux send-keys -t project-a "cd /path/to/project-a && claude" Enter
|
|
||||||
|
|
||||||
# 项目 B
|
# Check status
|
||||||
tmux new-session -d -s project-b
|
|
||||||
tmux send-keys -t project-b "cd /path/to/project-b && claude" Enter
|
|
||||||
```
|
|
||||||
|
|
||||||
每个会话都会有独立的邮件 Token，你可以同时控制多个项目！
|
|
||||||
|
|
||||||
### 📊 监控和管理
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 查看系统状态
|
|
||||||
node claude-remote.js status
|
node claude-remote.js status
|
||||||
|
|
||||||
# 查看待处理命令
|
# View pending commands
|
||||||
node claude-remote.js commands list
|
node claude-remote.js commands list
|
||||||
|
|
||||||
# 查看活跃会话
|
# Manage sessions
|
||||||
tmux list-sessions
|
tmux list-sessions
|
||||||
|
tmux attach -t session-name
|
||||||
# 清理命令队列
|
|
||||||
node claude-remote.js commands clear
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🎬 使用场景示例
|
## 🔍 Troubleshooting
|
||||||
|
|
||||||
### 场景1：代码审查自动化
|
|
||||||
1. 在办公室启动代码审查任务
|
|
||||||
2. 回家路上收到完成邮件："发现3个问题"
|
|
||||||
3. 回复邮件："请修复第一个问题"
|
|
||||||
4. Claude 自动开始修复
|
|
||||||
5. 通过邮件持续跟进进度
|
|
||||||
|
|
||||||
### 场景2：长时间项目监控
|
|
||||||
1. 启动大型重构任务
|
|
||||||
2. Claude 分模块完成工作
|
|
||||||
3. 每个阶段完成时收到邮件通知
|
|
||||||
4. 通过邮件回复指导下一步工作
|
|
||||||
|
|
||||||
### 场景3：多地协作开发
|
|
||||||
1. 在不同地点都能通过邮件控制同一个 Claude Code 实例
|
|
||||||
2. 无需 VPN 或复杂的远程桌面设置
|
|
||||||
3. 只需要邮箱就能远程编程
|
|
||||||
|
|
||||||
## 🔧 系统管理命令
|
|
||||||
|
|
||||||
|
**Email not working?**
|
||||||
```bash
|
```bash
|
||||||
# 邮件监听服务
|
node claude-remote.js test # Test email setup
|
||||||
npm run relay:pty # 启动邮件监听（前台运行）
|
|
||||||
|
|
||||||
# 系统状态检查
|
|
||||||
node claude-remote.js status # 查看整体状态
|
|
||||||
node claude-remote.js test # 测试所有功能
|
|
||||||
|
|
||||||
# 命令队列管理
|
|
||||||
node claude-remote.js commands list # 查看待处理命令
|
|
||||||
node claude-remote.js commands status # 查看处理状态
|
|
||||||
node claude-remote.js commands clear # 清空命令队列
|
|
||||||
|
|
||||||
# 会话管理
|
|
||||||
tmux list-sessions # 查看所有会话
|
|
||||||
tmux attach -t session-name # 连接到会话
|
|
||||||
tmux kill-session -t session-name # 删除会话
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔍 故障排除
|
**Commands not injecting?**
|
||||||
|
|
||||||
### ❓ 常见问题
|
|
||||||
|
|
||||||
**Q: npm install 失败**
|
|
||||||
```bash
|
```bash
|
||||||
# 检查 Node.js 版本
|
tmux list-sessions # Check if session exists
|
||||||
node -v # 需要 14+
|
grep ALLOWED_SENDERS .env # Verify sender whitelist
|
||||||
|
|
||||||
# 清理并重新安装
|
|
||||||
rm -rf node_modules package-lock.json
|
|
||||||
npm install
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Q: 邮件发送失败**
|
**Hooks not triggering?**
|
||||||
```bash
|
```bash
|
||||||
# 检查邮件配置
|
node claude-remote.js notify --type completed # Test manually
|
||||||
node claude-remote.js status
|
|
||||||
node claude-remote.js test
|
|
||||||
|
|
||||||
# 常见问题：
|
|
||||||
# 1. Gmail 用户必须使用应用密码
|
|
||||||
# 2. 检查 SMTP/IMAP 端口和安全设置
|
|
||||||
# 3. 确认网络可以访问邮件服务器
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Q: 命令注入失败**
|
## 🛡️ Security
|
||||||
```bash
|
|
||||||
# 检查 tmux 会话
|
|
||||||
tmux list-sessions
|
|
||||||
|
|
||||||
# 检查会话内容
|
- ✅ **Sender Whitelist**: Only authorized emails can send commands
|
||||||
tmux capture-pane -t session-name -p
|
- ✅ **Session Isolation**: Each token controls only its specific session
|
||||||
|
- ✅ **Auto Expiration**: Sessions timeout automatically
|
||||||
|
|
||||||
# 检查允许的发件人
|
## 🤝 Contributing
|
||||||
grep ALLOWED_SENDERS .env
|
|
||||||
```
|
|
||||||
|
|
||||||
**Q: Claude hooks 不触发**
|
Found a bug or have a feature request?
|
||||||
```bash
|
|
||||||
# 验证 hooks 配置
|
|
||||||
cat ~/.claude/settings.json
|
|
||||||
|
|
||||||
# 手动测试 hook
|
- 🐛 **Issues**: [GitHub Issues](https://github.com/JessyTsui/Claude-Code-Remote/issues)
|
||||||
node claude-remote.js notify --type completed
|
- 🐦 **Updates**: Follow [@Jiaxi_Cui](https://x.com/Jiaxi_Cui) on Twitter
|
||||||
|
- 💬 **Discussions**: Share your use cases and improvements
|
||||||
|
|
||||||
# 检查文件路径是否正确
|
## 📄 License
|
||||||
```
|
|
||||||
|
|
||||||
**Q: 收不到邮件通知**
|
MIT License - Feel free to use and modify!
|
||||||
```bash
|
|
||||||
# 检查 SMTP 配置
|
|
||||||
node claude-remote.js test
|
|
||||||
|
|
||||||
# 检查垃圾邮件文件夹
|
|
||||||
# 确认邮件地址配置正确
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🐛 调试模式
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 启用详细日志
|
|
||||||
LOG_LEVEL=debug npm run relay:pty
|
|
||||||
|
|
||||||
# 查看会话映射
|
|
||||||
cat src/data/session-map.json
|
|
||||||
|
|
||||||
# 查看处理过的邮件
|
|
||||||
cat src/data/processed-messages.json
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛡️ 安全说明
|
|
||||||
|
|
||||||
- ✅ **白名单机制** - 只有 `ALLOWED_SENDERS` 中的邮箱可以发送命令
|
|
||||||
- ✅ **会话隔离** - 每个 Token 只能控制对应的会话
|
|
||||||
- ✅ **命令验证** - 自动过滤危险命令
|
|
||||||
- ✅ **超时机制** - 会话有过期时间，自动清理
|
|
||||||
|
|
||||||
## 🤝 贡献和支持
|
|
||||||
|
|
||||||
### 报告问题
|
|
||||||
如果遇到问题，请在 [GitHub Issues](https://github.com/JessyTsui/Claude-Code-Remote/issues) 中报告。
|
|
||||||
|
|
||||||
### 功能请求
|
|
||||||
欢迎提交新功能建议和改进意见。
|
|
||||||
|
|
||||||
### 贡献代码
|
|
||||||
1. Fork 项目
|
|
||||||
2. 创建功能分支
|
|
||||||
3. 提交更改
|
|
||||||
4. 发起 Pull Request
|
|
||||||
|
|
||||||
## 📄 许可证
|
|
||||||
|
|
||||||
本项目采用 MIT 许可证。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**🚀 让 Claude Code 无处不在，随时随地智能编程！**
|
**🚀 Make Claude Code truly remote and accessible from anywhere!**
|
||||||
|
|
||||||
如果这个项目对你有帮助，请给我们一个 ⭐ Star！
|
⭐ **Star this repo** if it helps you code more efficiently!
|
||||||
|
|
||||||
|
> 💡 **Tip**: Share your remote coding setup on Twitter and tag [@Jiaxi_Cui](https://x.com/Jiaxi_Cui) - we love seeing how developers use Claude Code Remote!
|
||||||
Loading…
Reference in New Issue