https://github.com/JessyTsui/Claude-Code-Remote
https://github.com/JessyTsui/Claude-Code-Remote
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/JessyTsui/Claude-Code-Remote
- Owner: JessyTsui
- License: mit
- Created: 2025-07-12T12:37:50.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2025-07-27T18:21:54.000Z (2 months ago)
- Last Synced: 2025-07-27T19:26:04.552Z (2 months ago)
- Language: JavaScript
- Size: 3.49 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude - Claude-Code-Remote - 688โญ - Control via email/discord/telegram (Claude Code Ecosystem / Remote Control & Communication)
- awesome - JessyTsui/Claude-Code-Remote - Control Claude Code remotely via emailใdiscordใtelegram. Start tasks locally, receive notifications when Claude completes them, and send new commands by simply replying to emails. (JavaScript)
- awesome-claude-code - **Claude-Code-Remote**
README
# Claude Code Remote
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.
### ๐ฅ Watch Demo Video
> ๐ฆ Follow [@Jiaxi_Cui](https://x.com/Jiaxi_Cui) for updates and AI development insights
## โจ Features
- **๐ง 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
```bash
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
cd Claude-Code-Remote
npm install
```
### 2. Configure Email
```bash
# Copy example config
cp .env.example .env
# Edit with your email credentials
nano .env
```
**Required settings:**
```env
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
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=/your/path/to/Claude-Code-Remote/src/data/session-map.json
```
๐ **Gmail users**: Use [App Passwords](https://myaccount.google.com/security), not your regular password.
### 3. Configure Claude Code Hooks
Add to `~/.claude/settings.json`:
```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
}]
}]
}
}
```
### 4. Start
```bash
# 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
```
## ๐ฎ How It Works
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](./HOW_TO_USE_EMAIL_REPLY.md) | [ไธญๆ](./HOW_TO_USE_EMAIL_REPLY_ZH.md)
### 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.
```
**๐จ Your reply:**
```
Please optimize the performance and fix any bugs you find.
```
**โก Result:** Your command automatically executes in Claude!
## ๐ก Use Cases
- **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
```bash
# 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
```
## ๐ Troubleshooting
**Email not working?**
```bash
node claude-remote.js test # Test email setup
```
**Commands not injecting?**
```bash
tmux list-sessions # Check if session exists
grep ALLOWED_SENDERS .env # Verify sender whitelist
```
**Hooks not triggering?**
```bash
node claude-remote.js notify --type completed # Test manually
```
## ๐ก๏ธ Security
- โ
**Sender Whitelist**: Only authorized emails can send commands
- โ
**Session Isolation**: Each token controls only its specific session
- โ
**Auto Expiration**: Sessions timeout automatically
## ๐ค Contributing
Found a bug or have a feature request?
- ๐ **Issues**: [GitHub Issues](https://github.com/JessyTsui/Claude-Code-Remote/issues)
- ๐ฆ **Updates**: Follow [@Jiaxi_Cui](https://x.com/Jiaxi_Cui) on Twitter
- ๐ฌ **Discussions**: Share your use cases and improvements
## ๐ License
MIT License - Feel free to use and modify!
---
**๐ Make Claude Code truly remote and accessible from anywhere!**
## โญ Star History
[](https://star-history.com/#JessyTsui/Claude-Code-Remote&Date)
โญ **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!