Claude Code Remote: Control Claude Code Anywhere via Email

Have you ever wished you could keep working with Claude Code even when you’re away from your computer? Maybe you started a coding task at the office, had to leave for a meeting, and wanted to check progress or send new instructions without rushing back. That’s exactly what Claude Code Remote solves. This tool lets you control Claude Code remotely using just email—start tasks, get notified when they’re done, and send new commands by replying to messages. It’s like having a remote control for your AI coding assistant, right in your inbox.

What is Claude Code Remote?

Claude Code Remote is a tool designed to make Claude Code accessible from anywhere, no matter where you are. Instead of being tied to your computer, you can interact with Claude through email. Here’s the simple idea: you set up the tool once, and then you can start tasks on your local machine, get emails when Claude finishes, and even send new commands by replying to those emails. It’s perfect for anyone who needs flexibility in their workflow—whether you’re moving between meetings, working from different locations, or just want to stay connected to your coding projects without being glued to your screen.

Key Features

Let’s break down what makes Claude Code Remote useful. Each feature is designed to make remote control of Claude Code simple and effective:

1. Email Notifications: Stay in the Loop

The first thing you’ll notice is how easy it is to track your tasks. When Claude finishes a task—whether it’s analyzing code, writing a function, or explaining a concept—you’ll get an email notification right away. No more checking your computer repeatedly to see if the task is done. The email includes all the details: what the task was, Claude’s full response, and a note that you can reply with your next command. It’s like having a personal update system that fits into your existing email routine.

2. Email Control: Reply to Send New Commands

The real magic is in the ability to send new commands by replying to those notifications. You don’t need any special apps or tools—just use your regular email. If Claude finishes analyzing a script and you want it to refactor a part of it, simply reply to the notification email with your instruction. The tool will pick up your message, send it to Claude, and then notify you again when that new task is complete. It’s a seamless loop that keeps your work moving forward, even when you’re not at your desk.

3. Remote Access: Control from Anywhere

Whether you’re at home, on the go, or in a different office, as long as you can check your email, you can control Claude Code. Forgot to start a task before leaving work? If you set up Claude Code Remote in advance, you can trigger tasks and manage them from your phone, tablet, or any device with email access. It breaks down the barrier between your physical location and your coding projects.

4. Secure: Only Authorized Users Can Send Commands

Security is a priority here. Claude Code Remote uses a whitelist system, which means only emails you approve can send commands. You set up a list of allowed senders in the configuration, so you don’t have to worry about unauthorized people accessing your Claude sessions. This keeps your work safe and ensures only trusted users can interact with your projects.

5. Multi-line Support: Send Complex Instructions

Coding tasks often require detailed, multi-step instructions—and Claude Code Remote handles that easily. You can write long, formatted commands in your email replies. For example, you could ask Claude to “First analyze the login flow, then fix the error handling in the password reset function, and finally add comments to the main authentication module.” The tool will pass along the entire message, so you don’t have to simplify your instructions or send multiple emails.

Recent Updates (Changelog)

The tool is constantly improving, with updates based on user feedback and needs. Here’s what’s new:

January 2025

January 15, 2025: A new terminal-style design for email notifications was added. This makes the notifications easier to read, with a layout that looks more like the Claude Code interface you’re used to. Thanks to @vaclisinc for this improvement.
January 15, 2025: Fixed an issue with the working directory. Now you can run Claude Code Remote from any folder on your computer, not just the one where you installed it. This makes setup more flexible. Credit goes to @vaclisinc for this fix.
January 14, 2025: Solved a problem where using the same email for sending and receiving notifications would create a loop of automatic replies. Now the tool recognizes its own messages and ignores them, preventing endless email chains. Thanks to @vaclisinc for this solution.

July 2025

July 28, 2025: Removed hardcoded settings and switched to environment-based configuration. This means all your settings (like email addresses and passwords) are stored in a single, easy-to-edit file, making it simpler to set up and change your preferences. Thanks to @kevinsslin for this update.

What’s Coming Next (TODO List)

The team behind Claude Code Remote has big plans for the future. Here are some features you can look forward to:

More Notification Channels

Discord & Telegram Integration: Soon, you’ll be able to get notifications and send commands through popular messaging apps like Discord and Telegram, not just email. This gives you even more ways to stay connected to your Claude sessions.
Slack Workflow: A native Slack app with special commands (like typing /claude to send a message) is in the works. This will make it easy to integrate Claude Code into your team’s Slack workflow.

Better Developer Tools

