claude-mail-bridge

Claude Mail Bridge

A remote control tool that keeps you connected with Claude Code even when you're away from your terminal.

How It Works

┌─────────────────┐         Email         ┌─────────────────┐
│                 │ ◄───────────────────► │                 │
│   Claude Code   │                       │   Your Email    │
│   (tmux)        │                       │   (phone/PC)    │
│                 │                       │                 │
└─────────────────┘                       └─────────────────┘
        │
        ├── Daemon listens for email replies
        ├── Hooks detect session state changes
        └── MCP provides presence & email capabilities

Email-powered remote control for Claude Code — approve permissions, shape AI behavior, and coordinate your team, all without touching the terminal.

Key Features

1. Email-Based Remote Control

Communicate with Claude Code running in your terminal via email from anywhere. Includes session context (project, branch, working directory, start time) and supports file attachments up to 15MB.

2. Remote Permission Approval

Approve Claude Code's permission requests remotely without blocking. The system automatically captures permission prompts, batches multiple requests together, and emails them with terminal context for informed decisions.

3. Complete AI Behavior Tuning

A three-layer system (MCP + Skills + Hooks) that shapes how Claude behaves:

• MCP Tools provide capabilities (presence, email, team management)
• Skills define behavior rules (when to use email, privacy protocols)
• Hooks trigger automatic responses (permission capture, session events)

4. Team Collaboration

Boost team communication efficiency by letting Claude Code coordinate with team members. Ask Claude to summarize project progress, notify the team, or delegate tasks - all with explicit privacy controls.

Why CMB?

CMB is designed for specific scenarios where real-time solutions may not be ideal:

Scenario	How CMB Helps
Unstable networks	Email works on weak 4G/5G connections that would break real-time streams
Offline-first	Emails queue and deliver when network returns - no need to watch continuously
Low bandwidth	Pure text transmission - minimal bandwidth requirements
Long-running tasks	Perfect for jobs that run for hours or days without constant monitoring
No extra infrastructure	Uses your existing email - no servers to deploy or maintain
Team collaboration	Email team members directly from Claude with attachments support

CMB works anywhere you have email access - on a plane, in a subway, or just without a stable internet connection.

Installation

1. Install Package

pip install claude-mail-bridge

Manual Install from GitHub

If you prefer to install from the source code:

# Clone the repository
git clone https://github.com/CodingJay-1/claude-mail-bridge.git
cd claude-mail-bridge

# Build the package
pip install build
python -m build

# Install the built wheel
pip install dist/claude_mail_bridge-*.whl

2. Set Environment Variable

SMTP password is configured via environment variable for security:

# Add to ~/.bashrc or ~/.zshrc
export CMB_SMTP_PASSWORD='your_smtp_password'

Getting SMTP Password:

• QQ Mail: Settings → Account → POP3/SMTP Service → Generate authorization code
• Gmail: Account → Security → 2-Step Verification → App passwords

3. Run Setup Wizard

claude-mail-bridge setup

Follow the prompts to enter:

• System Email: Email used for sending/receiving messages (e.g., your_bot@qq.com)
• Email Provider: QQ Mail / Gmail / Custom
• SMTP Password: Already set via environment variable
• Receiver Email: Your personal email to receive Claude's messages
• Your Alias: Display name (optional)
• Machine Name: Identifier for this machine (shown in email subjects)

Configuration will be saved to ~/.claude-mail-bridge/config.json

4. Install Claude Code Plugin

claude-mail-bridge install-claude-plugin

This installs:

• Hooks: Session start/stop, permission request hooks
• MCP Servers: Presence management, email communication, team management
• Skills: Claude's behavior guidelines

5. Start the Daemon

claude-mail-bridge start

Usage

Basic Commands

# Start daemon
claude-mail-bridge start

# Stop daemon
claude-mail-bridge stop

# Show status
claude-mail-bridge status

# Set presence status
claude-mail-bridge presence set online   # At terminal
claude-mail-bridge presence set away     # Away from terminal

# Get current presence
claude-mail-bridge presence get

# Test email functionality
claude-mail-bridge test-email

# Uninstall plugin
claude-mail-bridge uninstall