Support for More AI Tools: The tool will soon work with other AI coding assistants, like Gemini CLI and Cursor. This means you can control multiple AI tools remotely with the same system.
Git Automation: Imagine Claude not only writing code but also automatically committing changes to Git, creating pull requests, or managing branches—all triggered by your email commands. That’s what the team is working on next.

Usage Analytics

Cost Tracking: Keep an eye on how many tokens you’re using with Claude and get estimates of associated costs. This helps with budgeting and understanding your usage patterns.
Performance Metrics: See how long tasks take to complete and how many resources they use. This can help you optimize your workflow.
Scheduled Reports: Get daily or weekly summaries of your Claude usage sent to your email. Perfect for tracking progress over time.

Native Apps

Mobile Apps: iOS and Android apps are planned, making it even easier to control Claude Code from your phone with a dedicated interface.
Desktop Apps: Native apps for macOS and Windows will provide a more seamless experience for users who prefer desktop tools over email.

Step-by-Step Setup Guide

Setting up Claude Code Remote is straightforward. Just follow these steps, and you’ll be controlling Claude from your email in no time.

Step 1: Copy the Project and Install Requirements

First, you need to get the Claude Code Remote files onto your computer and install the necessary software. Here’s how:

Open your terminal (the program you use to run command-line instructions).
Copy the project from GitHub using this command:
```
git clone https://github.com/JessyTsui/Claude-Code-Remote.git
```
This creates a folder called Claude-Code-Remote on your computer with all the tool’s files.
Move into that folder with:
```
cd Claude-Code-Remote
```
Install the required dependencies (extra software the tool needs to work) with:
```
npm install
```
This might take a minute or two—just wait for it to finish.

Step 2: Set Up Your Email Settings

Next, you need to tell Claude Code Remote how to send and receive emails. This is done using a configuration file called .env.

First, make a copy of the example configuration file to use as your own. Run:
```
cp .env.example .env
```
This creates a new file called .env with placeholder settings.
Open the .env file in a text editor. You can use nano (a simple terminal editor) with:
```
nano .env
```
Or use your favorite editor (like VS Code, Vim, or Notepad++).

Now, you need to fill in the details in the .env file. Let’s go through each setting:

# Email account for sending notifications
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password    # Gmail: use App Password, not regular password

# Email account for receiving replies (can be same as SMTP)
IMAP_USER=your-email@gmail.com  
IMAP_PASS=your-app-password

# Where to send notifications
EMAIL_TO=your-notification-email@gmail.com

# Who can send commands (security whitelist)
ALLOWED_SENDERS=your-notification-email@gmail.com

# Path to session data (use absolute path)
SESSION_MAP_PATH=/your/absolute/path/to/Claude-Code-Remote/src/data/session-map.json

SMTP_USER & SMTP_PASS: These are for the email account that will send you notifications. SMTP is the system that handles sending emails. If you use Gmail, you can’t use your regular password here—you need to create an “App Password.” We’ll explain how to do that in a moment.
IMAP_USER & IMAP_PASS: These are for the email account that will receive your replies (so the tool can read your commands). This can be the same email as SMTP_USER. IMAP is the system that handles receiving emails.
EMAIL_TO: This is the email address where you want to receive notifications. It could be the same as your SMTP_USER or a different one (like your work email).
ALLOWED_SENDERS: This is a list of email addresses that are allowed to send commands. Only these emails can reply with instructions, keeping your setup secure. For now, you can just put your own email here.
SESSION_MAP_PATH: This is the location where the tool will store information about your Claude sessions. You need to use the “absolute path” (the full address on your computer) to the session-map.json file. For example, on a Mac, it might look like /Users/yourname/Documents/Claude-Code-Remote/src/data/session-map.json. On Windows, it might be C:/Users/yourname/Documents/Claude-Code-Remote/src/data/session-map.json.

Important for Gmail users: To get your App Password:

Go to your Google Account security settings.
Make sure 2-Step Verification is turned on (you’ll need this to create an App Password).
Under “Signing in to Google,” click “App Passwords.”
Select “Mail” as the app and your device, then click “Generate.”
Use the generated password (it will look like a series of letters) as your SMTP_PASS and IMAP_PASS.

Once you’ve filled in all the details, save the .env file. If you’re using nano, press Ctrl+O to save, then Ctrl+X to exit.

Step 3: Connect Claude Code to the Tool

Now, you need to tell Claude Code to send updates to Claude Code Remote when it finishes tasks. This is done by adding “hooks” to Claude’s settings.

First, make sure the folder where Claude stores its settings exists. Run:
```
mkdir -p ~/.claude
```
This creates a .claude folder in your home directory if it doesn’t already exist.
Open Claude’s settings file in a text editor:
```
nano ~/.claude/settings.json
```

Add the following configuration. Make sure to replace /your/absolute/path/ with the actual full path to your Claude-Code-Remote folder (the same path you used for SESSION_MAP_PATH earlier, but without the /src/data/session-map.json part):

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

What does this do? These “hooks” tell Claude to run a specific command when it finishes a task (“Stop”) or when a sub-task (like a smaller part of a larger task) finishes (“SubagentStop”). The command sends a notification to Claude Code Remote, which then emails you.

Save the file (same as before: Ctrl+O and Ctrl+X in nano).

Step 4: Test Your Setup

Before you start using the tool, it’s a good idea to test if everything is working. Run this command in your terminal:

node claude-remote.js test

This sends a test email to the address you set in EMAIL_TO. Check your inbox (and spam folder, just in case) for this email. If you receive it, great—your email settings are correct! If not, don’t worry—we’ll troubleshoot later.

Step 5: Start Claude Code Remote

Now it’s time to start the tool. You’ll need two terminal windows (or tabs) for this:

Terminal 1: Start Email Monitoring
This window will run the part of the tool that checks for new email replies (your commands) and sends notifications. Run:

npm run relay:pty

You should see a message like:

🚀 Claude Code Remote is running!
📧 Monitoring emails...

Leave this terminal window open—if you close it, the tool will stop working.

Terminal 2: Start Claude in tmux
Tmux is a tool that lets you run terminal sessions in the background, so Claude keeps working even if you close this terminal. Here’s how to use it:

Create a new tmux session (think of it as a separate workspace for Claude):
```
tmux new-session -s my-project
```
The -s my-project just names the session “my-project”—you can use any name you like.
Once you’re in the tmux session, start Claude Code as you normally would:
```
claude
```

Now Claude is running, and Claude Code Remote is monitoring for emails. You’re all set!

Step 6: Verify Everything Works

Let’s do a quick test to make sure the whole system is working:

In the tmux session (Terminal 2), type a simple command to Claude, like:
```
What is 2+2?
```
Wait for Claude to respond (it should say “4”).
Check the email address you set in EMAIL_TO. You should receive a notification that Claude completed the task.

If you get the email, congratulations—Claude Code Remote is working!

How to Use Claude Code Remote

Now that everything is set up, let’s look at how to use the tool in your daily workflow.

Understanding Email Notifications

When Claude finishes a task, you’ll get an email that looks something like this:

Subject: Claude Code Remote Task Complete [#ABC123]

Claude completed: "What is 2+2?"

[Claude's full response here...]

Reply to this email to send new commands.

The subject line tells you the task is complete and includes a unique ID (like #ABC123) to help track tasks.
The body includes a reminder of what the task was and Claude’s full response.
At the bottom, there’s a note that you can reply to send a new command.

Sending Commands via Email Reply

Sending a new command to Claude is as easy as replying to an email:

Open the notification email you received when Claude finished the last task.
Click “Reply” (just like you would for any other email).

Type your command in the body of the email. For example:

Please write a simple Python function that adds two numbers.

Send the email.

That’s it! Claude Code Remote will read your reply, send the command to Claude, and when Claude finishes, you’ll get another notification email with the result.

Advanced: Sending Complex Commands

You’re not limited to short commands—you can send long, detailed instructions with multiple lines. Here are some examples:

Multi-line Commands

First, explain how loops work in JavaScript.
Then, write a for loop that prints numbers from 1 to 10.
Finally, explain what each part of the loop does.

Detailed Instructions

Refactor the following code to be more efficient:

function calculateTotal(prices) {
  let total = 0;
  for (let i = 0; i < prices.length; i++) {
    total = total + prices[i];
  }
  return total;
}

Please:
- Use a more modern JavaScript feature
- Add comments explaining the changes
- Test the function with an example array like [2.99, 5.99, 9.99]

The tool will pass along the entire message to Claude, so feel free to be as detailed as you need.

How the Email Workflow Works

Let’s break down the full cycle to understand how everything connects:

You start a task: You (or Claude) finish a task in the tmux session.
Notification sent: Claude triggers the hook you set up, which tells Claude Code Remote to send you an email.
You reply with a command: You read the notification, hit reply, and type your next instruction.
Command processed: Claude Code Remote checks for new emails, finds your reply, and sends the command to Claude.
Claude works: Claude processes your new command in the tmux session.
Repeat: When Claude finishes, you get another notification, and the cycle continues.

It’s a simple, circular workflow that keeps your project moving forward, even when you’re not at your computer.

Which Email Clients Work?

You can use any email client that supports standard reply functionality. Here are some that work well:

Gmail (both the web version and mobile app)
Apple Mail (on iPhone, iPad, or Mac)
Outlook (web, desktop, or mobile)
Any other email app that can send and receive emails using SMTP/IMAP (most do!)

Common Use Cases

Claude Code Remote is flexible enough to fit into many different workflows. Here are some ways people are using it:

Remote Development

Imagine you start working on a project at the office. You set up a task in Claude, then have to leave for home. With Claude Code Remote, you can check the progress on your phone via email, reply with a new command to fix something Claude mentioned, and by the time you get home, the next part of the project is done. It turns your commute into productive time.

Long Tasks

Some coding tasks take time—like analyzing a large codebase, writing documentation, or debugging a complex issue. Instead of waiting at your computer, you can start the task, step away to attend a meeting or take a break, and get an email when it’s finished. You can even send follow-up commands while you’re away, so Claude is never idle.

Team Collaboration

If you’re working with a team, you can share access to Claude sessions by adding your teammates’ emails to the ALLOWED_SENDERS list. When Claude finishes a task, the notification goes to everyone, and any team member can reply with a command. It’s a simple way to collaborate on AI-assisted coding without everyone needing to be in the same place.

Useful Commands

Here are some handy commands to help you manage Claude Code Remote:

Test your email setup: Run node claude-remote.js test to send a test email. This is great for troubleshooting.
Check system status: Run node claude-remote.js status to see if the tool is running correctly and check for any errors.
Manage tmux sessions:
- tmux list-sessions shows all your active tmux sessions (so you can see if Claude is running).
- tmux attach -t my-project reconnects you to a session named “my-project” (replace with your session name).
Stop email monitoring: Just press Ctrl+C in the terminal window where you ran npm run relay:pty.

Troubleshooting: Common Issues and Fixes

Even with the best setup, things can sometimes go wrong. Here’s how to fix common problems:

Not Receiving Emails?

Run the test command: node claude-remote.js test will tell you if there’s a problem with your email settings. If the test fails, check the error message—it often gives clues (like a wrong password).
Check your spam folder: Some email providers mark automated emails as spam. If you find the test email there, mark it as “not spam” to ensure future notifications arrive in your inbox.
Verify your .env settings: Double-check that all email addresses are spelled correctly, and that your App Password (for Gmail) is accurate. Even a small typo can break things.
Check your internet connection: The tool needs internet to send and receive emails. Make sure your computer is connected.

Commands Not Executing?

Check the tmux session: Run tmux list-sessions to see if your session is still running. If not, restart it with tmux new-session -s my-project and start Claude again.
Verify allowed senders: Make sure the email you’re replying from is in the ALLOWED_SENDERS list in .env. If not, add it and restart the email monitoring (press Ctrl+C and run npm run relay:pty again).
Ensure Claude is running: In the tmux session, check that Claude is active and ready to receive commands. If it’s frozen, restart Claude.

Need More Help?

Check GitHub Issues: The Claude Code Remote Issues page has solutions to common problems other users have faced.
Follow for Updates: Follow @Jiaxi_Cui on Twitter for news, tips, and updates about the tool.

Security Features

You might be wondering: is it safe to control my coding tools via email? Claude Code Remote includes several security measures to protect your work:

Sender Whitelist: Only emails in the ALLOWED_SENDERS list can send commands. This means even if someone else gets your notification emails, they can’t send instructions unless you’ve approved their email.
Session Isolation: Each session (tmux session) is controlled by its own token, so commands only affect the session they’re meant for.
Auto Expiration: Sessions automatically time out after a period, so unused sessions don’t stay open indefinitely.

License

Claude Code Remote is released under the MIT License. This means you’re free to use, modify, and share the tool as long as you include the original license information. It’s open-source, so anyone can contribute to making it better.

Final Thoughts

Claude Code Remote is all about making your workflow more flexible. By letting you control Claude Code via email, it breaks down the barrier between your physical location and your coding projects. Whether you’re on the go, collaborating with a team, or just need to step away from your desk, you can stay connected to your work.

If you find the tool helpful, consider starring the GitHub repo—it helps more people discover it. And if you have a unique way of using Claude Code Remote, share it on Twitter and tag @Jiaxi_Cui—the community would love to see it!

With Claude Code Remote, your AI coding assistant is always within reach, no matter where you are.

Master Remote Development with Claude Code Remote: Email-Controlled AI Coding Assistant