How to Trigger Remote Control

Claude Code automatically loads installed MCP services and skills. Just express yourself naturally:

Tell Claude you're leaving (triggers status switch to away):

"I'm leaving" / "我要走了"
"I'm going" / "我先走了"

Tell Claude you're back (triggers status switch to online):

"I'm back" / "我回来了"
"I'm at the terminal" / "我在电脑前了"

Request email communication directly:

"Email me the results"
"Contact me via email" / "邮件联系"

When your status is away, Claude will automatically:

• Report progress via email
• Ask for important decisions via email
• Wait for your email replies to continue execution

Presence Status Behavior

Status	Claude's Behavior
online	Normal interaction, direct communication
away	Email communication, progress reports, decision requests

Team Member Management

# Add team member
claude-mail-bridge teammates add teammate@example.com --alias "John"

# List team members
claude-mail-bridge teammates list

# Remove team member
claude-mail-bridge teammates remove teammate@example.com

Have Claude email team members:

"Email John and tell him..."
"Notify the team..."
"Summarize progress and send to Sarah..."

MCP Tools Reference

Claude Code can use the following MCP tools:

Presence System

Tool	Function
mcp__presence_system__get_presence	Get user's current online status
mcp__presence_system__set_presence	Set user's online status (online/away)
mcp__presence_system__set_dnd_mode	Set do-not-disturb mode

Email System

Tool	Function
mcp__email_system__mail_user_and_wait	Send email to user and wait for reply
mcp__email_system__mail_teammates	Send email to team members

Team System

Tool	Function
mcp__team_system__add_to_teammates	Add team member
mcp__team_system__get_teammates_list	Get team member list
mcp__team_system__remove_from_teammates	Remove team member

Skills Reference

Claude Code automatically invokes these skills based on context:

Skill	Trigger
claude-mail-bridge-init	Remote control keywords detected or session ends
claude-mail-bridge-wakeup	Wakeup message received
claude-mail-bridge-team_rules	Need to email team members

Workflow Example

1. Tell Claude you're leaving:

   You: "I'm leaving, monitor the test results and email me if there are issues"
   

2. Claude detects away status, automatically reports via email

3. You reply via email:

   Continue
   

   or

   Skip this test
   

4. Claude receives your reply, continues the task

Configuration File

Configuration saved at ~/.claude-mail-bridge/config.json:

{
  "cmb_email": {
    "smtp_host": "smtp.qq.com",
    "smtp_port": 465,
    "imap_host": "imap.qq.com",
    "imap_port": 993,
    "user": "your_bot@qq.com"
  },
  "receiver_email": "your_personal@gmail.com",
  "receiver_alias": "Your Name",
  "machine_name": "workstation",
  "teammates_mail_list": [
    {"email": "teammate@example.com", "alias": "John"}
  ]
}

Note: SMTP password is configured via CMB_SMTP_PASSWORD environment variable, not stored in config file.

Logs

Log file location: ~/.claude-mail-bridge/logs/daemon.log

Tested Platforms

Email Providers

Provider	Status	Notes
QQ Mail	✅ Tested	Fully verified
Gmail	🔶 Untested	Community feedback needed
163 Mail	🔶 Untested	Community feedback needed
126 Mail	🔶 Untested	Community feedback needed
Outlook	🔶 Untested	Community feedback needed

Operating Systems

OS	Status	Notes
Linux	✅ Tested	Primary development platform
macOS	🔶 Untested	Should work, needs verification
Windows	🔶 Untested	Needs testing

Contributions welcome! If you've tested CMB on other platforms, please share your experience.

Troubleshooting

Not receiving emails?

1. Check if daemon is running: claude-mail-bridge status
2. Check logs: tail -f ~/.claude-mail-bridge/logs/daemon.log
3. Test email functionality: claude-mail-bridge test-email

Claude not triggering remote control?

Ensure plugin is installed:

claude-mail-bridge install-claude-plugin

Check if MCP services are registered:

claude mcp list

You should see presence_system, email_system, team_system.

Development

# Clone repository
git clone https://github.com/your-repo/claude-mail-bridge.git
cd claude-mail-bridge

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

License

MIT License